Testing in Rust

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

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

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

#[test]
fn assertions() {
    let x = 5;
    assert!(x > 0);                 // true condition
    assert_eq!(x, 5);               // equality: prints both values on failure
    assert_ne!(x, 0);               // difference
}

assert_eq! and assert_ne! require the values to implement PartialEq and Debug.

#[test]
fn with_message() {
    let age = 17;
    assert!(age >= 18, "age refused: {age}, at least 18 required");
    assert_eq!(age, 18, "the age read from the form is {age}");
}

The message is printed in addition to the compared values. It says what the test was checking, especially in a loop.

assert!(result == 42);         // failure: "assertion failed: result == 42"
assert_eq!(result, 42);        // failure: "left: 41, right: 42"

The second form shows the value you got, which saves rerunning the test with println!.

#[derive(Debug)]
enum Error { NotFound, Forbidden(String) }

fn load(id: u32) -> Result<u32, Error> {
    if id == 0 { Err(Error::Forbidden("anonymous".into())) } else { Ok(id) }
}

#[test]
fn refuses_anonymous() {
    // Option 1: matches! — no need for PartialEq on Error
    assert!(matches!(load(0), Err(Error::Forbidden(_))));

    // Option 2: explicit match, to check the content too
    match load(0) {
        Err(Error::Forbidden(reason)) => assert_eq!(reason, "anonymous"),
        other => panic!("expected Forbidden, got {other:?}"),
    }

    // Option 3: let else
    let Err(Error::Forbidden(reason)) = load(0) else {
        panic!("expected Forbidden");
    };
    assert_eq!(reason, "anonymous");
}

#[test]
fn floats() {
    let r = 0.1 + 0.2;
    // assert_eq!(r, 0.3);                        // fails: 0.30000000000000004
    assert!((r - 0.3_f64).abs() < 1e-10, "got {r}");
}

use std::collections::HashSet;

#[test]
fn collections() {
    let mut actual = vec![3, 1, 2];
    actual.sort();
    assert_eq!(actual, [1, 2, 3]);       // Vec compared to an array: accepted

    let a: HashSet<_> = [1, 2].into();
    let b: HashSet<_> = [2, 1].into();
    assert_eq!(a, b);                    // order does not matter in a set
}

If the order of a result is not guaranteed (iterating over a HashMap), sort it or compare sets: otherwise the test will fail at random.

pub fn divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("division by zero");
    }
    a / b
}

#[test]
#[should_panic]
fn panics_on_zero() {
    divide(1, 0);
}

#[test]
#[should_panic(expected = "division by zero")]
fn panics_with_the_right_message() {
    divide(1, 0);
}

Without expected, the test passes on any panic, including an unrelated bug (an out-of-bounds index elsewhere). Always set expected: it is a substring of the panic message.

#[test]
fn caught_panic() {
    let r = std::panic::catch_unwind(|| divide(1, 0));
    assert!(r.is_err());
}

Useful to check several panics in a single test, or to keep going afterwards.

#[test]
fn reads_the_config() -> Result<(), Box<dyn std::error::Error>> {
    let n: i32 = "42".parse()?;          // ? instead of unwrap
    assert_eq!(n, 42);
    Ok(())
}

#[test]
#[ignore = "slow: needs a Postgres database"]
fn full_import() {}

cargo test                       # full_import is skipped
cargo test -- --ignored          # only the ignored ones
cargo test -- --include-ignored  # everything

#[test]
fn with_postgres() {
    let Ok(url) = std::env::var("DATABASE_URL_PG") else {
        eprintln!("DATABASE_URL_PG missing: test skipped");
        return;
    };
    // ...
}

// src/compute.rs
pub fn mean(v: &[f64]) -> Option<f64> {
    if v.is_empty() {
        return None;
    }
    Some(sum(v) / v.len() as f64)
}

fn sum(v: &[f64]) -> f64 {
    v.iter().sum()
}

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

    #[test]
    fn mean_of_nothing_is_none() {
        assert_eq!(mean(&[]), None);
    }

    #[test]
    fn private_sum() {
        assert_eq!(sum(&[1.0, 2.0]), 3.0);   // unit tests see private items
    }
}

// src/compute.rs
#[cfg(test)]
mod tests;              // content in src/compute/tests.rs

// src/compute/tests.rs
use super::*;

#[test]
fn simple_mean() {
    assert_eq!(mean(&[2.0, 4.0]), Some(3.0));
}

What it is for: keeping the code file readable when the tests get long, while keeping access to private items.

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

    fn data() -> Vec<f64> {      // no #[test]: plain helper function
        vec![1.0, 2.0, 3.0]
    }

    #[test]
    fn uses_the_helper() {
        assert_eq!(mean(&data()), Some(2.0));
    }
}

