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.

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 = ["--nocapture"]

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

For detailed information, see Per-test overrides.

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 = "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

`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

`filter`¶

Type: String (filterset expression)
Description: Test filter for when scripts apply
Documentation: Filterset DSL

Profile script instructions¶

`setup`¶

Type: String or array of strings
Description: Setup script(s) to run

`list-wrapper`¶

Type: String
Description: Wrapper script to use during test listing

`run-wrapper`¶

Type: String
Description: Wrapper script to use during test execution

Configuration file precedence¶

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

Configuration reference¶

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¶

Configuration file precedence¶

`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`¶