Skip to content

User configuration

0.9.118

In addition to repository configuration, nextest supports user-specific configuration. User config stores personal preferences like UI settings.

Configuration file location

Nextest looks for user configs at the following locations:

Platform Primary path Fallback path
Linux, macOS, and other Unix $XDG_CONFIG_HOME/nextest/config.toml or ~/.config/nextest/config.toml —
Windows %APPDATA%\nextest\config.toml %XDG_CONFIG_HOME%\nextest\config.toml or %HOME%\.config\nextest\config.toml

On Windows, both the native path (%APPDATA%) and the XDG path (%HOME%\.config) are checked in order. This allows users who manage dotfiles across platforms to use ~/.config/nextest/config.toml on Windows as well.

User configuration is not merged; the first matching path is always used.

Configuration hierarchy

User config settings are resolved with the following precedence (highest priority first):

  1. CLI arguments (e.g., --show-progress=bar).
  2. Environment variables (e.g., NEXTEST_SHOW_PROGRESS=bar).
  3. User overrides (first matching [[overrides]] for each setting).
  4. User base config ([ui] section).
  5. Built-in defaults.

This means CLI arguments and environment variables always override user config.

Platform-specific overrides

You can customize settings for specific platforms using [[overrides]] sections:

Platform-specific overrides
[ui]
# Base settings for all platforms.
show-progress = "auto"
max-progress-running = 8

[[overrides]]
# Windows-specific settings.
platform = "cfg(windows)"
ui.max-progress-running = 4

0.9.134 Overrides are evaluated against the build target: the platform nextest was compiled for. In earlier versions, the build target was used in some cases and the host platform in others. See the user config reference for details.

User config vs. per-test overrides

0.9.134 The platform spec is matched against nextest's build target. In most cases, this is the same as the host platform. But it can sometimes differ, for example when running a musl-targeted nextest binary on a glibc (-gnu) host. In this case, the build target is x86_64-unknown-linux-musl or aarch64-unknown-linux-musl, while the host platform is the corresponding -gnu platform.

This is distinct from the platform field in per-test overrides, which is matched against the host or target platform of the tests being run.

User config versus repository config

User config primarily affects UI, display settings, and optional features like recording—it does not change test execution behavior. For test execution settings like retries, timeouts, and test groups, use repository configuration.

Example configuration

User configuration in ~/.config/nextest/config.toml
# Enable experimental features.
[experimental]
record = true

[ui]
# Always show a progress bar.
show-progress = "bar"

# Show more running tests in the progress output.
max-progress-running = 16

# Disable keyboard input handling.
input-handler = false

# Disable indentation for captured test output.
output-indent = false

[record]
# Enable recording (requires [experimental] record = true).
enabled = true

For a complete list of available settings, see the user config reference.

See also