my_project/
├── src/
│   └── lib.rs
└── tests/
    ├── api.rs          ← one test binary
    ├── forms.rs        ← another test binary
    └── common/
        └── mod.rs      ← shared code (not a test)

// tests/api.rs
use my_project::Calculator;      // only the public API, like a user

#[test]
fn full_computation() {
    let mut c = Calculator::new(10.0);
    c.add(5.0);
    assert_eq!(c.result(), 15.0);
}

• Each file in tests/ is compiled as a separate crate that depends on your library.
• No need for #[cfg(test)]: the whole folder is only compiled for tests.
• They only see what is pub: they check the API as users will see it.
• A package that only has a main.rs (no lib.rs) cannot have integration tests on its logic: one more reason to put the logic in lib.rs.

// tests/common/mod.rs
pub fn initialized_calculator() -> my_project::Calculator {
    my_project::Calculator::new(100.0)
}

// tests/forms.rs
mod common;

#[test]
fn with_helper() {
    let c = common::initialized_calculator();
    assert_eq!(c.result(), 100.0);
}

Why common/mod.rs and not common.rs: a tests/common.rs file would be taken for a test binary (shown as "running 0 tests"). A subfolder is not treated as a test.

tests/
├── main.rs        ← mod api; mod forms; mod common;
├── api.rs
└── forms.rs

Each file in tests/ is linked separately: with many files, compilation and linking take time. Grouping them into one binary (a main.rs that declares the others as modules) speeds up large projects noticeably.

/// Adds two numbers.
///
/// # Examples
///
/// ```
/// let r = my_project::add(2, 3);
/// assert_eq!(r, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

cargo test compiles and runs every code block in the documentation. What it is for: the documentation cannot become wrong without the tests failing.

fn basket_with_two_items() -> Vec<(String, u32)> {
    vec![("apple".into(), 2), ("pear".into(), 1)]
}

#[test]
fn total() {
    let p = basket_with_two_items();
    assert_eq!(p.iter().map(|(_, n)| n).sum::<u32>(), 3);
}

struct TempFolder(std::path::PathBuf);

impl TempFolder {
    fn new(name: &str) -> Self {
        let p = std::env::temp_dir().join(name);
        std::fs::create_dir_all(&p).unwrap();
        Self(p)
    }
}

impl Drop for TempFolder {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.0);   // runs even if the test panics
    }
}

#[test]
fn writes_a_file() {
    let folder = TempFolder::new("test_writing");
    std::fs::write(folder.0.join("a.txt"), "x").unwrap();
    assert!(folder.0.join("a.txt").exists());
}   // folder removed here

Drop also runs when the test fails: cleanup is guaranteed, unlike a call at the end of the function that a panic would skip. The tempfile crate provides this type ready-made.

use std::sync::LazyLock;

static DATA: LazyLock<Vec<u32>> = LazyLock::new(|| {
    (0..1_000_000).collect()     // computed once for all tests
});

#[test]
fn uses_the_data() {
    assert_eq!(DATA.len(), 1_000_000);
}

Keep it for read-only data: tests run in parallel and must not modify each other.

fn is_even(n: i32) -> bool { n % 2 == 0 }

#[test]
fn is_even_multiple_cases() {
    let cases = [(0, true), (1, false), (2, true), (-3, false), (i32::MAX, false)];
    for (input, expected) in cases {
        assert_eq!(is_even(input), expected, "is_even({input})");
    }
}

Simple, but the test stops at the first failure and only shows up as one test.

macro_rules! even_cases {
    ($($name:ident: $input:expr => $expected:expr,)*) => {
        $(
            #[test]
            fn $name() {
                assert_eq!(is_even($input), $expected);
            }
        )*
    };
}

even_cases! {
    zero: 0 => true,
    one: 1 => false,
    negative_odd: -3 => false,
    max: i32::MAX => false,
}

