Install & Compatibility
Where this runs
tested against v0.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.470s · 36.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.3s · import 0.415s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
pytest --version
Debug
Known issues
breakingIf 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.fixWrap teardown logic in a `finally` block within your async fixtures to guarantee execution, e.g., `try: yield; finally: await cleanup()`.
affects: >=0.6.0
breakingTrio 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.fixEnsure `trio` is updated to `0.22.0` or later. If catching exceptions, prefer `ExceptionGroup` over `MultiError`.
affects: All versions, especially when paired with Trio <0.22.0 or trying to catch `MultiError`.
gotchaWithout `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.fixFor 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.
affects: All versions
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.fixDesign 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.
affects: All versions
breakingSupport for Python 3.5 and 3.6 was removed in older versions of `pytest-trio`. Current versions require Python 3.7 or newer.fixUpgrade to Python 3.7 or a newer supported version.
affects: 0.7.0 and later
gotchaThere 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.fixMonitor `pytest-trio`'s GitHub issues for updates or consider pinning `pytest` to a version prior to 8.4.2 if encountering this issue.
affects: `pytest-trio` 0.8.0 with `pytest` >= 8.4.2
Upgrade
Version history
0.8.0latest on PyPI · released Nov 1, 2022
Audit
Dependencies
pytestrequiredCore testing framework.
triorequiredAsynchronous I/O framework.
outcomerequiredUsed for handling results of coroutines and generators.