Skip to content

Target runners

If you're cross-compiling Rust code, you may wish to run tests through a wrapper executable or script. For this purpose, nextest supports target runners, using the same configuration options used by Cargo:


If you're on Linux cross-compiling to Windows, you can choose to run tests through Wine.

If you add the following to .cargo/config.toml:

runner = "wine"

Or, in your shell:


Then, running this command will cause your tests to be run as wine <test-binary>:

cargo nextest run --target x86_64-pc-windows-msvc

Shell scripts on macOS

If your target runner is a shell script, it might malfunction on macOS due to System Integrity Protection (SIP)'s environment sanitization. Nextest provides the NEXTEST_LD_* and NEXTEST_DYLD_* environment variables as workarounds. For more, see Dynamic linker environment variables.


While cross-compiling code, some tests may need to be run on the host platform. (See Filtering by build platform for more.)

For tests that run on the host platform, nextest uses the target runner defined for the host.

For example, if cross-compiling from x86_64-unknown-linux-gnu to x86_64-pc-windows-msvc, nextest will use:

  • CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER for proc-macro and other host-only tests
  • CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_RUNNER for other tests.

This behavior is similar to that of per-test overrides.

Debugging output

Nextest invokes target runners during both the list and run phases. During the list phase, nextest has stringent rules for the contents of standard output.

If a target runner produces debugging or any other kind of output, it MUST NOT go to standard output. Instead, you can produce output to standard error, to a file on disk, etc.

For example, this target runner will not work:

echo "This is some debugging output"

Instead, redirect debugging output to standard error:

echo "This is some debugging output" >&2