Configuration reference¶

This page provides the full repository configuration reference for nextest.

0.9.139 This reference is also available locally by running cargo nextest help repo-config.

For more information about how repository configuration works, see the main configuration page.

Configuration file locations¶

Configuration is loaded in the following order (higher priority overrides lower):

Repository config (.config/nextest.toml)
Tool-specific configs (specified via --tool-config-file)
Default embedded config

Tool-specific configs allow tools to provide their own nextest configuration that integrates with repository settings.

For more information about configuration hierarchy, see Hierarchical configuration.

Repository configuration schema¶

0.9.134

A JSON Schema is available for nextest's repository configuration. The schema can be obtained through:

For the latest released version of nextest, at https://nexte.st/schemas/repo-config.json. This URL is updated with new nextest releases.
For the schema corresponding to a particular version of nextest, by running cargo nextest self schema repo-config.

The schema can be used:

To validate a repository configuration file.
With the Tombi language server for TOML or RustRover, to provide autocomplete in supported IDEs and editors. (The taplo language server is not supported due to a crash bug.)

Note that the schema is somewhat stricter than nextest's own config parser: unknown configuration items will fail schema validation, while nextest itself will only print out a warning.

The schema is part of the JSON Schema Store, so both Tombi and RustRover will automatically download it for you. Because nextest's configuration (outside of experimental configuration) is append-only, the schema will automatically be updated as new nextest versions are released.

Top-level configuration¶

These parameters are specified at the root level of the configuration file.

`nextest-version`¶

0.9.55

Type: String or object
Description: The minimum required (and optionally recommended) version of nextest for this configuration.
Documentation: Minimum nextest versions
Default: Unset (the minimum version check is disabled)

Examples:

nextest-version = "0.9.50"
# or
nextest-version = { required = "0.9.20", recommended = "0.9.30" }

`experimental`¶

Type: Array of strings
Description: Enables experimental, non-stable features.
Documentation: Setup scripts, wrapper scripts
Default: [] (no experimental features enabled)
Valid values:
- "setup-scripts" 0.9.98 (originally 0.9.59)
- "wrapper-scripts" 0.9.98
Example:
```
experimental = ["setup-scripts"]
```

`store`¶

Type: Object
Description: Configuration for the nextest store directory.

`store.dir`¶

Type: String (path)
Description: Directory where nextest stores its data.
Default: target/nextest

Profile configuration¶

Profiles are configured under [profile.<name>]. The default profile is called [profile.default].

General configuration¶

`profile.<name>.inherits`¶

0.9.115

Type: String
Description: The profile to inherit settings from.
Documentation: Profile inheritance
Default: "default"

Core test execution¶

`profile.<name>.default-filter`¶

Type: String (filterset expression)
Description: The default set of tests run by cargo nextest run, as a filterset expression.
Documentation: Running a subset of tests by default
Default: "all()" (all tests are run)
Example: default-filter = "not test(very_slow_tests)"

`profile.<name>.global-timeout`¶

0.9.100

Type: String (duration)
Description: A global timeout for the entire test run.
Documentation: Setting a global timeout
Default: Unset (no global timeout)
Example: global-timeout = "2h"

`profile.<name>.test-threads`¶

Type: Integer or string
Description: Number of threads to run tests with.
Valid values: Positive integer, negative integer (relative to CPU count), or "num-cpus"
Default: "num-cpus"
Example: test-threads = 4 or test-threads = "num-cpus"

`profile.<name>.threads-required`¶

Type: Integer or string
Description: Number of threads each test reserves from the pool.
Documentation: Heavy tests and threads-required
Valid values: Positive integer, "num-cpus", or "num-test-threads"
Default: 1

`profile.<name>.run-extra-args`¶

0.9.86

Type: Array of strings
Description: Extra arguments to pass to test binaries.
Documentation: Extra arguments
Default: []
Example: run-extra-args = ["--test-threads", "1"]

Retry configuration¶

`profile.<name>.retries`¶

Type: Integer or object
Description: Retry policy for failed tests.
Documentation: Retries and flaky tests
Default: 0

Examples:

retries = 3
# or
retries = { backoff = "fixed", count = 3, delay = "1s" }
# or
retries = { backoff = "exponential", count = 4, delay = "2s", max-delay = "10s", jitter = true }

