Unit tests

Why test?

The compiler catches type and memory mistakes, but not logic mistakes: a GST rate of 1.8 instead of 18, or a discount applied twice. A test is code that runs your code with known inputs and checks the outputs. Once written, tests run in seconds every time you change something, so you notice breakage immediately instead of hearing about it from a customer.

Your first test

pub fn gst(amount: u32, rate: u32) -> u32 {
    amount * rate / 100
}

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

    #[test]
    fn gst_at_18_percent() {
        assert_eq!(gst(1000, 18), 180);
    }

    #[test]
    fn gst_on_zero_is_zero() {
        assert_eq!(gst(0, 18), 0);
    }
}

• #[cfg(test)] means "compile this module only when running tests", so tests do not make your real program bigger.
• use super::*; brings everything from the parent module (the code under test) into the tests module.
• #[test] marks a function as a test. It takes no arguments.
• assert_eq!(left, right) fails the test if the two values differ, and prints both.

cargo test
cargo test gst              # only tests whose name contains "gst"
cargo test -- --nocapture   # show println! output from passing tests

running 2 tests
test tests::gst_at_18_percent ... ok
test tests::gst_on_zero_is_zero ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

The assert macros

assert_eq! needs the values to implement PartialEq (to compare) and Debug (to print them on failure). Derive both on your own types.

Testing failures

pub fn divide_bill(total: u32, people: u32) -> u32 {
    if people == 0 {
        panic!("people must be at least 1");
    }
    total / people
}

#[test]
#[should_panic(expected = "at least 1")]
fn zero_people_panics() {
    divide_bill(900, 0);
}

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

Good test habits

• Name tests after the behaviour: refund_is_zero_after_30_days, not test1.
• Test the edges: zero, one, the maximum, empty strings, Hindi text, negative cases.
• One idea per test, so a failure tells you exactly what broke.
• Use #[ignore] for very slow tests and run them with cargo test -- --ignored.
• Private functions can be tested too, because the tests module is a child of the module.

Common mistakes

• Forgetting use super::*; and getting "cannot find function in this scope".
• Comparing floats with assert_eq!: 0.1 + 0.2 is not exactly 0.3. Check that the difference is tiny instead.
• Tests that depend on each other or on run order. Tests run in parallel; each must set up its own data.
• Not running tests before pushing. Make cargo test part of your routine (and of CI, next topics).