skip to content

With `cargo test`, how do you run a single test by name, see its `println!` output, and run tests one at a time?

level: middleimportance: should knowfreq 50%

answer

  1. two audiences on one line
  2. a substring of the test path
  3. the harness captures output
  4. threads belong to the harness

basics

~20 s

Pass the name as a filter and put harness options after the double dash: cargo test counts_spaces -- --no-capture --test-threads=1. The filter matches substrings of test paths, and options after -- go to each test binary, not to Cargo.

solid answer

~40 s

A `cargo test` command line has two audiences. Options before `--` go to Cargo, such as `--lib`, `--test cli`, `--doc` or `--release`. The positional name and everything after `--` go to the libtest harness inside each test binary. The name is a **filter**: every test whose full path, like `tests::counts_spaces`, contains the string runs, and `-- --exact` makes it an exact match. The harness captures each test's output and prints it only when the test fails, so `-- --no-capture` lets `println!` through as tests run, while `-- --show-output` prints passing tests' output at the end. Rust 1.88 deprecated the older `--nocapture` spelling, which still works as an alias. Tests run on several threads by default, so `-- --test-threads=1` runs them one at a time; written before `--`, Cargo rejects that flag.

code

console · 21 lines
console
$ cargo test counts_spaces -- --no-capture
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running unittests src/lib.rs (target/debug/deps/tally-121494a682b7cb72)

running 1 test
checking a padded line
test tests::counts_spaces ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/tally-2ee636d7ddadbfb4)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running tests/cli.rs (target/debug/deps/cli-1d3aa4394caf5e11)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s

go deeper

for a junior

Recall the double dash rule: Cargo's flags first, then the filter and harness flags such as --no-capture after the separator.

for a middle

Explain that the filter is a substring match applied inside every test binary, that capture hides passing output, and that --test-threads is separate from Cargo's -j.

for a senior

Show how you would chase a flaky shared-state test: isolate it with --exact, serialise with --test-threads=1, read output with --show-output, and narrow the build with --test or --lib.

for a principal

Discuss when serialising tests hides a design problem, such as shared global state, and when a team should fix isolation rather than standardise on one test thread.

## Two audiences on one command line `cargo test` compiles each test target into its own executable, linked with **libtest**, the test harness that ships with Rust, and then runs those executables one after another. The command line is split between the two programs: | Where it is written | Who reads it | Examples | |---|---|---| | Before `--` | Cargo | `--lib`, `--test cli`, `--doc`, `--release`, `-p NAME`, `-j N` | | The positional `TESTNAME` | libtest, in every test binary | `cargo test counts_spaces` | | After `--` | libtest, in every test binary | `--no-capture`, `--test-threads=1`, `--exact`, `--show-output` | The Cargo docs give the rule directly: "the ones after -- go to the binary, the ones before go to Cargo." Cargo enforces it. `cargo test --test-threads=1` fails with "unexpected argument '--test-threads' found", and Cargo's tip points out that `--test` is a different flag and that the value belongs after `--`. ## Filters select tests inside every binary A positional argument without a leading dash is a **filter**. The rustc book's chapter on tests says it matches "any substring found in the full path of the test function", where the path includes the module, as in `tests::counts_spaces`. - `cargo test spaces` runs every test whose path contains `spaces`. - `cargo test -- --exact tests::counts_spaces` requires the full path to match. - `cargo test -- --skip slow` excludes tests whose names contain `slow`, and may be repeated. - `cargo test -- --ignored` runs only tests marked `#[ignore]`; `--include-ignored` runs both kinds. Cargo still builds and runs every selected test binary; the filter is applied inside each one. That is why the session in the code example shows `tests/cli.rs` running with "1 filtered out". In the Cargo 1.99.1 run behind this answer, a bare name filter did not start the doc-test step at all; to filter documentation tests, use `cargo test --doc NAME`. ## Seeing output By default libtest **captures** each test's stdout and stderr and prints them only for tests that fail, which keeps a passing run readable. Two harness options change that: 1. `--no-capture` lets output through as each test runs. The rustc book lists `--nocapture` as a deprecated alias, a change made in Rust 1.88, so older scripts keep working. 2. `--show-output` prints the captured output of successful tests after the run, grouped per test. The rustc book recommends it over `--no-capture` when tests run in parallel, because live output from several threads interleaves. ## Running one test at a time libtest runs the tests of one binary on several threads; by default it uses the hardware concurrency reported by `std::thread::available_parallelism`. Tests that share a file, a port or an environment variable can then interfere. `-- --test-threads=1` runs them sequentially. The `RUST_TEST_THREADS` environment variable does the same, but the rustc book marks it as deprecated. Cargo's own `-j N` is not a substitute. The Cargo docs note that `--jobs` "affects the building of the test executable but does not affect how many threads are used when running the tests", and give `cargo test -j 2 -- --test-threads=2` as the way to set both. Separate test binaries are already run one after another. ## Narrowing by target first Filtering by name still compiles every test target. Target flags, written before `--`, limit what gets built and run: - `--lib` runs only the library's unit tests. - `--test cli` runs only the integration test `tests/cli.rs`, building just it and what it links against, the library and any binaries; `cargo test --test cli -- counts_from_library` narrows further. - `--doc` runs only the library's documentation tests, and cannot be mixed with other target flags. - `--bins` or `--bin NAME` runs unit tests inside binaries. Writing the tests themselves, with `#[test]`, `#[cfg(test)]` modules, integration crates and doctests, is the Rust language material on testing; these flags only choose and configure what runs. ## Mistakes interviewers listen for - Putting harness flags such as `--test-threads` or `--no-capture` before `--`. - Believing a filter must be the exact function name, or that it stops Cargo from building other test files. - Using `-j 1` to serialise tests. - Leaving shared-state tests flaky instead of either isolating them or running them with `--test-threads=1`.

  • Why does `cargo test -j 1` not stop tests from running in parallel?
    `-j` limits how many compile jobs Cargo runs while building the test executables. The number of threads each test binary uses is a libtest setting, so it goes after the double dash: `cargo test -- --test-threads=1`. The Cargo docs show both together as `cargo test -j 2 -- --test-threads=2`.
  • How do you run one test from one integration-test file without building the other test targets?
    Select the target before the double dash and the test after it: `cargo test --test cli -- counts_from_library`. `--test cli` runs only `tests/cli.rs`, building the library and binaries it may need but no other test target, and the filter then picks the test inside it. Add `-- --exact` with the full path when names overlap.
  • When is `--show-output` a better choice than `--no-capture`?
    When tests run in parallel. `--no-capture` prints output live, so lines from several threads interleave. `--show-output` keeps capturing and prints each successful test's output in its own block after the run, which reads cleanly without forcing `--test-threads=1`.

  • cargo test --test-threads=1 runs the tests one at a time
  • a test filter has to be the exact function name, module path included
  • cargo test -j 1 makes the harness run tests sequentially
  • output from passing tests is discarded and cannot be shown
  • Cargo skips building test files whose tests do not match the filter

Assumes Rust 1.99; libtest documents --no-capture and keeps --nocapture as a deprecated alias, a change listed in the Rust 1.88 release notes.