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):

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 thhe Hierarchical configuration.

Top-level configuration¶

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

`nextest-version`¶

Type: String or object
Description: Specifies the minimum required version of nextest
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 features
Documentation: Setup scripts, wrapper scripts
Default: []: no experimental features are enabled
Valid values: ["setup-scripts", "wrapper-scripts"]
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].

Core test execution¶

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

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

`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 requires
Documentation: Heavy tests and threads-required
Valid values: Positive integer, "num-cpus", or "num-test-threads"
Default: 1

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

Type: Array of strings
Description: Extra arguments to pass to test binaries
Documentation: Extra arguments
Default: []: no extra arguments
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 }

Timeout configuration¶

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

Type: String (duration) or object
Description: Time after which tests are considered slow, and timeout configuration
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" }

`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" }

Reporter options¶

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

Type: String
Description: Level of status information to display during test runs
Documentation: Reporting test results
Valid values: "none", "fail", "retry", "slow", "leak", "pass", "skip", "all"
Default: "pass"

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

Type: String
Description: Level of status information to display in final summary
Documentation: Reporting test results
Valid values: "none", "fail", "flaky", "slow", "skip", "leak", "pass", "all"
Default: "fail"

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

Type: String
Description: When to display output for failed tests
Documentation: Reporting test results
Valid values: "immediate", "immediate-final", "final", "never"
Default: "immediate"

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

Type: String
Description: When to display output for successful tests
Documentation: Reporting test results
Valid values: "immediate", "immediate-final", "final", "never"
Default: "never"

Failure handling¶

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

Type: Boolean or object
Description: Controls when to stop running tests after failures
Documentation: Failing fast

Examples:

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

Test grouping¶

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

Type: String
Description: Assigns tests to a custom 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 JUnit XML report
Documentation: JUnit support
Default: JUnit support is disabled
Example: junit.path = "target/nextest/junit.xml"

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

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

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

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

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

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

Archive configuration¶

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

Type: Array of objects
Description: Files to include when creating test archives
Documentation: Archiving and reusing builds

Example:

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

Archive include parameters¶

path: Relative path to include
relative-to: Base directory ("target")
depth: Maximum recursion depth (integer or "infinite")
on-missing: What to do if path is missing ("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: Selects which tests this override applies to
Documentation: Filterset DSL
Default: Override applies to all tests
Example: filter = 'test(integration_test)'

`platform`¶

Type: String or Object
Description: Platform specification for when override applies
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`¶

Type: String (filterset expression)
Description: Override the default filter for specific platforms
Documentation: Running a subset of tests by default
Note: Can only be used with platform specification

`priority`¶

Type: Integer (-100 to 100)
Description: Test priority (a greater number means a higher priority)
Documentation: Test priorities
Default: 0

Other settings¶

All profile-level settings can be overridden:

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

Test group configuration¶

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 can use
Valid values: Positive integer or "num-cpus"

Script configuration¶

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

Setup scripts¶

For detailed information, see Setup scripts.

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

Type: String, array, or object
Description: The command to execute

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: Timeout configuration for the 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 for the setup script
Default: 100ms

Examples:

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

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

Type: Boolean
Description: Whether to capture stdout from the script
Default: false

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

Type: Boolean
Description: Whether to capture stderr from the script
Default: false

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

Type: Boolean
Description: Store successful script output in JUnit
Default: true

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

Type: Boolean
Description: Store failed script output in JUnit
Default: true

Wrapper scripts¶

For detailed information, see Wrapper scripts.

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

Type: String, array, or object
Description: The wrapper command to execute

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 to interact with the configured target runner
Documentation: Target runners
Valid values: "ignore", "overrides-wrapper", "within-wrapper", "around-wrapper"
Default: "ignore"

Profile script configuration¶

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: Platform specification for when scripts apply
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: Test filter for when scripts apply
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: Setup script(s) to run
Documentation: Setup scripts

Examples:

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

`list-wrapper`¶

Type: String
Description: Wrapper script to use during test listing
Documentation: Wrapper scripts
Example: list-wrapper = "my-list-wrapper"

`run-wrapper`¶

Type: String
Description: Wrapper script to use 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()"

# "retries" defines the number of times a test should be retried. If set to a
# non-zero value, tests that succeed on a subsequent attempt will 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

# The number of threads to run tests with. Supported values are either an integer or
# the string "num-cpus". Can be overridden through the `--test-threads` option.
test-threads = "num-cpus"

# The number of threads required for each test. This is generally used in overrides to
# mark certain tests as heavier than others. However, it can also be set as a global parameter.
threads-required = 1

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

# Show these test statuses in the output.
#
# The possible values this can take are:
# * none: no output
# * fail: show failed (including exec-failed) tests
# * retry: show flaky and retried tests
# * slow: show slow tests
# * pass: show passed tests
# * skip: show skipped tests (most useful for CI)
# * all: all of the above
#
# Each value includes all the values above it; for example, "slow" includes
# failed and retried tests.
#
# Can be overridden through the `--status-level` flag.
status-level = "pass"

# Similar to status-level, show these test statuses at the end of the run.
final-status-level = "flaky"

# "failure-output" defines when standard output and standard error for failing tests are produced.
# Accepted values are
# * "immediate": output failures as soon as they happen
# * "final": output failures at the end of the test run
# * "immediate-final": output failures as soon as they happen and at the end of
#   the test run; combination of "immediate" and "final"
# * "never": don't output failures at all
#
# 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"

# "success-output" controls production of standard output and standard error on success. This should
# generally be set to "never".
success-output = "never"

# Cancel the test run on the first failure. For CI runs, consider setting this
# to false.
# Accepted values are
# * true: cancel the test run on the first failure
# * false: continue running tests even after a failure
# * { max-fail = 10 }: cancel the test run after the specified number of failures
# * { max-fail = "all" }: continue running tests even after a failure
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 }
slow-timeout = { period = "60s" }

# 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 = "100ms"

# `nextest archive` automatically includes any build output required by a standard build.
# However sometimes extra non-standard files are required.
# To address this, "archive.include" specifies additional paths that will be included in the archive.
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" will be included recursively in the archive.
    # * the file "target/data-from-some-dependency/file.txt" will be included in the archive.
]

[profile.default.junit]
# Output a JUnit report into the given file inside 'store.dir/<profile-name>'.
# If unspecified, JUnit is not written out.

# path = "junit.xml"

# The name of the top-level "report" element in JUnit report. If aggregating
# reports across different test runs, it may be useful to provide separate names
# for each report.
report-name = "nextest-run"

# Whether standard output and standard error for passing tests should be stored in the JUnit report.
# Output is stored in the <system-out> and <system-err> elements of the <testcase> element.
store-success-output = false

# Whether standard output and standard error for failing tests should be stored in the JUnit report.
# 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

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

Configuration reference¶

Configuration file locations¶

Top-level configuration¶

nextest-version¶

experimental¶

store¶

store.dir¶

Profile configuration¶

Core test execution¶

profile.<name>.default-filter¶

profile.<name>.test-threads¶

profile.<name>.threads-required¶

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

Retry configuration¶

profile.<name>.retries¶

Timeout configuration¶

profile.<name>.slow-timeout¶

profile.<name>.leak-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¶

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>.default-filter`¶

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

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

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

`profile.<name>.retries`¶

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

`profile.<name>.leak-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>.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`¶