Rust Testing Explained: cargo test, assert_eq!, assert! and should_panic

Welcome to episode 21 of Rust for Beginners, a series for complete beginners (no programming experience needed). In the last video, we learned about closures and iterators. Today, we'll learn how to test our code, so we know it works, and keeps working. Every code block below is the exact code from the video, ready to copy.

• All episodes are in the Rust Tutorial for Beginners playlist.
• Versions used: Rust 1.99.1 on Ubuntu, VS Code with rust-analyzer.

1. Library

This time, we create a library instead of a program, with dash dash lib. A library has no main function. It's code for other programs to use.

cargo new calculator --lib
cd calculator

2. Template

Cargo already wrote a test for us. Let's look at it.

3. Test module

Tests live in a module called tests. The cfg test line means: only compile this when testing. And use super star brings in everything from the file above.

4. #[test]

A test is a normal function marked with hash test. assert eq checks that two values are equal.

5. cargo test

Let's run it with cargo test. One test, passed.

cargo test

6. Our code

Now our own code: add, and is even.

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

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

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

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

    #[test]
    fn checks_even_numbers() {
        assert!(is_even(4));
        assert!(!is_even(7));
    }
}

Output: test tests::adds_two_numbers ... ok / test tests::checks_even_numbers ... ok / 2 passed

Then line 2 becomes a - b. Output:

running 2 tests
test tests::adds_two_numbers ... FAILED
test tests::checks_even_numbers ... ok

failures:

---- tests::adds_two_numbers stdout ----

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

failures:
    tests::adds_two_numbers

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`

7. Our tests

One test checks that two plus three is five. The other uses assert, which checks that something is true. The exclamation mark means not: seven is not even.

8. Run B

Let's run them. Both pass.

cargo test

9. Bug

But what if someone breaks the code later? Let's change plus to minus, by mistake.

10. Fail

cargo test catches it right away. The test failed: left is minus one, but right should be five.

cargo test

11. Fix

Let's fix it, and everything passes again. That's why tests are worth writing.

cargo test

12. should_panic

We can also test that code panics when it should. divide panics on zero, and should panic with expected checks the message.

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

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

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

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

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

    #[test]
    fn checks_even_numbers() {
        assert!(is_even(4));
        assert!(!is_even(7));
    }

    #[test]
    fn divides() {
        assert_eq!(divide(10, 2), 5);
    }

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

Output (order of the first lines may vary):

running 4 tests
test tests::adds_two_numbers ... ok
test tests::divides ... ok
test tests::checks_even_numbers ... ok
test tests::divide_by_zero_panics - should panic ... ok

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

13. Run C

Let's run it. Four tests, all passed, including the one that panics.

cargo test

Recap

To recap: tests go in a tests module, each marked with hash test. assert eq compares, assert checks for true, should panic expects a panic. And cargo test runs them all.