Record, replay and rerun¶

0.9.123

Experimental: This feature is not yet stable

Enable with: Add [experimental] with record = true to ~/.config/nextest/config.toml, or set NEXTEST_EXPERIMENTAL_RECORD=1 in 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-capture is 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:

Enabling recording in ~/.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:

ColorizedPlaintext

 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:

ColorizedPlaintext

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:

ColorizedPlaintext

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:

ColorizedPlaintext

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:

ColorizedPlaintext

   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:

ColorizedPlaintext

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:

ColorizedPlaintext

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¶

Custom pruning configuration in ~/.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