pytest-replay

What it is and what it does

pytest-replay is a pytest plugin that solves the problem of reproducing test failures that occur only under specific execution orders in parallel test runs. When pytest-xdist runs tests across multiple workers, the order is non-deterministic, making it nearly impossible to recreate a flaky failure locally. This plugin records the exact sequence of test node IDs, start times, finish times, and outcomes for each worker into JSON files, then allows you to replay that exact sequence later.

The plugin records metadata including test start and finish times, which helps identify race conditions and timing-dependent failures. It supports replaying single or multiple worker files in parallel (with xdist installed), and provides a `replay_metadata` fixture to capture additional context needed for reproducibility, such as random seeds. The recorded files are JSON-based and remain readable even if a test crashes, addressing a limitation of pytest's built-in cache.

Use it for:

• Reproduce a flaky test failure seen in CI by downloading the replay file and running it locally with the same test order.
• Debug race conditions in concurrent tests by analyzing timing data and test execution sequences across workers.
• Replay an entire multi-worker CI run locally to verify a fix without waiting for the full CI pipeline.
• Capture and store random seeds or other metadata needed to make non-deterministic tests reproducible.
• Analyze which tests ran before a crash to narrow down the cause of a sudden failure.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that records test execution order and timing from parallel test runs, then replays them in the same sequence to reproduce flaky or non-deterministic failures.

Yes. This is a focused, low-friction tool that directly solves a real pain point in parallel testing. It has no security vulnerabilities, a permissive license, active maintenance, and a single lightweight dependency. Install it if you use pytest-xdist and encounter flaky or order-dependent test failures.

Install

pytest-replay on PyPI

pip install pytest-replay

uv add pytest-replay

poetry add pytest-replay

Installing pytest-replay

Before you install

Installs cleanly with only pytest as a dependency. Actively maintained with recent releases; last commit on 2026-08-03 and latest release on 2025-12-23.

License in practice

MIT license is permissive; you can use, modify, and distribute this package with minimal restrictions.

Quickstart

pip install pytest-replay

# Record test execution order during parallel run:
pytest -n auto --replay-record-dir=build/tests/replay

# Replay tests in the same order:
pytest --replay=.pytest-replay-gw0.txt

pytest must be installed; pytest-xdist is required for parallel replay of multiple files.

Verify before relying

• Whether the plugin works correctly with all pytest plugins and fixtures in real-world test suites.
• Performance overhead of recording and replaying large test runs.

Package facts

Evidence: pytest_replay-1.7.1-py3-none-any.whl

Tags

More Testing packages