rstest

Run your existing pytest suite in parallel, unchanged. Same fixtures, same plugins, same outcomes — just faster. Rust-orchestrated, parallel by default, with built-in suite diagnostics (--doctor) that tell you where your test time actually goes.

aiohttp, 4,469 tests:   pytest 197s  →  rstest 68s warm (151s cold)

📚 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 rstest           # uv projects
poetry add rstest       # Poetry
pdm add rstest          # PDM
pipx install rstest     # isolated CLI install

No config. No test changes. If pytest runs it, rstest runs it — in parallel (-n auto), out of the box.

• Tests that can't run in parallel → @pytest.mark.serial (run exclusively, after the parallel phase).
• Order-dependent suites → --dist loadfile.
• Want byte-exact pytest semantics → rstest -n 0 (single pytest session).

Will rstest speed up your suite?

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

Two more truths worth knowing 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.

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.

Benchmarks

Real open-source suites, end-to-end, with per-test outcome diffing against the pytest baseline — 100% parity on the measured run (a few tests flake under plain pytest itself; those are catalogued in the docs).

Apple Silicon, CPython 3.13, pytest-xdist 3.8.

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):

The cold run is measured. The warm figure is a projection, not a recorded run — the cold run's per-package duration caches predict where the planner lands once warm, so it carries no parity number. Discount it until you measure your own.

Full methodology: benchmarks.

Why rstest

• Drop-in. 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. Test-granular work distribution with duration-aware scheduling; @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
  ... 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.

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

SLOWEST FILES:
   150.46s (81.0%)  tests/test_proxy_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. 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.