Unit testing

Tests are Rust functions that verify that the non-test code is functioning in
the expected manner. The bodies of test functions typically perform some setup,
run the code we want to test, then assert whether the results are what we
expect.

Most unit tests go into a tests mod with the #[cfg(test)] attribute.
Test functions are marked with the #[test] attribute.

Tests fail when something in the test function panics. There are some
helper macros:

  • assert!(expression) - panics if expression evaluates to false.
  • assert_eq!(left, right) and assert_ne!(left, right) - testing left and
    right expressions for equality and inequality respectively.
  1. pub fn add(a: i32, b: i32) -> i32 {
  2.     a + b
  3. }
  5. // This is a really bad adding function, its purpose is to fail in this
  6. // example.
  7. #[allow(dead_code)]
  8. fn bad_add(a: i32, b: i32) -> i32 {
  9.     a - b
  10. }
  12. #[cfg(test)]
  13. mod tests {
  14.     // Note this useful idiom: importing names from outer (for mod tests) scope.
  15.     use super::*;
  17.     #[test]
  18.     fn test_add() {
  19.         assert_eq!(add(1, 2), 3);
  20.     }
  22.     #[test]
  23.     fn test_bad_add() {
  24.         // This assert would fire and test will fail.
  25.         // Please note, that private functions can be tested too!
  26.         assert_eq!(bad_add(1, 2), 3);
  27.     }
  28. }

Tests can be run with cargo test.

  1. $ cargo test
  3. running 2 tests
  4. test tests::test_bad_add ... FAILED
  5. test tests::test_add ... ok
  7. failures:
  9. ---- tests::test_bad_add stdout ----
  10.         thread 'tests::test_bad_add' panicked at 'assertion failed: `(left == right)`
  11.   left: `-1`,
  12.  right: `3`', src/lib.rs:21:8
  13. note: Run with `RUST_BACKTRACE=1` for a backtrace.
  16. failures:
  17.     tests::test_bad_add
  19. test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

Testing panics

To check functions that should panic under certain circumstances, use attribute
#[should_panic]. This attribute accepts optional parameter expected = with
the text of the panic message. If your function can panic in multiple ways, it helps
make sure your test is testing the correct panic.

  1. pub fn divide_non_zero_result(a: u32, b: u32) -> u32 {
  2.     if b == 0 {
  3.         panic!("Divide-by-zero error");
  4.     } else if a < b {
  5.         panic!("Divide result is zero");
  6.     }
  7.     a / b
  8. }
  10. #[cfg(test)]
  11. mod tests {
  12.     use super::*;
  14.     #[test]
  15.     fn test_divide() {
  16.         assert_eq!(divide_non_zero_result(10, 2), 5);
  17.     }
  19.     #[test]
  20.     #[should_panic]
  21.     fn test_any_panic() {
  22.         divide_non_zero_result(1, 0);
  23.     }
  25.     #[test]
  26.     #[should_panic(expected = "Divide result is zero")]
  27.     fn test_specific_panic() {
  28.         divide_non_zero_result(1, 10);
  29.     }
  30. }

Running these tests gives us:

  1. $ cargo test
  3. running 3 tests
  4. test tests::test_any_panic ... ok
  5. test tests::test_divide ... ok
  6. test tests::test_specific_panic ... ok
  8. test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  10.    Doc-tests tmp-test-should-panic
  12. running 0 tests
  14. test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Running specific tests

To run specific tests one may specify the test name to cargo test command.

  1. $ cargo test test_any_panic
  2. running 1 test
  3. test tests::test_any_panic ... ok
  5. test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out
  7.    Doc-tests tmp-test-should-panic
  9. running 0 tests
  11. test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

To run multiple tests one may specify part of a test name that matches all the
tests that should be run.

  1. $ cargo test panic
  2. running 2 tests
  3. test tests::test_any_panic ... ok
  4. test tests::test_specific_panic ... ok
  6. test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out
  8.    Doc-tests tmp-test-should-panic
  10. running 0 tests
  12. test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Ignoring tests

Tests can be marked with the#[ignore] attribute to exclude some tests. Or to run
them with command cargo test -- --ignored

  1. pub fn add(a: i32, b: i32) -> i32 {
  2.     a + b
  3. }
  5. #[cfg(test)]
  6. mod tests {
  7.     use super::*;
  9.     #[test]
  10.     fn test_add() {
  11.         assert_eq!(add(2, 2), 4);
  12.     }
  14.     #[test]
  15.     fn test_add_hundred() {
  16.         assert_eq!(add(100, 2), 102);
  17.         assert_eq!(add(2, 100), 102);
  18.     }
  20.     #[test]
  21.     #[ignore]
  22.     fn ignored_test() {
  23.         assert_eq!(add(0, 0), 0);
  24.     }
  25. }
  1. $ cargo test
  2. running 1 test
  3. test tests::ignored_test ... ignored
  5. test result: ok. 0 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out
  7.    Doc-tests tmp-ignore
  9. running 0 tests
  11. test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  13. $ cargo test -- --ignored
  14. running 1 test
  15. test tests::ignored_test ... ok
  17. test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  19.    Doc-tests tmp-ignore
  21. running 0 tests
  23. test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out