Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Tools

cargo test

Reference for cargo test: unit, integration and doc tests, filtering by name, --nocapture, --test-threads, --ignored, --no-fail-fast and the test harness.

cargo test compiles your package in test mode and runs every test it finds: unit tests (functions marked #[test] inside the crate, usually in a #[cfg(test)] mod tests), integration tests (files in the tests/ directory, each compiled as its own crate), and documentation tests (code blocks in /// comments of a library).

Tests run in parallel on several threads. The output of a passing test is hidden, a failing test shows what it printed, and the run ends with a summary line. The command is read-only on this site; the runnable examples call test-style functions by hand so you can see the assertions behave.

Terminal
cargo test                       # everything
cargo test parse                 # only tests whose name contains "parse"
cargo test -- --nocapture        # show println! output of passing tests
cargo test -- --ignored          # run only #[ignore] tests

Try it

Rust What a test body does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Test functions can return Result

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Terminal
cargo test [options] [testname] [-- test-binary-options]

Options before -- belong to Cargo; options after -- go to the test harness.

Cargo option Description
testname Run tests whose full path contains this text.
--lib, --bins, --test <file>, --doc, --examples Choose which kinds of tests to run.
--no-run Build the tests without running them.
--no-fail-fast Keep going after a test binary fails.
--release Run tests with optimizations.
-p, --workspace, --features Package and feature selection.
Harness option (after --) Description
--nocapture Do not capture output; printing from passing tests shows up.
--test-threads=N Number of parallel threads; 1 runs serially.
--ignored Run only #[ignore] tests. --include-ignored runs everything.
--exact Match the name exactly instead of by substring.
--skip <text> Skip tests whose name contains the text.
--list Print the test names without running.
--show-output Print captured output of passing tests at the end.

Usage notes

  • A test passes if it returns normally (or returns Ok(()) / ExitCode::SUCCESS) and fails if it panics. #[should_panic] flips that.
  • Tests share a process, so global state (environment variables, the current directory, files with the same name) can make them interfere. Use unique temp names or --test-threads=1 when needed.
  • println! output is captured per test and shown only on failure, unless you pass --nocapture.
  • Integration tests in tests/ can only use the public API, the way a user of your crate would. Binary crates need their logic in a lib.rs to be testable this way.
  • Doc tests compile each fenced Rust block in a /// comment as a tiny program; mark blocks no_run, ignore or should_panic as needed. cargo test --doc runs only those.
  • cargo test builds with the test profile, which inherits from dev; overflow checks and debug_assert! are on.
  • Benchmarks marked #[bench] need nightly Rust; use a crate like Criterion on stable.
  • A name filter matches substrings of the module path, so cargo test tests::parse runs everything in that module.