docs(how-to): Add guide for isolating async applications in tests#1519
Open
AreteDriver wants to merge 1 commit into
Open
docs(how-to): Add guide for isolating async applications in tests#1519AreteDriver wants to merge 1 commit into
AreteDriver wants to merge 1 commit into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
appobject and overriding dependencies. Two subtle isolation traps repeatedly bite production codebases:importlib.reloadcreates a new app instance, but other test modules hold stale references to the old one through module-level imports.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 guidedocs/how-to-guides/isolate_async_apps_example.py— runnable examplesdocs/how-to-guides/index.rst— add entry to toctreeVerification
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.