Rust Testing

#[cfg(test)] means the module below is compiled only while testing. Unit tests sit next to the code, so they can see private items too.

#[cfg(test)]
mod tests {
    use super::*;
    // tests go here
}

The test passes if it finishes. It fails if it panics — and an assert that fails panics. Every test follows three steps: set up the data, run the code, then check the result.

#[test]
fn it_adds() {
    assert!(add(2, 3) > 4);
    assert_eq!(add(2, 3), 5);
}

Some code should fail. #[should_panic] passes only when the code inside panics:

#[test]
#[should_panic]
fn third_score_missing() {
    let scores = vec![10, 20];
    let _third = scores[5]; // panics: there is no third score
}

#[ignore] leaves a test out of normal runs, until you ask for it by name or with --ignored:

#[test]
#[ignore]
fn huge_file_search() {
    // slow test, skipped for now
}

A word after cargo test is a filter: only tests whose names contain it will run. The Running Tests lesson shows the full control panel.

cargo test it_adds

A file in the tests/ folder is its own crate. It imports your library. It uses only the public API, exactly like a real user. Shared helper code goes in tests/common/mod.rs, where it is not mistaken for a test file. Only library crates can be tested this way, so keep main.rs thin and the real logic in lib.rs.

// tests/add_from_outside.rs
use my_library::add;

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

Return Ok(()) to pass. Return an Err and the test fails, with that error as its report:

#[test]
fn parses_a_number() -> Result<(), String> {
    let n = parse_number("42")?;
    assert_eq!(n, 42);
    Ok(())
}

Use ? inside such a test: the first Err stops the test and fails it, so the happy path stays short:

#[test]
fn parses_and_adds() -> Result<(), std::num::ParseIntError> {
    let n: i32 = "42".parse()?;
    assert_eq!(n + 1, 43);
    Ok(())
}

Check a success before you rely on its value, and an expected failure by asking the Result directly. Never use ? to check an expected error — ? would turn that error into a failure of the test itself:

#[test]
fn rejects_words() {
    assert!(parse_number("abc").is_err());
    assert!(parse_number("42").is_ok());
}

In this example, parse_number turns text into a number, or fails with a message. The first test returns Result<(), String>. So it can put ? after parse_number("42"). If parsing failed, the test would stop and fail with that error. Instead it gets 42. assert_eq! confirms it. And Ok(()) ends the test as a pass. The second test checks the failure path on purpose: parse_number("abc") must be an Err, and is_err() says so. main parses the same good input and prints parsed = 42.

fn parse_number(text: &str) -> Result<i32, String> { text.trim().parse().map_err(|_| format!("not a number: {text}")) }
#[cfg(test)]
mod tests {
    use super::*;
    #[test] fn parses_a_number() -> Result<(), String> { assert_eq!(parse_number("42")?, 42); Ok(()) }
    #[test] fn rejects_words() { assert!(parse_number("abc").is_err()); }
}
fn main() { match parse_number("42") { Ok(n) => println!("parsed = {n}"), Err(e) => println!("error: {e}"), } }

fn add(a: i32, b: i32) -> i32 { a + b }
#[cfg(test)]
mod tests {
    use super::*;
    #[test] fn it_adds() { assert_eq!(add(2, 3), 5); }
    #[test] fn negatives() { assert_eq!(add(-1, 1), 0); }
}
fn main() { println!("add(2,3) = {} — run cargo test for 2 passing tests", add(2, 3)); }