Pytest Trio Plugin

0.8.0 · active · verified Tue Apr 14

pytest-trio is a pytest plugin designed to facilitate testing projects that leverage Trio, a friendly library for concurrency and async I/O in Python. It enables writing asynchronous tests without boilerplate, provides useful Trio-specific fixtures like `nursery` and `autojump_clock`, and supports async fixtures. The current stable version is 0.8.0, and it follows a release cadence tied to Trio and pytest compatibility updates.

Warnings

breaking If a `yield` in an async fixture (decorated with `@pytest.fixture` or `@pytest_trio.trio_fixture`) is cancelled, it will raise `trio.Cancelled` and teardown code after the `yield` might not execute. This differs significantly from standard pytest fixtures where `yield` never raises an exception. Ensure critical cleanup is in a `finally` block.
Fix: Wrap teardown logic in a `finally` block within your async fixtures to guarantee execution, e.g., `try: yield; finally: await cleanup()`.
breaking Trio 0.22.0 deprecated `trio.MultiError` in favor of Python's standard `BaseExceptionGroup` (PEP 654). `pytest-trio` 0.8.0 has been updated to use `ExceptionGroup` exclusively, requiring `trio>=0.22.0`. Older versions of `pytest-trio` with newer `trio` might encounter deprecation warnings or compatibility issues.
Fix: Ensure `trio` is updated to `0.22.0` or later. If catching exceptions, prefer `ExceptionGroup` over `MultiError`.
gotcha Without `trio_mode = true` in `pytest.ini`, `pytest-trio` only processes tests and fixtures explicitly marked with `@pytest.mark.trio` or `@pytest_trio.trio_fixture`. This can lead to async tests being skipped or not running correctly if not explicitly marked.
Fix: For projects exclusively using Trio, set `trio_mode = true` in `pytest.ini`. Otherwise, consistently use `@pytest.mark.trio` on all Trio-dependent tests and async fixtures.
gotcha `pytest-trio` runs `trio.run()` for each individual test, creating a fresh Trio environment. This differs from how standard pytest fixtures might be set up once for multiple tests, and can occasionally surprise users expecting a single shared Trio event loop across a test module or class.
Fix: Design tests to be atomic and independent, relying on fixtures to provide isolated setup/teardown for each test run. Be mindful that global state managed outside of Trio fixtures might not persist across tests as expected.
breaking Support for Python 3.5 and 3.6 was removed in older versions of `pytest-trio`. Current versions require Python 3.7 or newer.
Fix: Upgrade to Python 3.7 or a newer supported version.
gotcha There are reports that `pytest-trio` tests may fail with `pytest` 8.4 due to empty tracebacks when the plugin raises an exception directly. This indicates a potential compatibility issue with newer `pytest` versions.
Fix: Monitor `pytest-trio`'s GitHub issues for updates or consider pinning `pytest` to a version prior to 8.4.2 if encountering this issue.

Install

pip install pytest-trio Install stable version

Imports

pytest.mark.trio
```
import pytest

@pytest.mark.trio
async def test_something():
    ...
```
Used to explicitly mark an async test function or fixture that uses Trio. Can be omitted if 'trio_mode = true' is set in pytest.ini.
pytest_trio.trio_fixture
```
from pytest_trio import trio_fixture

@trio_fixture
async def my_fixture():
    ...
```
Decorator to explicitly mark an async fixture as a Trio fixture, ensuring it runs within the Trio event loop.
nursery
```
async def test_with_nursery(nursery):
    await nursery.start(some_task)
```
A built-in fixture provided by pytest-trio for managing background tasks.
autojump_clock
```
async def test_with_clock(autojump_clock):
    await trio.sleep(1)
```
A built-in fixture that provides a mock clock, useful for testing time-sensitive code without real-time delays.

Quickstart

To quickly get started, create a `pytest.ini` file in your project root with `trio_mode = true`. This enables Trio support for all async tests. Then, write `async def` test functions. `pytest-trio` automatically provides useful fixtures like `nursery` for managing background tasks.

# pytest.ini
[pytest]
trio_mode = true

# test_example.py
import trio

async def test_sleep():
    start_time = trio.current_time()
    await trio.sleep(0.01) # Use a small sleep for quick tests
    end_time = trio.current_time()
    assert end_time - start_time >= 0.01

async def test_should_pass_with_fixture(nursery):
    results = []
    async def background_task():
        await trio.sleep(0.001)
        results.append('done')
    nursery.start_soon(background_task)
    await trio.sleep(0.002) # Ensure background task has time to run
    assert 'done' in results

# Run with: pytest test_example.py

view raw JSON →