rstest

Runs most pytest suites unchanged, in parallel, usually faster. Same fixtures, same plugins: byte-exact per-test outcomes at -n 0, and in parallel the same caveats as pytest-xdist (see Known gaps). Rust-orchestrated, parallel by default, with built-in suite diagnostics (--doctor) that tell you where your test time actually goes.

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, 4,469 tests:   pytest 193s  →  rstest 67s warm (150s cold), -n 8

_{Same suite: pytest 193s → rstest 67s (warm, -n auto = 14 workers, as recorded); --doctor shows where the time goes. Current measured numbers: benchmarks.}

📚 Full documentation → python-rstest.readthedocs.io

Quick start

Evaluating rstest? Run rstest try first: it runs your suite under plain pytest and under rstest, then tells you whether outcomes match and how much faster rstest was (details).

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 also needs rstest in the project environment; see Installation.)

Requires Python 3.10+ on macOS, Linux, or Windows. Windows runs the full test gate in CI, but the 33-suite public corpus runs only on macOS/Linux, so Windows is validated at a smaller scale. 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, each worker is a separate process, so session- and module-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 byte-exact pytest semantics → rstest -n 0 (single 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. rstest runs a vendored pytest 9.1.1 core. A suite that's warning-clean on recent pytest 8.x is almost always already pytest-9-clean; if not, clear deprecations first (the same upgrade you'd owe pytest anyway). rstest -n 0 surfaces them. Plugins run on that core too, so a plugin's pytest<9 pin is inert (details).

Fastest way to find out for real: rstest try runs your suite under plain pytest and under rstest -n auto, then reports whether outcomes match and how much faster rstest was. No migration, no config. (It runs the baseline as python -m pytest, so pytest must be installed in the project's environment for this one command.)

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, 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, 6 libs/* packages, 4,284 tests, each with its own pytest config; a single pytest can't run from the root at all):

Only the cold run is measured. From its per-project duration caches, a warm run is projected (not measured) at 121–133s (6.6–7.3×); discount that until you measure your own.

Full methodology: benchmarks.

Why rstest

• pytest underneath. Forwards the pytest flag surface; runs conftest, fixtures, parametrize, marks, and pytest plugins (pytest-django, pytest-asyncio, hypothesis, …) through a vendored pytest core.
• Parallel by design. Duration-aware work distribution that starts the slowest tests first (per test, or per file when a large suite gets lazy collection); @pytest.mark.serial and --dist loadfile safety rails; crashed workers respawn without losing your run.
• rstest --doctor. Wait-bound tests, parallel-floor analysis, fixture hotspots, slowest files.
• rstest --watch. Instant reruns on save; changed test files rerun alone, source changes rerun only the tests the import graph says are affected.

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 33 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
• Migrating from pytest
• Migrating from pytest-xdist
• Parallel safety
• Suite diagnostics (--doctor)
• Watch mode
• CI quickstart
• CLI reference

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.