Record, replay, and rerun¶
Experimental: This feature is not yet stable
- Enable with: Add
[experimental]withrecord = trueto~/.config/nextest/config.toml, or setNEXTEST_EXPERIMENTAL_RECORD=1in the environment - Tracking issue: TBD
Nextest supports recording test runs to rerun failing tests, and to replay them later. Recorded runs are stored locally in the system cache.
Recorded test runs capture:
- Test statuses (pass, fail, etc) and durations.
- Outputs for all tests, both failing and successful. (If
--no-captureis passed in at the time the run is recorded, test output cannot be captured.)
Use cases¶
- Rerunning tests that failed or were not run in the past, with the goal being to iteratively converge towards a successful test run.
- Replaying test runs, including those that might have aged past terminal scrollback.
In the future, it will be possible to:
- Publish archives in CI that can be replayed locally.
- Export replayed test runs in various formats such as JUnit and libtest-json output.
Usage¶
To enable recording in user configuration:
~/.config/nextest/config.toml[experimental]
record = true
[record]
enabled = true
Now, all future cargo nextest run instances will automatically be recorded.
Rerunning failed tests¶
When the recording feature is enabled, you can rerun failing tests with cargo nextest run -R latest. This command will run tests that, in the original run:
- failed;
- did not run because the test run was cancelled; or,
- were not previously seen, typically because they were newly added since the original run.
Rerun build scope
Without any further arguments, cargo nextest run -R latest will build the same targets that the original run did. If package or target arguments are specified, they will override the set of build targets from the original run.
Example rerun flow¶
Let's say that cargo nextest run --package nextest-filtering was run, and it had two failing tests:
Nextest run ID b0b38ba7-3a69-44c7-b52c-c0dabf839c07 with nextest profile: default
Starting 51 tests across 2 binaries
Cancelling due to interrupt: 2 tests still running
FAIL [ 0.142s] (50/51) nextest-filtering proptest_helpers::tests::proptest_regex_valid
FAIL [ 0.143s] (51/51) nextest-filtering parsing::tests::proptest_expr_roundtrip
────────────
Summary [ 0.143s] 51 tests run: 49 passed, 2 failed, 0 skipped
Nextest run ID b0b38ba7-3a69-44c7-b52c-c0dabf839c07 with nextest profile: default
Starting 51 tests across 2 binaries
Cancelling due to interrupt: 2 tests still running
FAIL [ 0.142s] (50/51) nextest-filtering proptest_helpers::tests::proptest_regex_valid
FAIL [ 0.143s] (51/51) nextest-filtering parsing::tests::proptest_expr_roundtrip
────────────
Summary [ 0.143s] 51 tests run: 49 passed, 2 failed, 0 skipped
With cargo nextest run -R latest proptest_helpers, the first test is selected:
info: experimental features enabled: setup-scripts
info: rerun: inheriting build scope from original run: --package nextest-filtering
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.11s
────────────
Nextest run ID e8082b32-05ae-4681-8b1d-84da628b9991 with nextest profile: default
Starting 1 test across 2 binaries (50 tests skipped, including 49 tests that already passed)
PASS [ 0.154s] nextest-filtering proptest_helpers::tests::proptest_regex_valid
────────────
Summary [ 0.155s] 1 test run: 1 passed, 50 skipped
Note 1 outstanding test not seen during this rerun:
nextest-filtering parsing::tests::proptest_expr_roundtrip
warning: 1 outstanding test still remains
(hint: cargo nextest run -R latest to continue rerunning)
info: experimental features enabled: setup-scripts
info: rerun: inheriting build scope from original run: --package nextest-filtering
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.11s
────────────
Nextest run ID e8082b32-05ae-4681-8b1d-84da628b9991 with nextest profile: default
Starting 1 test across 2 binaries (50 tests skipped, including 49 tests that already passed)
PASS [ 0.154s] nextest-filtering proptest_helpers::tests::proptest_regex_valid
────────────
Summary [ 0.155s] 1 test run: 1 passed, 50 skipped
Note 1 outstanding test not seen during this rerun:
nextest-filtering parsing::tests::proptest_expr_roundtrip
warning: 1 outstanding test still remains
(hint: cargo nextest run -R latest to continue rerunning)
All selected tests passed, but some outstanding (previously-failing) tests still remain, so nextest exits with the advisory exit code RERUN_TESTS_OUTSTANDING (exit code 5).
A subsequent cargo nextest run -R latest will run the remaining test:
info: experimental features enabled: setup-scripts
info: rerun: inheriting build scope from original run: --package nextest-filtering
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.11s
────────────
Nextest run ID 0b9f340f-1b61-4bdf-9260-54fa7a470ef4 with nextest profile: default
Starting 1 test across 2 binaries (50 tests skipped that already passed)
PASS [ 0.260s] nextest-filtering parsing::tests::proptest_expr_roundtrip
────────────
Summary [ 0.261s] 1 test run: 1 passed, 50 skipped
info: no outstanding tests remain
info: experimental features enabled: setup-scripts
info: rerun: inheriting build scope from original run: --package nextest-filtering
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.11s
────────────
Nextest run ID 0b9f340f-1b61-4bdf-9260-54fa7a470ef4 with nextest profile: default
Starting 1 test across 2 binaries (50 tests skipped that already passed)
PASS [ 0.260s] nextest-filtering parsing::tests::proptest_expr_roundtrip
────────────
Summary [ 0.261s] 1 test run: 1 passed, 50 skipped
info: no outstanding tests remain
It is possible to rewind the rerun logic to an earlier state by passing in a run ID to -R. In this case b0b forms an unambiguous prefix (highlighted in bold purple), so cargo nextest run -R b0b results in both tests being run:
info: experimental features enabled: setup-scripts
info: rerun: inheriting build scope from original run: --package nextest-filtering
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.11s
────────────
Nextest run ID d6a74827-4764-4965-9f1a-5b16417daf28 with nextest profile: default
Starting 2 tests across 2 binaries (49 tests skipped that already passed)
PASS [ 0.153s] nextest-filtering proptest_helpers::tests::proptest_regex_valid
PASS [ 0.277s] nextest-filtering parsing::tests::proptest_expr_roundtrip
────────────
Summary [ 0.278s] 2 tests run: 2 passed, 49 skipped
info: no outstanding tests remain
info: experimental features enabled: setup-scripts
info: rerun: inheriting build scope from original run: --package nextest-filtering
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.11s
────────────
Nextest run ID d6a74827-4764-4965-9f1a-5b16417daf28 with nextest profile: default
Starting 2 tests across 2 binaries (49 tests skipped that already passed)
PASS [ 0.153s] nextest-filtering proptest_helpers::tests::proptest_regex_valid
PASS [ 0.277s] nextest-filtering parsing::tests::proptest_expr_roundtrip
────────────
Summary [ 0.278s] 2 tests run: 2 passed, 49 skipped
info: no outstanding tests remain
Rerun heuristics¶
Picking the set of tests to run is tricky, particularly in the face of tests being removed and new ones being added. We have attempted to pick a strategy that aims to be conservative while covering the most common use cases, but it is always possible that tests are missed. Because of this, and because code changes might include regressions in previously passing tests, it is recommended that you perform a full test run once your iterations are complete.
As a best practice, it is also recommended that you use CI to gate changes making their way to production, and that you perform full runs in CI.
A design document discussing the heuristics and considerations involved is forthcoming.
Replaying test runs¶
To replay the last test run, run cargo nextest replay. This will show output that looks like:
Replaying recorded run 1bed9018-d2c0-4054-ad23-29837188cc31
Started 2026-01-16 17:08:22 status: completed
────────────
Nextest run ID 1bed9018-d2c0-4054-ad23-29837188cc31 with nextest profile: default
Starting 6 tests across 2 binaries (445 tests skipped)
PASS [ 0.006s] (1/6) nextest-runner reporter::events::tests::abort_description_from_abort_status
PASS [ 0.006s] (2/6) nextest-runner reporter::events::tests::abort_description_display
PASS [ 0.006s] (3/6) nextest-runner reporter::events::tests::abort_description_cross_platform_deserialization
PASS [ 0.006s] (4/6) nextest-runner reporter::events::tests::test_is_success
PASS [ 0.025s] (5/6) nextest-runner reporter::events::tests::abort_description_serialization
PASS [ 0.026s] (6/6) nextest-runner reporter::events::tests::execution_result_description_serialization
────────────
Summary [ 0.033s] 6 tests run: 6 passed, 445 skipped
Replaying recorded run 1bed9018-d2c0-4054-ad23-29837188cc31
Started 2026-01-16 17:08:22 status: completed
────────────
Nextest run ID 1bed9018-d2c0-4054-ad23-29837188cc31 with nextest profile: default
Starting 6 tests across 2 binaries (445 tests skipped)
PASS [ 0.006s] (1/6) nextest-runner reporter::events::tests::abort_description_from_abort_status
PASS [ 0.006s] (2/6) nextest-runner reporter::events::tests::abort_description_display
PASS [ 0.006s] (3/6) nextest-runner reporter::events::tests::abort_description_cross_platform_deserialization
PASS [ 0.006s] (4/6) nextest-runner reporter::events::tests::test_is_success
PASS [ 0.025s] (5/6) nextest-runner reporter::events::tests::abort_description_serialization
PASS [ 0.026s] (6/6) nextest-runner reporter::events::tests::execution_result_description_serialization
────────────
Summary [ 0.033s] 6 tests run: 6 passed, 445 skipped
Earlier runs can be replayed by identifying them through their nextest run ID, with the --run-id/-R option to cargo nextest replay. Any unique prefix can be used; in colorized output, unique prefixes are highlighted in bold purple.
Replayed runs automatically use the configured pager, such as less.
Reporter options for replay¶
The following reporter options also apply to replays, allowing output to be displayed differently than the original run:
--status-level <LEVEL>- Which test statuses to display during the replay. The default is
pass. See Status levels for valid values. --final-status-level <LEVEL>- Which test statuses to display at the end of the replay. The default is
fail. See Status levels for valid values. --failure-output <WHEN>- When to display output for failing tests. The default is
immediate. Valid values:immediate,final,immediate-final,never. --success-output <WHEN>- When to display output for successful tests. The default is
never. Valid values:immediate,final,immediate-final,never. --no-capture- Simulate no-capture mode. Since recorded output is already captured, this is a convenience option that sets
--success-output immediate,--failure-output immediate, and--no-output-indent. --no-output-indent- Disable indentation for test output.
For example, outputs for successful tests are hidden by default. Use cargo nextest replay --success-output immediate to see those outputs.
Listing recorded runs¶
To list recorded runs, run cargo nextest store list. This produces output that looks like:
133 recorded runs:
b0b38ba7 2026-01-21 20:07:40 0.143s 206 KB 49 passed / 2 failed (cancelled)
├─d6a74827 2026-01-21 20:30:30 0.278s 190 KB 2 passed *latest
├─e8082b32 2026-01-21 20:18:13 0.155s 186 KB 1 passed
│ 0b9f340f 2026-01-21 20:24:55 0.261s 187 KB 1 passed
└─092550db 2026-01-21 20:08:44 0.277s 190 KB 2 passed
362688c2 2026-01-21 20:07:37 0.266s 208 KB 51 passed
<output snipped>
─────────
29.5 MB
133 recorded runs:
b0b38ba7 2026-01-21 20:07:40 0.143s 206 KB 49 passed / 2 failed (cancelled)
├─d6a74827 2026-01-21 20:30:30 0.278s 190 KB 2 passed *latest
├─e8082b32 2026-01-21 20:18:13 0.155s 186 KB 1 passed
│ 0b9f340f 2026-01-21 20:24:55 0.261s 187 KB 1 passed
└─092550db 2026-01-21 20:08:44 0.277s 190 KB 2 passed
362688c2 2026-01-21 20:07:37 0.266s 208 KB 51 passed
<output snipped>
─────────
29.5 MB
As with reruns, highlighted prefixes can be used to uniquely identify a test run. For example, with the above output, to replay the run ID starting with b0b38ba7, run cargo nextest replay -R b0b.
Reruns are shown in a tree structure. Chains of reruns (e.g., with repeated cargo nextest run -R latest invocations) are shown linearly if possible.
Detailed information about a run¶
For detailed information, run cargo nextest store info <run-id>. For example, cargo nextest store info b0b:
Run b0b38ba7-3a69-44c7-b52c-c0dabf839c07
nextest version: 0.9.123
command: /opt/cargo/bin/cargo-nextest nextest run -p nextest-filtering
env: CARGO_HOME=/opt/cargo
status: cancelled (exit code 100)
started at: 2026-01-21 20:07:40 +00:00 (1h ago)
last written at: 2026-01-21 20:30:30 +00:00 (52m ago)
duration: 0.143s
replayable: yes
tests:
passed: 49
failed: 2
sizes: compressed uncompressed entries
log 5 KB 108 KB 105
store 200 KB 2.0 MB 77
────────── ──────────── ───────
total 206 KB 2.2 MB 182
Run b0b38ba7-3a69-44c7-b52c-c0dabf839c07
nextest version: 0.9.123
command: /opt/cargo/bin/cargo-nextest nextest run -p nextest-filtering
env: CARGO_HOME=/opt/cargo
status: cancelled (exit code 100)
started at: 2026-01-21 20:07:40 +00:00 (1h ago)
last written at: 2026-01-21 20:30:30 +00:00 (52m ago)
duration: 0.143s
replayable: yes
tests:
passed: 49
failed: 2
sizes: compressed uncompressed entries
log 5 KB 108 KB 105
store 200 KB 2.0 MB 77
────────── ──────────── ───────
total 206 KB 2.2 MB 182
For debugging purposes, runs capture all environment variables starting with CARGO_ and NEXTEST_, other than ones ending with _TOKEN (since they may contain sensitive tokens).
Record retention¶
Nextest applies limits to recorded runs to prevent the cache size from blowing up.
Retention limits are applied per-workspace. The default limits are:
- Number: A maximum of 100 runs are stored.
- Size: Runs are stored until their compressed size exceeds 1 GB.
- Age: Runs are stored for up to 30 days.
These limits can be customized via the [record] section in user configuration.
The cache is pruned in order of last written at, starting from the oldest runs. The last written at time is set at initial creation, and bumped on the original run when a recorded rerun is created.
Example pruning configuration¶
~/.config/nextest/config.toml[record]
enabled = true
# The maximum number of recorded runs.
max-records = 200
# The maximum total compressed size across recorded runs.
max-total-size = "2GB"
# The number of days to persist runs for.
max-age = "60d"
Automatic pruning¶
The cache is automatically automatically pruned once a day at the end of test runs, if recording is enabled. The cache is also pruned if the number or size limits are exceeded by a factor of 1.5x or more.
Manual pruning¶
To prune recorded runs manually, run cargo nextest store prune.
To see what would be pruned the next time, run cargo nextest store prune --dry-run.
Store location¶
The store location is platform-dependent:
| Platform | Path |
|---|---|
| Linux and other Unix | $XDG_CACHE_HOME/nextest/ or ~/.cache/nextest/ |
| macOS | ~/Library/Caches/nextest/ |
| Windows | %LOCALAPPDATA%\nextest\ |
The store location can be overridden via the NEXTEST_CACHE_DIR environment variable.
Within the store, recorded runs are indexed by canonicalized workspace path.
Configuration options¶
For a full list, see Record configuration.
Options and arguments¶
TODO