Keep the failed run, not just its traceback.

The problem with another rerun

A traceback identifies where a test failed. Logs can show the values someone thought to print in advance. Neither necessarily preserves the external responses, timing-related values or Python state that led to the failure. When a flaky test passes on a rerun, the original execution is already gone.

Retrace records supported Python boundary interactions and execution ordering while the test runs. The result is a .retrace artifact. During replay, the Python code executes against recorded results, allowing the original run to be inspected instead of attempting a fresh reproduction. The recording has to exist before the failure occurs.

Try the public pytest quickstart

The Retrace pytest quickstart includes an intentionally failing checkout test. It uses Python 3.12, a virtual environment and an explicit Retrace runner. From a clean checkout:

git clone https://github.com/retracesoftware/retracesoftware.git
cd retracesoftware/quickstart
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install retracesoftware -r requirements.txt
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m retracesoftware \
  --recording recordings/pytest.retrace -- -m pytest pytest_demo -q --tb=short

The test is meant to fail. Check that recordings/pytest.retrace was created; its presence matters more than the nonzero pytest exit status. The quickstart’s failure concerns a checkout calculation in which tax is computed before a loyalty discount changes the taxable amount. The demo also uses time, UUID and random values that would normally change between runs.

Replay and inspect the same execution

The full walkthrough shows how to extract and replay the recording in a terminal:

./recordings/pytest.retrace --extract
ROOT_PID=$(python -m retracesoftware --recording recordings/pytest.retrace --list_pids | head -1)
./recordings/pytest.d/${ROOT_PID}.bin

For an interactive investigation, open the quickstart folder in VS Code, install the Retrace Debug Extension published by RetraceSoftware, open the .retrace file in the Retrace view, and set a breakpoint in pytest_demo/checkout.py. The documented workflow lets you inspect variables and the call stack, step forward, and step backwards through the recorded Python execution. See the VS Code guide.

A CI job can upload the .retrace file as an ordinary build artifact after failure. Download that artifact to a compatible local environment to investigate the recorded run. The repository README contains a GitHub Actions example. Treat recordings as potentially sensitive: their captured inputs and responses may include application data.

What this changes—and what it does not

An ordinary rerun invokes the live test again; its clock, randomness, files, service responses or scheduling may differ. Replay uses the previously captured supported interactions. This helps answer which Python branch executed and what state was present in that run. It does not reconstruct a run that was never recorded, and it is not a general snapshot of every remote service or native component.

This is a controlled preview workflow. The public quickstart uses Python 3.12 and VS Code. Pytest plugin loading is deliberately disabled for the demo; broader plugin combinations and threading support have caveats. The current compatibility notes and a trial on your own workload matter more than a general compatibility claim. Replay also needs a compatible Python environment and the relevant source and dependencies.

For the recording model behind this workflow, read how Python record-replay works. If you have a failing test that remains difficult to explain, discuss the investigation with the team.