Skip to content

Environment variables

This section contains information about the environment variables nextest reads and sets.

Environment variables nextest reads

Nextest reads some of its command-line options as environment variables. In all cases, passing in a command-line option overrides the respective environment variable.

NEXTEST_PROFILE
Nextest profile to use while running tests
NEXTEST_TEST_THREADS
Number of tests to run simultaneously
NEXTEST_RETRIES
Number of times to retry running tests
NEXTEST_HIDE_PROGRESS_BAR
If set to 1, always hide the progress bar
NEXTEST_STATUS_LEVEL
Status level during test runs (see Status levels)
NEXTEST_FINAL_STATUS_LEVEL
Status level at the end of a test run (see Status levels)
NEXTEST_SUCCESS_OUTPUT
Display output for passing tests (see Displaying captured test output)
NEXTEST_FAILURE_OUTPUT
Display output for failing tests (see Displaying captured test output)
NEXTEST_VERBOSE
Verbose output

Nextest also reads the following environment variables to emulate Cargo's behavior.

CARGO
Path to the cargo binary to use for builds
CARGO_TARGET_DIR
Where to place generated artifacts
CARGO_TARGET_<triple>_RUNNER
Support for target runners
CARGO_TERM_COLOR
Default color mode: always, auto, or never

Nextest delegates to Cargo for the build, which recognizes a number of environment variables. See Environment variables Cargo reads for a full list.

Environment variables nextest sets

Nextest exposes these environment variables to your tests at runtime only. They are not set at build time because cargo-nextest may reuse builds done outside of the nextest environment.

