pytest-asyncio

pytest-asyncio is a pytest plugin that makes it possible to write coroutine test functions and have pytest execute them correctly — no manual event-loop boilerplate required. Marking a test @pytest.mark.asyncio (or enabling the asyncio_mode = auto config option) lets you await code inside the test body just like you would in application code, and pytest-asyncio takes care of driving the event loop and running the coroutine to completion.

Maintained under the pytest-dev organization alongside pytest itself, it’s the de facto standard way to test asyncio-based Python code with pytest, supporting async fixtures with configurable scope (function, module, session), parametrized event loops, and custom loop factories. It explicitly does not support unittest.TestCase subclasses, pointing users instead to unittest.IsolatedAsyncioTestCase or an async-aware test framework for that case.

What You Get

• pytest.mark.asyncio to mark individual coroutine functions as pytest test items
• An asyncio_mode = auto configuration option that treats every async def test/fixture as async automatically, without per-test markers
• Async fixtures with configurable scope (function, class, module, session) via @pytest_asyncio.fixture
• Support for custom event loop factories and parametrized event loop configurations across a test session
• Integration with pytest’s existing fixture, parametrization, and collection machinery so async tests behave like any other pytest test

Common Use Cases

• Unit and integration testing of asyncio-based application code (async web frameworks, async DB clients, async task queues)
• Testing async context managers and async generators used as pytest fixtures with proper setup/teardown scoping
• Running the same async test logic against multiple event loop configurations via parametrization
• Migrating a codebase from manual asyncio.run()-wrapped tests to native async def test functions

Under The Hood

Architecture — The entire plugin lives in a single, focused module, pytest_asyncio/plugin.py (1,140 lines), which hooks into pytest’s collection and fixture machinery to detect async def test functions and fixtures, wrap them in an event loop runner, and manage loop lifecycle/scope so fixtures and tests sharing a scope share the same running loop. __init__.py exposes the small public surface (fixture, marker registration) that users actually import.

Tech Stack — Pure Python with pytest as its only required dependency (plus typing-extensions on older Pythons), designed to work with any asyncio-based code without also depending on a specific async framework (no forced dependency on Tornado, Trio, etc.) — it strictly targets Python’s built-in asyncio.

Code Quality — Exceptionally thorough test suite: 37+ test modules covering markers, fixture scopes (tests/modes/), event loop factories, subprocess handling, doctest support, Hypothesis-based property tests, and even task-cleanup edge cases — unusually deep coverage for a plugin of this size, backed by Codecov reporting and CI across supported Python versions. py.typed is shipped, signaling committed type-hint support for consumers.

API Design — The @pytest.mark.asyncio / asyncio_mode=auto split is a deliberate ergonomics choice: teams can opt into per-test explicitness or blanket-enable async support project-wide once they’ve standardized on it. The README is upfront about a real limitation (no support for unittest.TestCase subclasses) rather than leaving users to discover it via a confusing failure, which meaningfully shortens the debugging loop for newcomers.