Passing in extra arguments¶
Warning
This is an advanced feature, and it can cause your tests to silently stop working if used incorrectly. Use with caution.
In some situations, it can be helpful to pass extra arguments into a test binary
at runtime. Nextest supports run-extra-args for this purpose.
Use case: running tests on the main thread¶
In some environments like macOS, the initial thread created for the process, also known as the main thread or UI thread, is special. Tests in these environments will often require that they always be run on the main thread (see #1959). This is sometimes called "single-threaded mode", but that is a bit of a misnomer. What matters is that the main thread of the test is the same as the main thread of the process.
Even though nextest uses a separate process for each test, that isn't a guarantee that the test will be run on the main thread of the process. In fact, the standard libtest harness and most other harnesses will create a separate thread to run the test in, and use the main thread only to manage the test thread.
As a workaround, some custom test harnesses support passing in arguments to
force the test to run on the main thread. For example, with libtest-mimic,
passing in --test-threads=1 as an extra argument forces the test to run on the
main thread.
For more about custom test harnesses and libtest-mimic, see Custom test harnesses.
You must use a custom test harness
If your goal is to run tests on the main thread of their corresponding
processes, --test-threads=1 by itself will not by itself achieve that. The
standard libtest harness does not run tests on the main thread with
--test-threads=1: see Cargo issue #104053.
You must also use a custom test harness. Our recommendation is
libtest-mimic, which follows this behavior with --test-threads=1.
You may also use another custom test harness, though note the compatibility
rules. Your harness may use a different argument for this purpose; in that
case, replace --test-threads=1 with the appropriate argument in the
examples below.
Defining extra arguments¶
Extra arguments are typically defined via per-test settings.
To run all tests in the gui package's tests/custom-tests.rs target
with the --test-threads=1 argument:
.config/nextest.toml[[profile.default.overrides]]
filter = "binary_id(gui::custom-tests)"
run-extra-args = ["--test-threads=1"]
The binary_id predicate accepts names shown during cargo nextest run; see
Binary IDs for more.
You can also define extra arguments that apply to all tests:
[profile.default]
run-extra-args = ["--test-threads=1"]
If libtest-mimic is in use, the above configuration will run tests on the main thread. (Nextest's CI validates this.)
Notes¶
Extra arguments are not passed in at list time, only at runtime. List-time extra arguments may be supported in the future if there's a compelling use case.
Extra arguments are passed directly to the test binary, and nextest does not interpret them in any way. Passing in the wrong arguments can cause your tests to silently stop working.