`profile.<name>.flaky-result`¶

0.9.131

Type: String
Description: Whether to treat flaky tests as passing or failing.
Documentation: Failing flaky tests
Valid values: "pass", "fail"
Default: "pass"
Example: flaky-result = "fail"

Timeout configuration¶

`profile.<name>.slow-timeout`¶

Type: String (duration) or object
Description: Time after which tests are considered slow, plus optional termination policy.
Documentation: Slow tests and timeouts
Default: 60s with no termination on timeout

Examples:

slow-timeout = "60s"
# or
slow-timeout = { period = "120s", terminate-after = 2, grace-period = "10s" }
# or
slow-timeout = { period = "30s", terminate-after = 4, on-timeout = "pass" }

The slow-timeout object accepts the following parameters:

period: Time period after which a test is considered slow (required)
terminate-after: Number of periods after which to terminate the test (default: do not terminate)
grace-period: Time to wait for graceful shutdown before force termination (default: 10s)
on-timeout: 0.9.115 What to do when a test times out: "fail" (default) or "pass"

`profile.<name>.leak-timeout`¶

Type: String (duration) or object
Description: Time to wait for child processes to exit after a test completes.
Documentation: Leaky tests

Examples:

leak-timeout = "100ms"
# or
leak-timeout = { period = "500ms", result = "fail" }

Benchmark configuration¶

`profile.<name>.bench.global-timeout`¶

0.9.117

Type: String (duration)
Description: Global timeout for the entire benchmark run. Replaces global-timeout when running cargo nextest bench.
Documentation: Running benchmarks
Default: Unset (no global timeout)
Example: bench.global-timeout = "2h"

`profile.<name>.bench.slow-timeout`¶

0.9.117

Type: String (duration) or object
Description: Time after which benchmarks are considered slow, plus optional termination policy. Replaces slow-timeout when running cargo nextest bench.
Documentation: Running benchmarks
Default: Unset

Examples:

bench.slow-timeout = "120s"
# or
bench.slow-timeout = { period = "60s", terminate-after = 10, grace-period = "10s" }

The bench.slow-timeout object accepts the same parameters as slow-timeout:

period: Time period after which a benchmark is considered slow (required)
terminate-after: Number of periods after which to terminate the benchmark (default: do not terminate)
grace-period: Time to wait for graceful shutdown before force termination (default: 10s)

Reporter options¶

`profile.<name>.status-level`¶

Type: String
Description: Level of status information to display during test runs.
Documentation: Reporting test results
Valid values (incremental; each level includes those above it):
- "none": no output.
- "fail": only output test failures.
- "retry": output test retries; includes fail.
- "slow": output slow tests; includes retry.
- "leak": output leaky tests; includes slow.
- "pass": output passing tests; includes leak.
- "skip": output skipped tests; includes pass.
- "all": equivalent to "skip" today; reserved for future expansion.
Default: "pass"

`profile.<name>.final-status-level`¶

Type: String
Description: Level of status information to display in the final summary.
Documentation: Reporting test results
Valid values (incremental; each level includes those above it):
- "none": no output.
- "fail": only output test failures.
- "flaky": output flaky tests; includes fail. Accepts "retry" as an alias.
- "slow": output slow tests; includes flaky.
- "skip": output skipped tests; includes slow.
- "leak": output leaky tests; includes skip.
- "pass": output passing tests; includes leak.
- "all": equivalent to "pass" today; reserved for future expansion.
Default: "flaky"

`profile.<name>.failure-output`¶

Type: String
Description: When to display output for failed tests.
Documentation: Reporting test results
Valid values:
- "immediate": show captured output as soon as the test completes.
- "immediate-final": show captured output when the test completes and again at the end of the run.
- "final": show captured output only at the end of the run.
- "never": never show captured output.
Default: "immediate"

`profile.<name>.success-output`¶

Type: String
Description: When to display output for successful tests.
Documentation: Reporting test results
Valid values: same as failure-output
Default: "never"

Failure handling¶

`profile.<name>.fail-fast`¶

Type: Boolean or object
Description: Controls when to stop running tests after failures.
Documentation: Failing fast
Default: true (stop after first failure, wait for running tests to complete)

