Managing recorded runs¶
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¶
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, macOS, and other Unix | $XDG_STATE_HOME/nextest/ or ~/.local/state/nextest/ |
| Windows | %LOCALAPPDATA%\nextest\ |
The store location can be overridden via the NEXTEST_STATE_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¶
cargo nextest store list¶
The output of cargo nextest store list -h:
List all recorded runs
Usage: cargo nextest store list [OPTIONS]
Options:
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always]
[default: auto]
--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=]
List all recorded runs
Usage: cargo nextest store list [OPTIONS]
Options:
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always]
[default: auto]
--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 list --help:
List all recorded runs
Usage: cargo nextest store list [OPTIONS]
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--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=]
List all recorded runs
Usage: cargo nextest store list [OPTIONS]
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--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=]
cargo nextest store info¶
The output of cargo nextest store info -h:
Show detailed information about a recorded run
Usage: cargo nextest store info [OPTIONS] [RUN_ID_OR_RECORDING]
Arguments:
[RUN_ID_OR_RECORDING] Run ID, latest, or recording path to show info for [aliases: -R]
Options:
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always]
[default: auto]
--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=]
Show detailed information about a recorded run
Usage: cargo nextest store info [OPTIONS] [RUN_ID_OR_RECORDING]
Arguments:
[RUN_ID_OR_RECORDING] Run ID, latest, or recording path to show info for [aliases: -R]
Options:
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always]
[default: auto]
--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 info --help:
Show detailed information about a recorded run
Usage: cargo nextest store info [OPTIONS] [RUN_ID_OR_RECORDING]
Arguments:
[RUN_ID_OR_RECORDING]
Run ID, latest, or recording path to show info for [aliases: -R].
Accepts "latest" for the most recent completed run, a full UUID or unambiguous prefix, or
a file path (ending in .zip, or, on Unix, <(curl url)).
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--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=]
Show detailed information about a recorded run
Usage: cargo nextest store info [OPTIONS] [RUN_ID_OR_RECORDING]
Arguments:
[RUN_ID_OR_RECORDING]
Run ID, latest, or recording path to show info for [aliases: -R].
Accepts "latest" for the most recent completed run, a full UUID or unambiguous prefix, or
a file path (ending in .zip, or, on Unix, <(curl url)).
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--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=]
cargo nextest store prune¶
The output of cargo nextest store prune -h:
Prune old recorded runs according to retention policy
Usage: cargo nextest store prune [OPTIONS]
Options:
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always]
[default: auto]
--dry-run Show what would be deleted without actually deleting
--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=]
Prune old recorded runs according to retention policy
Usage: cargo nextest store prune [OPTIONS]
Options:
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=always]
[default: auto]
--dry-run Show what would be deleted without actually deleting
--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 prune --help:
Prune old recorded runs according to retention policy
Usage: cargo nextest store prune [OPTIONS]
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--dry-run
Show what would be deleted without actually deleting
--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=]
Prune old recorded runs according to retention policy
Usage: cargo nextest store prune [OPTIONS]
Options:
--color <WHEN>
Produce color output: auto, always, never
[env: CARGO_TERM_COLOR=always]
[default: auto]
--dry-run
Show what would be deleted without actually deleting
--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=]