Skip to content
Tutorials Center
My learning

Topics

Lesson 96 of 132 ยท Testing and Tooling

Testing in Rust

Learn Rust testing: #[test] functions, assert!, assert_eq!, should_panic, Result-returning tests, unit versus integration tests, cargo test output and a runnable test harness.

Code that you have not tested is code you hope works. Rust makes testing a first-class part of the language: there is a built-in #[test] attribute, a set of assertion macros in the standard library, and a test runner shipped inside cargo. You need no framework, no configuration file and no extra dependency to write your first test.

There is one catch for this tutorial. Tests are run by cargo test (or rustc --test), a mode that our browser editor does not use, since it compiles your file as a normal program. So this lesson works in two ways. The real syntax and the real cargo test output appear in read-only blocks, exactly as you would see them on your machine. And every concept is also demonstrated with a runnable stand-in harness: a few lines of plain Rust that run test functions, catch panics and print a report, which shows what the real runner does under the hood.

Your first test

A test is an ordinary function with no parameters and no return value (or a Result), marked #[test]. It passes if it returns normally and fails if it panics. By convention, unit tests live at the bottom of the same file inside a module that is compiled only when testing:

Rust
// Read-only: this is the layout in a real project, run with `cargo test`.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn adds_two_numbers() {
        assert_eq!(add(2, 3), 5);
    }

    #[test]
    fn adds_negative_numbers() {
        assert_eq!(add(-4, 1), -3);
    }
}

Three details deserve attention:

  • #[cfg(test)] means "compile this module only when running tests". Your release binary does not contain test code, and the test module can even use dependencies that are listed only as dev-dependencies.
  • use super::*; brings the parent module's items into scope. Because a child module may see private items of its ancestors, tests can call private functions. That is a deliberate design choice: unit tests check internals, integration tests check the public API.
  • Each #[test] function runs in its own thread, in parallel with the others by default, and a panic fails only that test.

You can leave the same code in the editor. Here it is, with a main so the program is runnable. Notice what is missing from the output:

Rust Test code is invisible in a normal build

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.

The failing test above does not break the build, because without the test configuration the whole tests module is removed before type checking. That is why #[cfg(test)] code can be large and can use extra helpers without bloating your program.

Running the real thing prints this (read-only output from cargo test):

TEXT
running 2 tests
test tests::adds_negative_numbers ... ok
test tests::adds_two_numbers ... ok

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

The assertion macros

All checks are macros that panic with a helpful message when the condition is false:

Macro Passes when Use for
assert!(cond) cond is true Any boolean check
assert_eq!(left, right) left == right Comparing values; shows both on failure
assert_ne!(left, right) left != right Values that must differ
assert!(matches!(v, Pattern)) the value matches a pattern Enum variants, ranges
debug_assert!, debug_assert_eq! same, but only in debug builds Cheap-to-skip internal invariants

Prefer assert_eq! over assert!(a == b), because on failure it prints both values. The types must implement PartialEq and Debug, which you get with #[derive(Debug, PartialEq)]. All the macros take an optional format string for a custom message:

Rust
assert!(score <= 100, "score {score} is out of range for player {name}");

Let us see a failure with real output. We call the assertion inside a closure and catch the panic, which is the same thing the test runner does; the message is the actual text a failing assert_eq! produces.

Rust What a failed assertion reports

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.

The message layout matters when you read CI logs: left is the first argument and right the second, so the convention assert_eq!(actual, expected) makes left the actual value. (Many teams put the expected value first; pick one and keep it consistent.)

Testing for panics: #[should_panic]

Sometimes a panic is the correct behavior, such as dividing by zero or indexing out of range. Mark the test #[should_panic]; it then passes only if the function panics. Add expected = "text" so a panic for the wrong reason does not accidentally pass:

Rust
// Read-only: needs `cargo test`.
pub fn percent(part: u32, whole: u32) -> u32 {
    if whole == 0 {
        panic!("whole must not be zero");
    }
    part * 100 / whole
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[should_panic(expected = "whole must not be zero")]
    fn rejects_zero_whole() {
        percent(1, 0);
    }
}

expected is a substring match against the panic message. Use #[should_panic] sparingly. Functions that can fail in expected ways should return Result, and then the test asserts on the Err, which is more precise (see below).

Tests that return Result

A test can return Result<(), E> where E: Debug. Then the question mark operator works inside the test, and an Err fails it, printing the error. This removes a pile of unwrap() calls:

Rust
// Read-only: needs `cargo test`.
#[test]
fn parses_a_port() -> Result<(), std::num::ParseIntError> {
    let port: u16 = "8080".parse()?;
    assert_eq!(port, 8080);
    Ok(())
}

Do not use #[should_panic] on a Result-returning test. To check that something returns an error, assert on the value instead: assert!("abc".parse::<u16>().is_err()); or assert_eq!(parse("x"), Err(ParseError::Empty)).

A runnable test harness

Here is the stand-in promised earlier. It collects test functions, runs each one inside catch_unwind, and prints a report in the style of cargo test. It supports plain tests, tests that must panic and tests that return Result. Two of its tests fail on purpose so you can see a failure report: one has a wrong expected value, and one returns an Err.

Rust A tiny test runner

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.

The real runner does the same things with more polish: it discovers #[test] functions automatically, runs them in parallel threads, captures their printed output (only shown for failures), supports filters and #[ignore], and returns a non-zero exit code if anything failed so CI notices.

Look at the failure messages in the harness output. The failing divide(-7, 2) test shows left: Ok(-3) and right: Ok(-4), which tells you immediately that integer division truncates toward zero. Good tests produce failure messages that explain themselves.