NEXTEST
Always set to "1".
NEXTEST_RUN_ID
Set to a UUID corresponding to a particular nextest run.
NEXTEST_EXECUTION_MODE
Currently, always set to process-per-test. More options may be added in the future if nextest gains the ability to run all tests within the same process (#27).
NEXTEST_BIN_EXE_<name>
The absolute path to a binary target's executable. This is only set when running an integration test or benchmark. The <name> is the name of the binary target, exactly as-is. For example, NEXTEST_BIN_EXE_my-program for a binary named my-program.

Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.

When reusing builds from an archive, this is set to the remapped path within the target directory.

NEXTEST_LD_* and NEXTEST_DYLD_*
Replicate the values of any environment variables that start with the prefixes LD_ or DYLD_, such as LD_PRELOAD or DYLD_FALLBACK_LIBRARY_PATH.

This is a workaround for macOS's System Integrity Protection environment sanitization. For more, see Dynamic linker environment variables.

For consistency, NEXTEST_LD_* and NEXTEST_DYLD_* are exported on all platforms, not just macOS.

Nextest delegates to Cargo for the build, which controls the environment variables that are set. See Environment variables Cargo sets for crates for a full list.

Nextest also sets these environment variables at runtime, matching the behavior of cargo test:

CARGO
Path to the cargo binary performing the build.

This is set by Cargo, not nextest, so if you invoke nextest with cargo-nextest nextest run it will not be set.

CARGO_MANIFEST_DIR
The directory containing the manifest of the test's package.

If --workspace-remap is passed in, this is set to the remapped manifest directory. You can obtain the non-remapped directory using the value of this variable at compile-time, e.g. env!("CARGO_MANIFEST_DIR").

CARGO_PKG_VERSION
The full version of the test's package.
CARGO_PKG_VERSION_MAJOR
The major version of the test's package.
CARGO_PKG_VERSION_MINOR
The minor version of the test's package.
CARGO_PKG_VERSION_PATCH
The patch version of the test's package.
CARGO_PKG_VERSION_PRE
The pre-release version of the test's package.
CARGO_PKG_AUTHORS
Colon-separated list of authors from the manifest of the test's package.
CARGO_PKG_NAME
The name of the test's package.
CARGO_PKG_DESCRIPTION
The description from the manifest of the test's package.
CARGO_PKG_HOMEPAGE
The home page from the manifest of the test's package.
CARGO_PKG_REPOSITORY
The repository from the manifest of the test's package.
CARGO_PKG_LICENSE
The license from the manifest of the test's package.
CARGO_PKG_LICENSE_FILE
The license file from the manifest of the test's package.
OUT_DIR
The path to the test's build script output directory.

Only set if the crate has a build script.

Additionally, the following environment variables are also set:

Dynamic library paths

Nextest sets the dynamic library path at runtime, similar to what Cargo does. This helps with locating shared libraries that are part of the build process. The variable name depends on the platform:

  • Windows: PATH
  • macOS: DYLD_FALLBACK_LIBRARY_PATH
  • Unix: LD_LIBRARY_PATH

Nextest includes the following paths:

  • Search paths included from any build script with the rustc-link-search instruction. Paths outside of the target directory are removed. If additional libraries on the system are needed in the search path, consider using a setup script to configure the environment.
  • The base output directory, such as target/debug, and the "deps" directory. This enables support for dylib dependencies and rustc compiler plugins.
  • 0.9.72 The rustc sysroot library path, to enable proc-macro tests and binaries compiled with -C prefer-dynamic to work.

Altering the environment within tests

(The information in this section is true as of Rust 1.84. We'll update this section in the unlikely event that changes occur.)

Many tests will want to alter their own environment variables1. The std::env::set_var and std::env::remove_var functions are unsafe in general, and can lead to races if another thread is accessing (writing to or reading from) the environment at the same time.

In particular, the safety contract for set_var and remove_var requires at least one of these three statements to be true:

  1. The program is single-threaded.
  2. The underlying implementations of set_var and remove_var are thread-safe. This is true on Windows, and on some Unix platforms like illumos. Notably, this is not true on Linux.
  3. While these functions are being called, no code is simultaneously accessing the environment other than through Rust's std::env module. (For example, no C code is accessing the environment.)

Nextest runs each test in its own process. Does that make it safe to alter the environment in tests? The answer is generally yes. Let's look at this case-by-case.

This does not apply to cargo test

The discussion below only applies to tests run via nextest's process-per-test model.

cargo test runs many tests in the same process, so one has to be much more cautious. A more detailed analysis of cargo test is out of scope for this discussion.

A standard test

When nextest starts a standard test annotated with #[test] (also known as a libtest test), the resulting process has two threads:

  • The main thread, used to monitor the test.
  • The test thread.

So the test process is multithreaded, making statement 1 above false.

But with current versions of Rust, while the test thread is running, the main thread does not read or write environment variables.

This is unlikely to ever change—there is no reason for the main thread to ever access the environment, and doing so would likely break many existing tests. So statement 3 is true.

In other words, if the test itself hasn't created any threads yet, it is de facto safe to alter the environment.

Alter the environment at the beginning of tests

Practically speaking, it is best to call set_var and remove_var at the very beginning of tests, before there's the chance for any threads to be created.

A test under a custom test harness

Custom test harnesses may run arbitrary code before test execution, so it's hard to make a general statement.

With the recommended libtest-mimic harness, the environment is not accessed while tests are running, so statement 3 above is true.

In addition, libtest-mimic can be forced to not create any threads by passing in extra arguments. Not creating a thread for the test makes statements 1 and 3 above both true.

This means that if you're using libtest-mimic directly, with or without extra arguments, it is safe to alter the environment.

Harnesses written on top of libtest-mimic might create their own threads, though. You're encouraged to analyze the harnesses you're using.

The datatest-stable harness

The datatest-stable harness maintained by the nextest organization does not spin up any threads, so it is safe to alter the environment at the beginning of tests.

Tests annotated with custom proc-macros

Some tests use a procedural macro that generates a wrapper #[test] function. One common example is the #[tokio::test] macro.

Like with custom test harnesses, these wrappers can run arbitrary code before test execution, so a general statement cannot be made. One would have to analyze the generated code and the runtime to make a complete determination.

It's worth looking at #[tokio::test] as an example:

  • By default, the macro runs Tokio in single-threaded mode. This case is equivalent to a standard test, so it is safe to alter the environment.

  • If flavor = "multi_thread" is specified, #[tokio::test] does create at least one worker thread.

    However, the Tokio runtime does not access the environment after the worker thread pool is created, and any other worker threads are dormant at the beginning of the test.

    So statement 3 remains true, and it is safe to alter the environment at the beginning of tests.

For test harness and proc-macro maintainers

If you maintain a custom test harness or proc-macro, it is recommended that you document environment safety as a property.

It is safe for nextest users to alter the environment at the beginning of tests, as long as you can guarantee that created threads, if any, won't access the environment concurrently.

(This may not be true for cargo test users due to its shared-process model. Be sure to make this clear in your documentation.)

  1. In general, altering the current process's environment variables is fraught with peril since it touches shared mutable state, but tests are a reasonable use case for this functionality. The cargo-nextest binary never alters its environment variables, but many of nextest's own tests do so. ↩