Skip to content

Configuration reference

This page provides a comprehensive reference of all configuration parameters available in nextest.

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

Configuration file locations

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

  1. Repository config (.config/nextest.toml)
  2. Tool-specific configs (specified via --tool-config-file)
  3. 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:
  • 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: 60s with no termination on timeout
  • 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

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.
# Examples:
# * retries = 3
# * retries = { backoff = "fixed", count = 2, delay = "1s" }
# * retries = { backoff = "exponential", count = 10, delay = "1s", jitter = true, max-delay = "10s" }
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.
#
# Status levels are incremental: each level includes all levels above it. For
# example, "slow" implies "retry" and "fail".
#
# Valid values:
# * "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.
#
# 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.
#
# Valid values:
# * "immediate": show captured output as soon as the test completes.
# * "final": show captured output only at the end of the run.
# * "immediate-final": show captured output when the test completes and again
#   at the end of the run.
# * "never": never show captured output.
#
# For large test suites and CI it is generally useful to use "immediate-final".
#
# 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. Accepted values:
# * true: stop running tests after the first failure (waits for running tests
#   to complete).
# * false: run all tests regardless of failures.
# * { max-fail = 10 }: stop after 10 failures (waits for running tests).
# * { max-fail = 10, terminate = "wait" }: same as above (explicit).
# * { max-fail = 10, terminate = "immediate" }: stop and terminate running
#   tests immediately.
# * { max-fail = "all" }: run all tests regardless of failures.
#
# 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.
#
# Optional: specify the parameter 'terminate-after' with a non-zero integer,
# which will cause slow tests to be terminated after the specified number of
# periods have passed.
# Example: slow-timeout = { period = "60s", terminate-after = 2 }
#
# The 'on-timeout' parameter controls whether timeouts are treated as failures (the default)
# or successes.
# Example: slow-timeout = { period = "60s", on-timeout = "pass" }
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.
#
# Optional: specify the parameter 'terminate-after' with a non-zero integer,
# which will cause slow benchmarks to be terminated after the specified number of
# periods have passed.
# Example: bench.slow-timeout = { period = "60s", terminate-after = 2 }
#
# 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 = [
    # Examples:
    #
    # { path = "application-data", relative-to = "target" },
    # { path = "data-from-some-dependency/file.txt", relative-to = "target" },
    #
    # In the above example:
    # * the directory and its contents at "target/application-data" are
    #   included recursively in the archive.
    # * the file "target/data-from-some-dependency/file.txt" is included in
    #   the archive.
]

[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]