Examples:

fail-fast = true  # Stop after first failure (waits for running tests)
fail-fast = false # Run all tests
fail-fast = { max-fail = 5 }  # Stop after 5 failures (waits for running tests)
fail-fast = { max-fail = "all" }  # Run all tests

# With termination mode (since 0.9.111)
fail-fast = { max-fail = 1, terminate = "wait" }  # Wait for running tests (default)
fail-fast = { max-fail = 1, terminate = "immediate" }  # Terminate running tests immediately

When max-fail is exceeded: - terminate = "wait" (default): nextest stops scheduling new tests but waits for currently running tests to finish naturally. - terminate = "immediate" 0.9.111: nextest sends termination signals to running tests (respecting the grace period configured via slow-timeout.terminate-after).

Test grouping¶

`profile.<name>.test-group`¶

0.9.48

Type: String
Description: Assigns matching tests to a custom test group for resource management.
Documentation: Test groups for mutual exclusion
Valid values: Custom group name or "@global"
Default: "@global"

JUnit configuration¶

`profile.<name>.junit.path`¶

Type: String (path)
Description: Path to write the JUnit XML report to. If unset, JUnit reporting is disabled.
Documentation: JUnit support
Default: Unset
Example: junit.path = "target/nextest/junit.xml"

`profile.<name>.junit.report-name`¶

Type: String
Description: Name for the JUnit XML report.
Documentation: JUnit support
Default: "nextest-run"

`profile.<name>.junit.store-success-output`¶

Type: Boolean
Description: Whether to store successful test output in the JUnit XML report.
Documentation: JUnit support
Default: false

`profile.<name>.junit.store-failure-output`¶

Type: Boolean
Description: Whether to store failed test output in the JUnit XML report.
Documentation: JUnit support
Default: true

`profile.<name>.junit.flaky-fail-status`¶

0.9.131

Type: String
Description: How flaky-fail tests are reported in the JUnit XML report.
Documentation: JUnit support
Valid values: "failure" or "success"
Default: "failure"

Archive configuration¶

0.9.70

`profile.<name>.archive.include`¶

Type: Array of objects
Description: Extra paths to include in the archive.
Documentation: Archiving and reusing builds

Example:

[[profile.default.archive.include]]
path = "fixtures"
relative-to = "target"
depth = 2
on-missing = "warn"

Archive include parameters¶

path: Path to include, relative to relative-to.
relative-to: Base directory path is interpreted relative to. Valid values: "target".
depth: Maximum recursion depth (non-negative integer or "infinite").
on-missing: What to do if path is missing. Valid values: "ignore", "warn", "error".

Override configuration¶

Overrides allow you to customize settings for specific tests or platforms using [[profile.<name>.overrides]] sections.

For detailed information, see Per-test settings.

Override filters¶

At least one of these filters must be specified.

`filter`¶

Type: String (filterset expression)
Description: Filterset expression selecting tests this override applies to.
Documentation: Filterset DSL
Default: Override applies to all tests
Example: filter = 'test(integration_test)'

`platform`¶

0.9.58

Type: String or Object
Description: Host and/or target platforms this override applies to.
Documentation: Specifying platforms
Default: Override applies to all platforms

Examples:

platform = "x86_64-unknown-linux-gnu"
# or
platform = { host = "cfg(unix)", target = "aarch64-apple-darwin" }

Override settings¶

`default-filter`¶

0.9.84

Type: String (filterset expression)
Description: Replaces default-filter for matching platforms. Requires platform and must not be combined with filter.
Documentation: Running a subset of tests by default

`priority`¶

0.9.91

Type: Integer (-100 to 100)
Description: Priority for matching tests; higher values run sooner.
Documentation: Test priorities
Default: 0

Other settings¶

All profile-level settings can be overridden:

threads-required
run-extra-args
retries
flaky-result
slow-timeout
bench.slow-timeout
leak-timeout
test-group
success-output
failure-output
junit.store-success-output
junit.store-failure-output

Test group configuration¶

0.9.48

Custom test groups are defined under [test-groups.<name>] sections.

For detailed information, see Test groups for mutual exclusion.

`test-groups.<name>.max-threads`¶

