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.
Portable recordings¶
Recorded runs can be exported as self-contained portable recordings for sharing across machines. For example, a recording can be created in CI and downloaded locally to be replayed or used as the basis for a rerun.
To export a recording:
cargo nextest store export latest
By default, this creates a file named nextest-run-<run-id>.zip in the current directory, where <run-id> is the full UUID of the run. The output path can be customized with --archive-file:
cargo nextest store export latest --archive-file my-run.zip
To replay or rerun from a portable recording, pass the path to the .zip file as the -R argument:
# Replay a portable recording.
cargo nextest replay -R my-run.zip
# Rerun failing tests from a portable recording.
cargo nextest run -R my-run.zip
0.9.127 With Unix shells, you can also use process substitution to download a URL directly:
# Recommended: =(...) for zsh.
cargo nextest replay -R =(curl https://example.com/archive.zip)
# The <(...) syntax works in both bash and zsh, but is
# slightly less efficient.
cargo nextest replay -R <(curl https://example.com/archive.zip)
# For fish, use psub.
cargo nextest replay -R (curl https://example.com/archive.zip | psub)
GitHub workflow artifacts
If using GitHub's CI, a natural place to upload recordings is as a GitHub workflow artifact.
To download these artifacts, the gh CLI tool provides the gh run download command. This command does not currently have a way to write the recording to standard out, so process substitution can't directly be used. Instead, download the archive to disk and use that. For example:
gh run download 21978978444 -n nextest-run-ubuntu-latest-stable
cargo nextest replay nextest-run-archive.zip
Sensitive data in portable recordings
Portable recordings contain the full captured output of every test in the run. Test outputs can inadvertently contain sensitive data such as API keys, personal information (PII), or environment variable values. Nextest does not attempt to scrub or redact recordings. You are responsible for ensuring that recordings shared outside your organization do not contain sensitive information.
For more about the portable recording format, see the design document.
Options and arguments¶
cargo nextest replay¶
The output of cargo nextest replay -h:
Replay a recorded test run (experimental)
Usage: cargo nextest replay [OPTIONS]
Options:
--color <WHEN> Produce color output: auto, always, never [env:
CARGO_TERM_COLOR=always] [default: auto]
-R, --run-id <RUN_ID_OR_RECORDING> Run ID, latest, or recording path to replay [default: latest]
--exit-code Exit with the same code as the original run
--no-pager Do not pipe output through a pager
-v, --verbose Verbose output [env: NEXTEST_VERBOSE=]
-h, --help Print help (see more with '--help')
Reporter options:
--no-capture Simulate no-capture mode during replay
--failure-output <WHEN> Output stdout and stderr on failure [env:
NEXTEST_FAILURE_OUTPUT=] [possible values: immediate,
immediate-final, final, never]
--success-output <WHEN> Output stdout and stderr on success [env:
NEXTEST_SUCCESS_OUTPUT=] [possible values: immediate,
immediate-final, final, never]
--status-level <LEVEL> Test statuses to output [env: NEXTEST_STATUS_LEVEL=] [possible
values: none, fail, retry, slow, leak, pass, skip, all]
--final-status-level <LEVEL> Test statuses to output at the end of the run [env:
NEXTEST_FINAL_STATUS_LEVEL=] [possible values: none, fail,
flaky, slow, skip, pass, all]
--no-output-indent Do not indent captured test output [env:
NEXTEST_NO_OUTPUT_INDENT=]
Manifest options:
--manifest-path <PATH> Path to Cargo.toml
Config options:
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent] [env:
NEXTEST_USER_CONFIG_FILE=]
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files
--override-version-check
Override checks for the minimum version defined in nextest's config
-P, --profile <PROFILE>
The nextest profile to use [env: NEXTEST_PROFILE=]
Replay a recorded test run (experimental)
Usage: cargo nextest replay [OPTIONS]
Options:
--color <WHEN> Produce color output: auto, always, never [env:
CARGO_TERM_COLOR=always] [default: auto]
-R, --run-id <RUN_ID_OR_RECORDING> Run ID, latest, or recording path to replay [default: latest]
--exit-code Exit with the same code as the original run
--no-pager Do not pipe output through a pager
-v, --verbose Verbose output [env: NEXTEST_VERBOSE=]
-h, --help Print help (see more with '--help')
Reporter options:
--no-capture Simulate no-capture mode during replay
--failure-output <WHEN> Output stdout and stderr on failure [env:
NEXTEST_FAILURE_OUTPUT=] [possible values: immediate,
immediate-final, final, never]
--success-output <WHEN> Output stdout and stderr on success [env:
NEXTEST_SUCCESS_OUTPUT=] [possible values: immediate,
immediate-final, final, never]
--status-level <LEVEL> Test statuses to output [env: NEXTEST_STATUS_LEVEL=] [possible
values: none, fail, retry, slow, leak, pass, skip, all]
--final-status-level <LEVEL> Test statuses to output at the end of the run [env:
NEXTEST_FINAL_STATUS_LEVEL=] [possible values: none, fail,
flaky, slow, skip, pass, all]
--no-output-indent Do not indent captured test output [env:
NEXTEST_NO_OUTPUT_INDENT=]
Manifest options:
--manifest-path <PATH> Path to Cargo.toml
Config options:
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent] [env:
NEXTEST_USER_CONFIG_FILE=]
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files
--override-version-check
Override checks for the minimum version defined in nextest's config
-P, --profile <PROFILE>
The nextest profile to use [env: NEXTEST_PROFILE=]
The output of cargo nextest replay --help:
Replay a recorded test run (experimental).
This command replays a recorded test run, displaying events as if the run were happening live.
This is an experimental feature. To enable it, set the environment variable
NEXTEST_EXPERIMENTAL_RECORD=1.
Usage: cargo nextest replay [OPTIONS]
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
-R, --run-id <RUN_ID_OR_RECORDING>
Run ID, latest, or recording path to replay.
Accepts "latest" (the default) for the most recent completed run, a full UUID or
unambiguous prefix, or a file path (ending in .zip or containing path separators, e.g.
<(curl url)).
[default: latest]
--exit-code
Exit with the same code as the original run.
By default, replay exits with code 0 if the replay itself succeeds. With this flag, replay
exits with the code that the original test run would have returned (e.g., 100 for test
failures, 105 for setup script failures).
--no-pager
Do not pipe output through a pager
-v, --verbose
Verbose output
[env: NEXTEST_VERBOSE=]
-h, --help
Print help (see a summary with '-h')
Reporter options:
--no-capture
Simulate no-capture mode during replay.
This is a convenience flag that sets:
- --success-output immediate
- --failure-output immediate
- --no-output-indent
These settings produce output similar to running tests with --no-capture, showing all
output immediately without indentation.
Explicit --success-output and --failure-output flags take precedence over this setting.
--failure-output <WHEN>
Output stdout and stderr on failure
[env: NEXTEST_FAILURE_OUTPUT=]
[possible values: immediate, immediate-final, final, never]
--success-output <WHEN>
Output stdout and stderr on success
[env: NEXTEST_SUCCESS_OUTPUT=]
[possible values: immediate, immediate-final, final, never]
--status-level <LEVEL>
Test statuses to output
[env: NEXTEST_STATUS_LEVEL=]
[possible values: none, fail, retry, slow, leak, pass, skip, all]
--final-status-level <LEVEL>
Test statuses to output at the end of the run
[env: NEXTEST_FINAL_STATUS_LEVEL=]
[possible values: none, fail, flaky, slow, skip, pass, all]
--no-output-indent
Do not indent captured test output.
By default, test output produced by --failure-output and --success-output is indented for
visual clarity. This flag disables that behavior.
This option has no effect with --no-capture, since that passes through standard output and
standard error.
[env: NEXTEST_NO_OUTPUT_INDENT=]
Manifest options:
--manifest-path <PATH>
Path to Cargo.toml
Config options:
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent].
User configuration stores per-user preferences like UI settings. Use "none" to skip
loading user config entirely.
[env: NEXTEST_USER_CONFIG_FILE=]
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files.
Some tools on top of nextest may want to set up their own default configuration but
prioritize user configuration on top. Use this argument to insert configuration that's
lower than --config-file in priority but above the default config shipped with nextest.
Arguments are specified in the format "tool:abs_path", for example
"my-tool:/path/to/nextest.toml" (or "my-tool:C:\path\to\nextest.toml" on Windows). Paths
must be absolute.
This argument may be specified multiple times. Files that come later are lower priority
than those that come earlier.
--override-version-check
Override checks for the minimum version defined in nextest's config.
Repository and tool-specific configuration files can specify minimum required and
recommended versions of nextest. This option overrides those checks.
-P, --profile <PROFILE>
The nextest profile to use.
Nextest's configuration supports multiple profiles, which can be used to set up different
configurations for different purposes. (For example, a configuration for local runs and
one for CI.) This option selects the profile to use.
[env: NEXTEST_PROFILE=]
Replay a recorded test run (experimental).
This command replays a recorded test run, displaying events as if the run were happening live.
This is an experimental feature. To enable it, set the environment variable
NEXTEST_EXPERIMENTAL_RECORD=1.
Usage: cargo nextest replay [OPTIONS]
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
-R, --run-id <RUN_ID_OR_RECORDING>
Run ID, latest, or recording path to replay.
Accepts "latest" (the default) for the most recent completed run, a full UUID or
unambiguous prefix, or a file path (ending in .zip or containing path separators, e.g.
<(curl url)).
[default: latest]
--exit-code
Exit with the same code as the original run.
By default, replay exits with code 0 if the replay itself succeeds. With this flag, replay
exits with the code that the original test run would have returned (e.g., 100 for test
failures, 105 for setup script failures).
--no-pager
Do not pipe output through a pager
-v, --verbose
Verbose output
[env: NEXTEST_VERBOSE=]
-h, --help
Print help (see a summary with '-h')
Reporter options:
--no-capture
Simulate no-capture mode during replay.
This is a convenience flag that sets:
- --success-output immediate
- --failure-output immediate
- --no-output-indent
These settings produce output similar to running tests with --no-capture, showing all
output immediately without indentation.
Explicit --success-output and --failure-output flags take precedence over this setting.
--failure-output <WHEN>
Output stdout and stderr on failure
[env: NEXTEST_FAILURE_OUTPUT=]
[possible values: immediate, immediate-final, final, never]
--success-output <WHEN>
Output stdout and stderr on success
[env: NEXTEST_SUCCESS_OUTPUT=]
[possible values: immediate, immediate-final, final, never]
--status-level <LEVEL>
Test statuses to output
[env: NEXTEST_STATUS_LEVEL=]
[possible values: none, fail, retry, slow, leak, pass, skip, all]
--final-status-level <LEVEL>
Test statuses to output at the end of the run
[env: NEXTEST_FINAL_STATUS_LEVEL=]
[possible values: none, fail, flaky, slow, skip, pass, all]
--no-output-indent
Do not indent captured test output.
By default, test output produced by --failure-output and --success-output is indented for
visual clarity. This flag disables that behavior.
This option has no effect with --no-capture, since that passes through standard output and
standard error.
[env: NEXTEST_NO_OUTPUT_INDENT=]
Manifest options:
--manifest-path <PATH>
Path to Cargo.toml
Config options:
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent].
User configuration stores per-user preferences like UI settings. Use "none" to skip
loading user config entirely.
[env: NEXTEST_USER_CONFIG_FILE=]
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files.
Some tools on top of nextest may want to set up their own default configuration but
prioritize user configuration on top. Use this argument to insert configuration that's
lower than --config-file in priority but above the default config shipped with nextest.
Arguments are specified in the format "tool:abs_path", for example
"my-tool:/path/to/nextest.toml" (or "my-tool:C:\path\to\nextest.toml" on Windows). Paths
must be absolute.
This argument may be specified multiple times. Files that come later are lower priority
than those that come earlier.
--override-version-check
Override checks for the minimum version defined in nextest's config.
Repository and tool-specific configuration files can specify minimum required and
recommended versions of nextest. This option overrides those checks.
-P, --profile <PROFILE>
The nextest profile to use.
Nextest's configuration supports multiple profiles, which can be used to set up different
configurations for different purposes. (For example, a configuration for local runs and
one for CI.) This option selects the profile to use.
[env: NEXTEST_PROFILE=]
cargo nextest store export¶
The output of cargo nextest store export -h:
Export a recorded run as a portable recording
Usage: cargo nextest store export [OPTIONS] [RUN_ID]
Arguments:
[RUN_ID] Run ID to export, or latest [aliases: -R]
Options:
--color <WHEN> Produce color output: auto, always, never [env:
CARGO_TERM_COLOR=always] [default: auto]
--archive-file <PATH> Destination for the archive file
--no-pager Do not pipe output through a pager
-v, --verbose Verbose output [env: NEXTEST_VERBOSE=]
-h, --help Print help (see more with '--help')
Manifest options:
--manifest-path <PATH> Path to Cargo.toml
Config options:
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent] [env:
NEXTEST_USER_CONFIG_FILE=]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files
--override-version-check
Override checks for the minimum version defined in nextest's config
-P, --profile <PROFILE>
The nextest profile to use [env: NEXTEST_PROFILE=]
Export a recorded run as a portable recording
Usage: cargo nextest store export [OPTIONS] [RUN_ID]
Arguments:
[RUN_ID] Run ID to export, or latest [aliases: -R]
Options:
--color <WHEN> Produce color output: auto, always, never [env:
CARGO_TERM_COLOR=always] [default: auto]
--archive-file <PATH> Destination for the archive file
--no-pager Do not pipe output through a pager
-v, --verbose Verbose output [env: NEXTEST_VERBOSE=]
-h, --help Print help (see more with '--help')
Manifest options:
--manifest-path <PATH> Path to Cargo.toml
Config options:
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent] [env:
NEXTEST_USER_CONFIG_FILE=]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files
--override-version-check
Override checks for the minimum version defined in nextest's config
-P, --profile <PROFILE>
The nextest profile to use [env: NEXTEST_PROFILE=]
The output of cargo nextest store export --help:
Export a recorded run as a portable recording
Usage: cargo nextest store export [OPTIONS] [RUN_ID]
Arguments:
[RUN_ID]
Run ID to export, or latest [aliases: -R].
Accepts "latest" for the most recent completed run, or a full UUID or unambiguous prefix.
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--archive-file <PATH>
Destination for the archive file.
Defaults to nextest-run-<run-id>.zip in the current directory.
--no-pager
Do not pipe output through a pager
-v, --verbose
Verbose output
[env: NEXTEST_VERBOSE=]
-h, --help
Print help (see a summary with '-h')
Manifest options:
--manifest-path <PATH>
Path to Cargo.toml
Config options:
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent].
User configuration stores per-user preferences like UI settings. Use "none" to skip
loading user config entirely.
[env: NEXTEST_USER_CONFIG_FILE=]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files.
Some tools on top of nextest may want to set up their own default configuration but
prioritize user configuration on top. Use this argument to insert configuration that's
lower than --config-file in priority but above the default config shipped with nextest.
Arguments are specified in the format "tool:abs_path", for example
"my-tool:/path/to/nextest.toml" (or "my-tool:C:\path\to\nextest.toml" on Windows). Paths
must be absolute.
This argument may be specified multiple times. Files that come later are lower priority
than those that come earlier.
--override-version-check
Override checks for the minimum version defined in nextest's config.
Repository and tool-specific configuration files can specify minimum required and
recommended versions of nextest. This option overrides those checks.
-P, --profile <PROFILE>
The nextest profile to use.
Nextest's configuration supports multiple profiles, which can be used to set up different
configurations for different purposes. (For example, a configuration for local runs and
one for CI.) This option selects the profile to use.
[env: NEXTEST_PROFILE=]
Export a recorded run as a portable recording
Usage: cargo nextest store export [OPTIONS] [RUN_ID]
Arguments:
[RUN_ID]
Run ID to export, or latest [aliases: -R].
Accepts "latest" for the most recent completed run, or a full UUID or unambiguous prefix.
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--archive-file <PATH>
Destination for the archive file.
Defaults to nextest-run-<run-id>.zip in the current directory.
--no-pager
Do not pipe output through a pager
-v, --verbose
Verbose output
[env: NEXTEST_VERBOSE=]
-h, --help
Print help (see a summary with '-h')
Manifest options:
--manifest-path <PATH>
Path to Cargo.toml
Config options:
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--user-config-file <PATH>
User config file [default: ~/.config/nextest/config.toml or platform equivalent].
User configuration stores per-user preferences like UI settings. Use "none" to skip
loading user config entirely.
[env: NEXTEST_USER_CONFIG_FILE=]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files.
Some tools on top of nextest may want to set up their own default configuration but
prioritize user configuration on top. Use this argument to insert configuration that's
lower than --config-file in priority but above the default config shipped with nextest.
Arguments are specified in the format "tool:abs_path", for example
"my-tool:/path/to/nextest.toml" (or "my-tool:C:\path\to\nextest.toml" on Windows). Paths
must be absolute.
This argument may be specified multiple times. Files that come later are lower priority
than those that come earlier.
--override-version-check
Override checks for the minimum version defined in nextest's config.
Repository and tool-specific configuration files can specify minimum required and
recommended versions of nextest. This option overrides those checks.
-P, --profile <PROFILE>
The nextest profile to use.
Nextest's configuration supports multiple profiles, which can be used to set up different
configurations for different purposes. (For example, a configuration for local runs and
one for CI.) This option selects the profile to use.
[env: NEXTEST_PROFILE=]