Record and replay¶

0.9.123

Experimental: This feature is not yet stable

Enable with: Add experimental = ["record"] to ~/.config/nextest/config.toml, or set NEXTEST_EXPERIMENTAL_RECORD=1 in the environment
Tracking issue: TBD

Nextest supports recording test runs 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, test output cannot be captured)

Use cases¶

Currently, test runs can be replayed with cargo nextest replay. This is particularly useful for runs done in the past, 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
rerun tests that failed or were not run in the past, with the goal being to converge towards a successful test run

Usage¶

Once the experimental record feature has been enabled in user config, you can enable recording in user configuration:

Enabling recording in ~/.config/nextest/config.toml

[record]
enabled = true

Now, all future cargo nextest run instances will automatically be recorded.

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

5 recorded runs:

  caede343  2026-01-16 15:30:53     14.330s     479 KB  525 passed
  fc29b029  2026-01-16 15:09:53      0.013s     200 KB    8 passed
  9d032152  2026-01-16 14:58:28      0.266s     207 KB   31 passed / 28 failed / 515 not run (cancelled)
  fe92197f  2026-01-16 14:49:56           -       0 KB      incomplete
  e8c794b0  2026-01-16 14:43:41      4.587s     324 KB  446 passed

5 recorded runs:

  caede343  2026-01-16 15:30:53     14.330s     479 KB  525 passed
  fc29b029  2026-01-16 15:09:53      0.013s     200 KB    8 passed
  9d032152  2026-01-16 14:58:28      0.266s     207 KB   31 passed / 28 failed / 515 not run (cancelled)
  fe92197f  2026-01-16 14:49:56           -       0 KB      incomplete
  e8c794b0  2026-01-16 14:43:41      4.587s     324 KB  446 passed

The highlighted prefixes can be used to uniquely identify a test run. For example, with the above output, to replay the run ID starting with 9d032152, run cargo nextest replay -r 9d.

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 least-recently-created (LRU) order, starting from the oldest runs.

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