Type: Integer or string
Description: Maximum number of threads this test group may use concurrently.
Valid values: Positive integer or "num-cpus"

Script configuration¶

0.9.59

Scripts are configured under [scripts.setup.<name>] and [scripts.wrapper.<name>] sections.

Setup scripts¶

0.9.98

For detailed information, see Setup scripts.

`scripts.setup.<name>.command`¶

Type: String, array, or object
Description: The command to run for this setup script.

Examples:

command = "echo hello"
# or
command = ["cargo", "run", "--bin", "setup"]
# or
command = { command-line = "debug/my-setup", relative-to = "target" }

`scripts.setup.<name>.slow-timeout`¶

Type: String (duration) or object
Description: Slow-timeout configuration for this setup script.
Default: No timeout

Examples:

slow-timeout = "30s"
# or
slow-timeout = { period = "60s", terminate-after = 1, grace-period = "5s" }

`scripts.setup.<name>.leak-timeout`¶

Type: String (duration) or object
Description: Leak-timeout configuration for this setup script.
Default: 200ms

Examples:

leak-timeout = "500ms"
# or
leak-timeout = { period = "1s", result = "fail" }

`scripts.setup.<name>.capture-stdout`¶

Type: Boolean
Description: Whether to capture stdout from this setup script.
Default: false

`scripts.setup.<name>.capture-stderr`¶

Type: Boolean
Description: Whether to capture stderr from this setup script.
Default: false

`scripts.setup.<name>.junit.store-success-output`¶

Type: Boolean
Description: Whether to store this setup script's output on success in the JUnit XML report.
Default: true

`scripts.setup.<name>.junit.store-failure-output`¶

Type: Boolean
Description: Whether to store this setup script's output on failure in the JUnit XML report.
Default: true

Wrapper scripts¶

0.9.98

For detailed information, see Wrapper scripts.

`scripts.wrapper.<name>.command`¶

Type: String, array, or object
Description: The command to run as the wrapper.

Examples:

command = "my-script.sh"
# or
command = ["cargo", "run", "--bin", "setup", "--"]
# or
command = { command-line = "debug/my-setup", relative-to = "target" }

`scripts.wrapper.<name>.target-runner`¶

Type: String
Description: How this wrapper composes with a configured target runner.
Documentation: Target runners
Valid values:
- "ignore": the target runner is ignored.
- "overrides-wrapper": when a target runner is configured, it replaces the wrapper; otherwise the wrapper runs as usual.
- "within-wrapper": the target runner runs within the wrapper script (command line: <wrapper> <target-runner> <test-binary> <args>).
- "around-wrapper": the target runner runs around the wrapper script (command line: <target-runner> <wrapper> <test-binary> <args>).
Default: "ignore"

Profile script configuration¶

0.9.59

Profile-specific script configuration under [[profile.<name>.scripts]] sections.

Profile script filters¶

At least one of these filters must be specified.

`platform`¶

Type: String or object
Description: Host and/or target platforms these scripts apply to.
Documentation: Specifying platforms
Default: Scripts apply to all platforms

Examples:

platform = "x86_64-unknown-linux-gnu"
# or
platform = { host = "cfg(unix)", target = "aarch64-apple-darwin" }

`filter`¶

Type: String (filterset expression)
Description: Filterset expression selecting tests these scripts apply to.
Documentation: Filterset DSL
Default: Scripts apply to all tests
Example: filter = 'test(integration_test)'

Profile script instructions¶

At least one instruction must be specified.

`setup`¶

Type: String or array of strings
Description: Names of setup scripts to run (single name or array).
Documentation: Setup scripts

Examples:

setup = "my-setup"
# or
setup = ["setup1", "setup2"]

`list-wrapper`¶

Type: String
Description: Name of the wrapper script used during test listing.
Documentation: Wrapper scripts
Example: list-wrapper = "my-list-wrapper"

`run-wrapper`¶

Type: String
Description: Name of the wrapper script used during test execution.
Documentation: Wrapper scripts
Example: run-wrapper = "my-run-wrapper"

Default configuration¶

The default configuration shipped with cargo-nextest is:

# This is the default config used by nextest. It is embedded in the binary at
# build time. It may be used as a template for .config/nextest.toml.

