🎓 A1Learner
🔍

Rust Running Tests

The test runner is the cargo test command and its options. cargo test runs every test in a project.

Filter by name

A word from a test name is a filter. On this lesson's example program this runs add_two_and_two and add_three_and_two, and the report ends with 1 filtered out:

cargo test add

Run tests one at a time

This option runs the tests one after another, with no parallelism:

cargo test -- --test-threads=1

See the printing of passing tests

Output from println! in a test is captured: you see it only when the test fails. The -- in the command splits it in two. Options before -- go to Cargo. Options after -- go to the test program itself. This option is the test program's:

cargo test -- --show-output

Run only the ignored tests

--include-ignored does the opposite job: it runs everything, ignored tests included:

cargo test -- --ignored

One file from the tests folder

Replace api_checks with the name of a file in the tests/ folder, without the .rs ending:

cargo test --test api_checks

Run one test, exactly

A name filter matches substrings. It can catch cousins with similar names. The --exact switch takes the full path of one test, module and all:

cargo test -- --exact tests::adds_prices

Pick which tests to build

Three switches each choose one kind of target. --lib runs the unit tests inside the crate. --test names one file from tests/. --doc runs the doc examples:

cargo test --lib
cargo test --test api
cargo test --doc

Example

fn add_two(a: u64) -> u64 { a + 2 }
#[cfg(test)]
mod tests {
    use super::*;
    #[test] fn add_two_and_two() { assert_eq!(add_two(2), 4); }
    #[test] fn add_three_and_two() { assert_eq!(add_two(3), 5); }
    #[test] fn one_hundred() { assert_eq!(add_two(100), 102); }
}
fn main() { println!("add_two(2) = {}", add_two(2)); println!("cargo test add -> runs the 2 tests with add in the name"); }

Key points

  • Tests run in parallel by default, each in its own thread.
  • Never let tests share a file or other state.
  • They can break each other
  • A filter matches against the full path of a test.
  • cargo test discount also finds tests::discount::ten_percent_off.
  • cargo test -- --help lists the test program options.
  • The two helps are different on purpose.
  • cargo test runs every test in a project unless a filter or option narrows the run.

In this example, three tests guard one small function, and their names are chosen on purpose. Two names start with add_ and one does not. Running cargo test with no filter runs all three. Running cargo test add runs only add_two_and_two and add_three_and_two, and the report ends with "1 filtered out" for one_hundred. Running cargo test one_hundred runs just that one. main prints the same hint, so the program itself reminds you how the filter works.

Note

cargo test --help lists the Cargo options.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Rust Playground

Exercise

What does cargo test -- --test-threads=1 do?