Running tests with cargo

The commands you will use daily (read-only; they need a real project):

Terminal
cargo test                     # run everything: unit, integration and doc tests
cargo test parse               # only tests whose name contains "parse"
cargo test tests::adds_two     # filter by module path
cargo test -- --nocapture      # show println! output of passing tests too
cargo test -- --test-threads=1 # run tests one at a time
cargo test -- --ignored        # run the tests marked #[ignore]
cargo test --lib               # only the library's unit tests
cargo test --test api          # only the integration test file tests/api.rs

A failing run looks like this (read-only output):

TEXT
running 2 tests
test tests::good ... ok
test tests::bad ... FAILED

failures:

---- tests::bad stdout ----

thread 'tests::bad' panicked at src/lib.rs:15:9:
assertion `left == right` failed
  left: 4
 right: 5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::bad

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

error: test failed, to rerun pass `--lib`

Output printed by tests with println! is captured and shown only for failures, which keeps the log readable. Use --nocapture when you want to see it.

Tests run in parallel, so they must not depend on each other or on shared mutable state such as one fixed file name or a global counter. If two tests must not run simultaneously, give each its own temp file, or serialize access with a Mutex.

Unit tests versus integration tests

Rust distinguishes two kinds by where the test lives.

Unit tests sit in the same file as the code, inside #[cfg(test)] mod tests. They can reach private items. Keep them small and focused on one function or type.

Integration tests are separate files in the tests/ directory next to src/. Each file is compiled as its own crate and sees your library only through its public API, just as a user would. They are ideal for checking that the public pieces work together.

TEXT
my_project/
  Cargo.toml
  src/
    lib.rs          <- code + #[cfg(test)] unit tests
  tests/
    api.rs          <- integration test, one crate
    common/
      mod.rs        <- shared helpers (not run as a test file)
Rust
// tests/api.rs (read-only: integration test using the public API)
use my_project::add; // note: imported like any external crate

#[test]
fn public_api_works() {
    assert_eq!(add(1, 1), 2);
}

Facts to remember:

  • Integration tests need a library crate (src/lib.rs). A binary-only crate (src/main.rs) cannot be imported. The usual fix is to put the logic in lib.rs and keep main.rs thin.
  • Put shared helpers in tests/common/mod.rs (a subdirectory), not tests/common.rs, or Cargo treats the helper file as a test file of its own.
  • Doc tests are a third kind: code examples in /// comments are compiled and run by cargo test too. They are covered in Test patterns.

Organizing tests well

A few habits that keep a test suite useful rather than a burden:

  1. One behavior per test, with a name that reads like a sentence: rejects_empty_names, not test1. When it fails, the name is half the diagnosis.
  2. Arrange, act, assert. Set up the data, call the function, then check the result. A test with three screens of setup is a hint that the code under test does too much.
  3. Test the edges. Empty input, one element, the maximum and minimum values, and the boundary between valid and invalid (0, 1, 255, 256).
  4. Test errors as carefully as successes. The error path is where bugs hide.
  5. Never test with the real network, clock or random numbers. Pass them in (a function parameter or a trait) so tests are deterministic. The next lesson shows how.
  6. Keep tests fast. A suite that takes minutes does not get run.
  7. #[ignore] slow tests (with a reason: #[ignore = "needs a database"]) and run them on demand or in a nightly CI job.
  8. Do not test private implementation details too eagerly. Tests that mirror the code line by line break on every refactor.

When a bug is reported, write the failing test first, watch it fail for the right reason, then fix the code. The test stays forever and prevents the same bug from returning. This is the cheapest high-value habit in testing.

Common mistakes

  • Using assert!(a == b) and losing the values in the failure message; use assert_eq!.
  • Forgetting #[cfg(test)] on the module, which compiles test helpers into the release build.
  • A #[should_panic] without expected, passing because of an unrelated panic.
  • Tests that share a file or global state and fail only when run in parallel.
  • Comparing floating-point numbers with assert_eq!. Compare with a tolerance: assert!((got - want).abs() < 1e-9).
  • Expecting println! output in a passing test to appear without --nocapture.
  • Putting the real logic in main.rs, then discovering integration tests cannot import it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. When does a function marked #[test] count as passing?

    A test fails by panicking or returning Err. Returning normally is a pass; the runner does not look at printed output.
  2. 2. What does #[cfg(test)] on a module do?

    The module is removed from normal builds, so tests and test helpers do not bloat the program.
  3. 3. Why prefer assert_eq!(a, b) over assert!(a == b)?

    assert_eq! shows left and right in the failure message. It requires PartialEq and Debug.
  4. 4. Where do integration tests live, and what can they access?

    Each file in tests/ is compiled as a separate crate that uses your library like an external user, so only public items are visible.
  5. 5. Why add expected = "..." to #[should_panic]?

    Without expected, any panic satisfies the test, including one caused by an unrelated bug.

Summary

  • A test is a #[test] function that passes by returning normally and fails by panicking (or returning Err).
  • Put unit tests in #[cfg(test)] mod tests beside the code; they can see private items. Put integration tests in tests/; they see only the public API.
  • Use assert!, assert_eq!, assert_ne! and matches!; add messages that explain what was expected.
  • #[should_panic(expected = "...")] tests for panics; Result-returning tests allow ?.
  • cargo test runs tests in parallel, captures output, and supports filters, --nocapture and #[ignore].
  • Our editor does not run cargo test, so we used a small catch_unwind harness to show how test running works.
  • Name tests as sentences, test edges and errors, keep tests independent and deterministic.

Next: Test Patterns: Fixtures, Doc Tests and Property Tests