Skip to content

Configuring nextest

cargo-nextest supports repository-specific configuration at the location .config/nextest.toml from the Cargo workspace root. The location of the configuration file can be overridden with the --config-file option.

For a comprehensive list of all configuration parameters, including default values, see Configuration reference.

Profiles

With cargo-nextest, local and CI runs often need to use different settings. For example, CI test runs should not be cancelled as soon as the first test failure is seen.

cargo-nextest supports multiple profiles, where each profile is a set of options for cargo-nextest. Profiles are selected on the command line with the -P or --profile option. Most individual configuration settings can also be overridden at the command line.

Here is a recommended profile for CI runs:

Configuring a CI profile in .config/nextest.toml
[profile.ci]
# Do not cancel the test run on the first failure.
fail-fast = false

After checking the profile into .config/nextest.toml, use cargo nextest --profile ci in your CI runs.

Default profiles

Nextest's embedded configuration may define new profiles whose names start with default- in the future. To avoid backwards compatibility issues, do not name custom profiles starting with default-.

Profile inheritance

0.9.115

By default, all custom profiles inherit their configuration from the profile named default. To inherit from another profile, specify the inherits key:

Inheriting from another profile in .config/nextest.toml
[profile.ci]
fail-fast = false
slow-timeout = "60s"

[profile.ci-extended]
inherits = "ci"
slow-timeout = "300s"

A series of profile inherits keys form an inheritance chain, and configuration lookups are done by iterating over the chain.

The default profile cannot inherit from another profile

The default profile cannot be made to inherit from another profile; it is always at the root of any inheritance chain.

Tool-specific configuration

Some tools that integrate with nextest may wish to customize nextest's defaults. However, in most cases, command-line arguments and repository-specific configuration should still override those defaults.

To support these tools, nextest supports the --tool-config-file argument. Values to this argument are specified in the form tool:/path/to/config.toml. For example, if your tool my-tool needs to call nextest with customized defaults, it should run:

cargo nextest run --tool-config-file my-tool:/path/to/my/config.toml

The --tool-config-file argument may be specified multiple times. Config files specified earlier are higher priority than those that come later.

Hierarchical configuration

Configuration is resolved in the following order:

  1. Command-line arguments. For example, if --retries=3 is specified on the command line, failing tests are retried up to 3 times.
  2. Environment variables. For example, if NEXTEST_RETRIES=4 is specified on the command line, failing tests are retried up to 4 times.
  3. Per-test overrides, if they're supported for this configuration variable.

  4. If a profile is specified, profile-specific configuration in .config/nextest.toml. For example, if the repository-specific configuration looks like:

    [profile.ci]
retries = 2

    then, if --profile ci is selected, failing tests are retried up to 2 times.

  5. If a profile is specified, tool-specific configuration for the given profile.

  6. For each profile in the inheritance chain, which always terminates at the default profile:

    1. Repository-specific configuration for that profile profile. For example, if the repository-specific configuration looks like: 

      [profile.ci-extended]
inherits = "ci"

[profile.ci]
retries = 5
      then, with the ci-extended profile, failing tests are retried up to 5 times.

    2. Tool-specific configuration for that profile.

  7. The default configuration, which is that tests are never retried.

See also