rstest

Runs most pytest suites unchanged, in parallel. Same fixtures, same plugins, parallel by default, with built-in suite diagnostics (--doctor) that tell you where your test time actually goes. How much faster depends on your suite's shape (self-check below).

Note: This is the Python test runner on PyPI (pip install rstest). It is not related to the Rust fixture crate rstest on crates.io.

_{aiohttp's suite: pytest 193s → rstest 67s on a warm cache, then --doctor shows where the time goes. Recorded at -n auto (14 workers); the suite gains nothing past 8, so the tables below use -n 8.}

📚 Full documentation → python-rstest.readthedocs.io

Quick start

In any pytest project:

pip install rstest      # or: uv pip install rstest
rstest

Also works with your tool of choice:

uv add --dev rstest           # uv projects
poetry add --group dev rstest # Poetry
pdm add -dG test rstest       # PDM

Install rstest into the same environment as your tests: workers run in that interpreter. A pipx / uv tool install alone can't run your tests; it only puts rstest on your PATH (details).

Requires Python 3.10+ on macOS (Apple silicon), Linux, or Windows (Windows is validated at a smaller scale than macOS/Linux). rstest is alpha (0.x): expect breaking changes between minor versions until 1.0.

No config and no test changes needed: rstest runs your pytest suite in parallel (-n auto) out of the box. As with pytest-xdist, session-scoped fixtures run once per worker, not once per run.

• Tests that can't run in parallel (shared files, ports, databases) → @pytest.mark.serial (run exclusively, after the parallel phase).
• Tests that depend on order within a file → --dist loadfile (keeps each file's tests on one worker); across files → rstest -n 0.
• Want pytest's exact behavior → rstest -n 0 (single-worker mode: one pytest session, per-test outcomes match pytest exactly).

Will rstest speed up your suite?

The wins come from suite shape, not magic. Quick self-check:

Two more things to know before you benchmark:

• Warm cache matters. Duration-aware scheduling needs one run of timing data. First run is cold; the win arrives on run two. In ephemeral CI, persist .rstest_cache or expect cold-run timing.
• Adopting rstest adopts pytest 9, whatever pytest you have installed (details).

Fastest way to find out for real: rstest try compares a plain pytest run with rstest -n auto and reports parity and speed, with no config (how it works).

Benchmarks

Real open-source suites, end-to-end, with per-test outcome diffing against the pytest baseline: 100% parity on pandas, django-allauth and rich in the measured run (allauth and rich have tests that flake under plain pytest too, so some runs land at ~99.8-99.9%), and 99.91-99.98% on aiohttp, whose socket-leak warning flake hits xdist too (every known flake is catalogued in the docs).

Apple M4 Max, CPython 3.13, pytest-xdist 3.8, median of 5 runs at the same -n for both runners. CPU-bound suites (sympy, scikit-learn) land at parity with xdist; see the benchmarks page.

Monorepo (langchain-ai/langgraph, the 5 libs/* packages that need no live services, 838 tests, each with its own pytest config; a single pytest can't run from the root at all):

Same method as above (median of 5, rstest -n auto). One of the five packages, libs/sdk-py, collects no tests under either runner in the benchmark venv (a missing test dependency), so the 838 tests come from the other four.

Full methodology: benchmarks.

Why rstest

• Your tests, unchanged. A vendored pytest 9.1.1 core runs your conftest hierarchies, fixtures, parametrize, marks, and installed plugins (pytest-django, pytest-asyncio, hypothesis, pytest-mock, ...) as pytest does. Most pytest flags (-k, -m, -x, --lf, plugin flags) forward unchanged; a few, such as --timeout, --reruns and --html, are rstest's own with the same basic syntax as the plugins they replace.
• xdist semantics in parallel. Session fixtures run once per worker, as under pytest-xdist, plus a short list of differences.
• Parallel by design. Work distribution across worker processes, duration-aware scheduling that starts your slowest tests first (per test, or per file when a large suite gets lazy collection), and safety rails for tests that can't parallelize (@pytest.mark.serial, --dist loadfile).
• Crash-safe. A segfaulting test costs you one FAILED line: the worker is replaced, its remaining tests redistribute, and the run completes.
• rstest --doctor. Tells you why the suite is slow: tests that wait instead of compute, the long-pole tests that cap any parallelism, fixture hotspots, slowest files.
• rstest --watch. Reruns on save; changed test files rerun alone, source changes rerun only the tests the import graph says are affected.

Compatibility contract. At -n 0 (single-worker mode) per-test outcomes match pytest exactly, and any difference is a bug (except for the few flags rstest shares with pytest or a plugin, which rstest handles itself at every worker count). In parallel, outcomes are preserved for parallel-safe tests, with the same caveats as pytest-xdist and a few report plugins that go quiet. Details: Compatibility and Known gaps.

rstest --doctor

Runs your suite, then answers where does the time actually go?, from data the runner already owns (per-test wall/CPU time, per-fixture setup):

================== rstest doctor ==================
4442 tests, 185.8s test time (wall 67.7s, 8 workers)

WAIT-BOUND: 95% of test time (176.5s) is waiting, not computing (sleeps / IO / timeouts).
    54.20s waiting of   54.25s  tests/test_proxy_functional.py::test_proxy_https_multi_conn_limit
    10.97s waiting of   10.97s  tests/test_proxy_functional.py::test_proxy_https_connect
  ... and 27 more

PARALLEL FLOOR: the longest test (54.2s) exceeds the ideal per-worker share (23.2s at -n 8);
no worker count can finish faster than its longest test. Gate tests:
    54.25s  tests/test_proxy_functional.py::test_proxy_https_multi_conn_limit

FIXTURE HOTSPOTS (setup time across all workers):
     0.79s   4442x  scope=function blockbuster
     0.54s    157x  scope=function transport

SLOWEST FILES:
   150.46s (81.0%)  tests/test_proxy_functional.py
     8.60s ( 4.6%)  tests/test_client_functional.py
===================================================

That's aiohttp's real suite: one file is 81% of total test time, almost all of it waiting on 10-second proxy timeouts. (Doctor counts tests with a recorded call duration, so skipped tests drop out: 4442 here against the 4,469 collected.) More →

Docs

• Getting started
• Evaluating rstest: what it speeds up, when not to adopt, and what switching costs
• Migrating from pytest
• Migrating from pytest-xdist
• Parallel safety
• Suite diagnostics (--doctor)
• Watch mode
• CI quickstart
• CLI reference
• Troubleshooting
• Agent skills: rstest install-skills or the Claude Code plugin

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.