Each case is a separate test, with its name in the report. The rstest and test-case crates offer the same thing with an attribute (#[case(0, true)]).

async fn fetch(id: u32) -> Option<String> {
    tokio::time::sleep(std::time::Duration::from_millis(1)).await;
    (id > 0).then(|| format!("item {id}"))
}

#[tokio::test]
async fn fetches_an_item() {
    assert_eq!(fetch(1).await, Some("item 1".into()));
}

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn with_several_threads() {}

#[test] cannot run an async function: #[tokio::test] creates a runtime for the test. By default, it is single-threaded.

#[tokio::test(start_paused = true)]
async fn expiration() {
    let start = tokio::time::Instant::now();
    tokio::time::sleep(std::time::Duration::from_secs(3600)).await;   // instant
    assert!(start.elapsed() >= std::time::Duration::from_secs(3600));
}

With start_paused (tokio's test-util feature), time advances on its own when all tasks are waiting: a one-hour expiration test takes a few microseconds.

// Hard to test: the time is read inside
fn is_expired_v1(expires_at: u64) -> bool {
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH).unwrap().as_secs();
    now > expires_at
}

// Easy to test: the time is a parameter
fn is_expired(expires_at: u64, now: u64) -> bool {
    now > expires_at
}

#[test]
fn expiration_boundary() {
    assert!(!is_expired(100, 100));
    assert!(is_expired(100, 101));
}

trait Sender {
    fn send(&self, to: &str, text: &str) -> Result<(), String>;
}

struct Signup<S: Sender> { mail: S }

impl<S: Sender> Signup<S> {
    fn register(&self, email: &str) -> Result<(), String> {
        self.mail.send(email, "Welcome")
    }
}

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

    struct FakeSender { sent: RefCell<Vec<String>> }

    impl Sender for FakeSender {
        fn send(&self, to: &str, _text: &str) -> Result<(), String> {
            self.sent.borrow_mut().push(to.to_string());
            Ok(())
        }
    }

    #[test]
    fn sends_the_welcome_mail() {
        let s = Signup { mail: FakeSender { sent: RefCell::new(vec![]) } };
        s.register("[email protected]").unwrap();
        assert_eq!(*s.mail.sent.borrow(), ["[email protected]"]);
    }
}

Production code uses a real SMTP sender; the test uses a fake one that records the calls. The mockall crate generates such fakes automatically.

#[cfg(test)]
mod tests {
    #[test]
    #[cfg(feature = "admin")]          // compiled only with the feature
    fn admin_available() {}

    #[test]
    #[cfg(not(feature = "admin"))]
    fn admin_absent() {}
}

cargo test --features admin
cargo test --no-default-features

cargo test                          # all tests: unit, integration, doc
cargo test mean                     # tests whose path contains "mean"
cargo test compute::tests::         # one module
cargo test mean -- --exact          # exact name (full path)

cargo test --lib                    # only the library's unit tests
cargo test --test api               # only tests/api.rs
cargo test --doc                    # only the documentation examples
cargo test --bins                   # only the binaries' tests

cargo test -- --nocapture           # show println! output (hidden when the test passes)
cargo test -- --test-threads=1      # one test at a time
cargo test -- --ignored             # only the #[ignore] ones
cargo test -- --include-ignored
cargo test -- --list                # list without running
cargo test --no-fail-fast           # keep going after the first failing file

cargo test -p runique               # one workspace member
cargo test --features admin,test-utils test_name
cargo test --release                # tests with optimizations (integer overflows not detected)

cargo install cargo-llvm-cov
cargo llvm-cov --html             # line-by-line report
cargo llvm-cov --features admin

Coverage tells you which lines were executed, not whether they were checked: a test with no assertion covers code without proving anything.

cargo install cargo-mutants
cargo mutants                     # changes the code (>= becomes >, true becomes false...) and reruns the tests
cargo mutants -f src/auth.rs      # a single file

Each mutation that survives (the tests still pass) points to a line whose behavior no test checks. It is the best way to find forgotten boundaries (section 10.3).

// with the proptest crate
proptest::proptest! {
    #[test]
    fn reversing_twice_gives_the_original(v: Vec<i32>) {
        let mut w = v.clone();
        w.reverse();
        w.reverse();
        proptest::prop_assert_eq!(v, w);
    }
}

Instead of writing cases by hand, you write a property that is true for all inputs; the crate generates hundreds of inputs and shrinks any counterexample to the smallest one.

#[test] fn test1() {}                                    // vague
#[test] fn dividing_by_zero_returns_an_error() {}        // says what is guaranteed

#[test]
fn adding_to_the_basket() {
    // Arrange
    let mut basket = Vec::new();
    // Act
    basket.push(("apple", 2));
    // Assert
    assert_eq!(basket.len(), 1);
}

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

    #[test] fn a() { assert!(c); assert_eq!(x, y); assert_ne!(x, z); }
    #[test] fn b() -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
    #[test] #[should_panic(expected = "message")] fn c() {}
    #[test] #[ignore = "reason"] fn d() {}
    #[tokio::test] async fn e() {}
}

assert!(matches!(r, Err(Error::X)));
assert_eq!(f().unwrap_err(), "message");

cargo test filter                 cargo test -- --nocapture
cargo test --lib / --test name / --doc
cargo test -- --test-threads=1    cargo test -- --ignored
cargo test --features a,b         cargo llvm-cov    cargo mutants