Skip to content

docs(how-to): Add guide for isolating async applications in tests#1519

Open
AreteDriver wants to merge 1 commit into
pytest-dev:mainfrom
AreteDriver:docs/isolate-async-apps-guide
Open

docs(how-to): Add guide for isolating async applications in tests#1519
AreteDriver wants to merge 1 commit into
pytest-dev:mainfrom
AreteDriver:docs/isolate-async-apps-guide

Conversation

@AreteDriver

Copy link
Copy Markdown

Summary

Adds a new how-to guide demonstrating two common failure modes when testing async applications (e.g., FastAPI, Quart, aiohttp) with pytest-asyncio, and how to fix them using fixture-scoped imports and temporary directory overrides.

Motivation

Testing async web frameworks often involves importing an app object and overriding dependencies. Two subtle isolation traps repeatedly bite production codebases:

  1. Stale app reference via module-level importimportlib.reload creates a new app instance, but other test modules hold stale references to the old one through module-level imports.
  2. Default path leak — An app or service with a default file-system path in its constructor writes state that bleeds across tests.

pytest-asyncio's fixture scoping makes these easy to prevent, but the failure modes aren't well documented anywhere in the asyncio ecosystem.

Scope

  • docs/how-to-guides/isolate_async_apps.rst — the guide
  • docs/how-to-guides/isolate_async_apps_example.py — runnable examples
  • docs/how-to-guides/index.rst — add entry to toctree

Verification

The example code passes on pytest-asyncio 0.24+ with FastAPI as the demo framework (any async web framework exhibits the same pattern). Both failure modes are reproduced with failing assertions, then fixed.


Author's note: These patterns were extracted from production test suites (github.com/AreteDriver/animus and github.com/AreteDriver/BenchGoblins). Happy to adjust to match project conventions.

Adds a new how-to guide covering two common failure modes when testing
async web frameworks (FastAPI, Quart, aiohttp) with pytest-asyncio:

1. Stale module-level imports after reload — importlib.reload creates a new
   app instance, but other test modules hold stale references. Fix: import
   inside the fixture or test function.

2. Default file-system path leaks — services with optional path arguments
   reuse the same default directory across tests. Fix: always inject a
   temporary directory via a fixture.

Includes runnable example code (pytest) demonstrating both traps and fixes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant