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.
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
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.
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
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=1when 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 alib.rsto be testable this way. - Doc tests compile each fenced Rust block in a
///comment as a tiny program; mark blocksno_run,ignoreorshould_panicas needed.cargo test --docruns only those. cargo testbuilds with thetestprofile, which inherits fromdev; overflow checks anddebug_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::parseruns everything in that module.