[store]
# The directory under the workspace root at which nextest-related files are
# written. Profile-specific storage is currently written to dir/<profile-name>.
dir = "target/nextest"

# This section defines the default nextest profile. Custom profiles are layered
# on top of the default profile.
[profile.default]
# The set of tests run by `cargo nextest run` by default.
default-filter = "all()"

# Retry policy for failed tests. A non-zero value causes tests that pass on a
# subsequent attempt to be marked as flaky. Can be overridden through the
# `--retries` option.
retries = 0

# Whether to treat flaky tests as passing or failing.
flaky-result = "pass"

# Number of threads to run tests with. Either an integer or "num-cpus". Can be
# overridden through the `--test-threads` option.
test-threads = "num-cpus"

# Number of threads (slots) each test reserves from the pool. Generally used in
# overrides to mark certain tests as heavier than others; can also be set as a
# global default.
threads-required = 1

# Extra arguments to pass to test binaries at runtime. Intended primarily for
# communication with custom test harnesses -- use with caution!
run-extra-args = []

# Level of status information to display during test runs.
#
# Can be overridden through the `--status-level` flag.
status-level = "pass"

# Level of status information to display in the final summary. Differs from
# status-level in that it has a separate "flaky" indicator distinct from
# "retry" (though "retry" works as an alias), and in that "skip" is prioritized
# over "pass".
final-status-level = "flaky"

# When to display output for failed tests.
#
# Can be overridden through the `--failure-output` option.
failure-output = "immediate"

# When to display output for successful tests. Generally best left as "never".
success-output = "never"

# Failure handling for the test run.
#
# For CI runs, consider setting this to false.
fail-fast = true

# Treat a test that takes longer than the configured 'period' as slow, and print
# a message. See <https://nexte.st/docs/features/slow-tests> for more
# information.
slow-timeout = { period = "60s", on-timeout = "fail" }

# Time after which benchmarks are considered slow, plus optional termination
# policy. Replaces `slow-timeout` when running `cargo nextest bench`.
# See <https://nexte.st/docs/features/slow-tests> for more information.
#
# Benchmarks have a separate configuration because they are often expected to
# take longer than tests. Defaults to 30 years, which is a large enough value
# to feel "infinite" without running into overflows on various platforms.
bench.slow-timeout = { period = "30y" }

# Global timeout for the entire benchmark run. Replaces `global-timeout` when
# running `cargo nextest bench`.
#
# Benchmarks have a separate configuration because they are often expected to
# take longer than tests. Defaults to 30 years, which is a large enough value
# to feel "infinite" without running into overflows on various platforms.
bench.global-timeout = "30y"

# Treat a test as leaky if after the process is shut down, standard output and
# standard error aren't closed within this duration.
#
# This usually happens in case of a test that creates a child process and lets
# it inherit those handles, but doesn't clean the child process up (especially
# when it fails).
#
# See <https://nexte.st/docs/features/leaky-tests> for more information.
leak-timeout = "200ms"

# Stop all tests after the configured global timeout.
#
# Defaults to 30 years, which is a large enough value to feel "infinite" without
# running into overflows on various platforms.
global-timeout = "30y"

# Extra paths to include in `nextest archive`. The standard build output is
# included automatically; use this to add any non-standard files the tests
# need at runtime.
archive.include = []

[profile.default.junit]
# Path to write the JUnit XML report to, relative to 'store.dir/<profile-name>'.
# If unset, JUnit reporting is disabled.

# path = "junit.xml"

# Name for the JUnit XML report. When aggregating reports across different test
# runs, it may be useful to provide separate names for each report.
report-name = "nextest-run"

# Whether to store successful test output in the JUnit XML report. When true,
# output is stored in the <system-out> and <system-err> elements of the
# <testcase> element.
store-success-output = false

# Whether to store failed test output in the JUnit XML report. When true,
# output is stored in the <system-out> and <system-err> elements of the
# <testcase> element.
#
# Note that if a description can be extracted from the output, it is always
# stored in the <description> element.
store-failure-output = true

# How flaky-fail tests are reported in the JUnit XML report. "failure" reports
# them as failures with <failure> and <flakyFailure> elements; "success"
# reports them as successes, identical to flaky-pass tests.
flaky-fail-status = "failure"

# This profile is activated if MIRI_SYSROOT is set.
[profile.default-miri]

Configuration reference¶

Configuration file locations¶

Repository configuration schema¶

Top-level configuration¶

nextest-version¶

experimental¶

store¶

store.dir¶

Profile configuration¶

General configuration¶

profile.<name>.inherits¶

Core test execution¶

profile.<name>.default-filter¶

profile.<name>.global-timeout¶

profile.<name>.test-threads¶

profile.<name>.threads-required¶

profile.<name>.run-extra-args¶

Retry configuration¶

profile.<name>.retries¶

profile.<name>.flaky-result¶

Timeout configuration¶

profile.<name>.slow-timeout¶

profile.<name>.leak-timeout¶

Benchmark configuration¶

profile.<name>.bench.global-timeout¶

profile.<name>.bench.slow-timeout¶

Reporter options¶

profile.<name>.status-level¶

profile.<name>.final-status-level¶

profile.<name>.failure-output¶

profile.<name>.success-output¶

Failure handling¶

profile.<name>.fail-fast¶

Test grouping¶

profile.<name>.test-group¶

JUnit configuration¶

profile.<name>.junit.path¶

profile.<name>.junit.report-name¶

profile.<name>.junit.store-success-output¶

profile.<name>.junit.store-failure-output¶

profile.<name>.junit.flaky-fail-status¶

Archive configuration¶

profile.<name>.archive.include¶

Archive include parameters¶

Override configuration¶

Override filters¶

filter¶

platform¶

Override settings¶

default-filter¶

priority¶

Other settings¶

Test group configuration¶

test-groups.<name>.max-threads¶

Script configuration¶

Setup scripts¶

scripts.setup.<name>.command¶

scripts.setup.<name>.slow-timeout¶

scripts.setup.<name>.leak-timeout¶

scripts.setup.<name>.capture-stdout¶

scripts.setup.<name>.capture-stderr¶

scripts.setup.<name>.junit.store-success-output¶

scripts.setup.<name>.junit.store-failure-output¶

Wrapper scripts¶

scripts.wrapper.<name>.command¶

scripts.wrapper.<name>.target-runner¶

Profile script configuration¶

Profile script filters¶

platform¶

filter¶

Profile script instructions¶

setup¶

list-wrapper¶

run-wrapper¶

Default configuration¶

`nextest-version`¶

`experimental`¶

`store`¶

`store.dir`¶

`profile.<name>.inherits`¶

`profile.<name>.default-filter`¶

`profile.<name>.global-timeout`¶

`profile.<name>.test-threads`¶

`profile.<name>.threads-required`¶

`profile.<name>.run-extra-args`¶

`profile.<name>.retries`¶

`profile.<name>.flaky-result`¶

`profile.<name>.slow-timeout`¶

`profile.<name>.leak-timeout`¶

`profile.<name>.bench.global-timeout`¶

`profile.<name>.bench.slow-timeout`¶

`profile.<name>.status-level`¶

`profile.<name>.final-status-level`¶

`profile.<name>.failure-output`¶

`profile.<name>.success-output`¶

`profile.<name>.fail-fast`¶

`profile.<name>.test-group`¶

`profile.<name>.junit.path`¶

`profile.<name>.junit.report-name`¶

`profile.<name>.junit.store-success-output`¶

`profile.<name>.junit.store-failure-output`¶

`profile.<name>.junit.flaky-fail-status`¶

`profile.<name>.archive.include`¶

`filter`¶

`platform`¶

`default-filter`¶

`priority`¶

`test-groups.<name>.max-threads`¶

`scripts.setup.<name>.command`¶

`scripts.setup.<name>.slow-timeout`¶

`scripts.setup.<name>.leak-timeout`¶

`scripts.setup.<name>.capture-stdout`¶

`scripts.setup.<name>.capture-stderr`¶

`scripts.setup.<name>.junit.store-success-output`¶

`scripts.setup.<name>.junit.store-failure-output`¶

`scripts.wrapper.<name>.command`¶

`scripts.wrapper.<name>.target-runner`¶

`platform`¶

`filter`¶

`setup`¶

`list-wrapper`¶

`run-wrapper`¶