150

I have a Rust function that panics under some condition and I wish to write a test case to validate whether the function is panicking or not. I couldn't find anything except the assert! and assert_eq! macros. Is there some mechanism for testing this?

I could spawn a new task and checking whether that task panics or not. Does it make sense?


Returning a Result<T, E> is not suitable in my case.

I wish to add support for the Add trait to a Matrix type I am implementing. The ideal syntax for such addition would look like:

let m = m1 + m2 + m3;

where m1, m2, m3 are all matrices. Hence, the result type of add should be Matrix. Something like the following would be too cryptic:

let m = ((m1 + m2).unwrap() + m3).unwrap()

At the same time, the add() function needs to validate that the two matrices being added have same dimension. Thus, add() needs to panic if the dimensions don't match. The available option is panic!().

0

8 Answers 8

218

You can find the answer in testing section of the Rust book. More specifically, you want #[should_panic] attribute:

#[test]
#[should_panic]
fn test_invalid_matrices_multiplication() {
    let m1 = Matrix::new(3, 4);  // assume these are dimensions
    let m2 = Matrix::new(5, 6);
    m1 * m2
}
3
  • 79
    It's worth mentioning that you can add a check for the panic's text: #[should_panic(expected = "assertion failed")]
    – phss
    May 20, 2017 at 18:03
  • 8
    A quick note here that depending on your IDE and environment the stack trace from the panic may still appear in the output, but the test will still pass. It took me a minute to realize that my #[should_panic] was actually working. When you run a generic cargo test from the command line you'll notice that it swallows the panic and just shows as ok.
    – ragona
    Nov 22, 2019 at 21:35
  • 8
    I would strengthen that "can" to "really should". Code can panic in many ways. If you don't specify an expected text, the test could end up passing for the wrong reason. Dec 9, 2021 at 12:58
86

As Francis Gagné mentioned in his answer, I also find the #[should_panic] attribute (as suggested by the accepted answer) is not fine-grained enough. For example, if my test setup fails for some reason (i.e. I've written a bad test), I do want a panic to be considered a failure!

As of Rust 1.9.0, std::panic::catch_unwind() is available. It allows you to put the code you expect to panic into a closure, and only panics emitted by that code will be considered expected (i.e. a passing test).

#[test]
fn test_something() {
    ... //<-- Any panics here will cause test failure (good)
    let result = std::panic::catch_unwind(|| <expected_to_panic_operation_here>);
    assert!(result.is_err());  //probe further for specific error type here, if desired
}

Note it cannot catch non-unwinding panics (e.g. std::process::abort()).

29

If you want to assert that only a specific portion of the test function fails, use std::panic::catch_unwind() and check that it returns an Err, for example with is_err(). In complex test functions, this helps ensure that the test doesn't pass erroneously because of an early failure.

Several tests in the Rust standard library itself use this technique.

4
  • 7
    Should there be an assert_fails or assert_panics macro for this?
    – dhardy
    Feb 23, 2015 at 16:54
  • 3
    You can use unwrap_err too.
    – wimh
    Aug 2, 2016 at 14:15
  • Is there any way to do this in a #[no_std] environment? I'm looking to create an assert_panics! macro for general use.
    – jhpratt
    Nov 5, 2019 at 6:16
  • @jhpratt The best I've found for #[no_std] so far is to use #[should_panic(expected = "<panic message to match>")] with unreachable!() following the should-panic test condition. Test is green with expected panic, red otherwise.
    – U007D
    Oct 16, 2021 at 2:51
13

Use following catch_unwind_silent instead of regular catch_unwind to achieve silence in output for expected exceptions:

use std::panic;

fn catch_unwind_silent<F: FnOnce() -> R + panic::UnwindSafe, R>(f: F) -> std::thread::Result<R> {
    let prev_hook = panic::take_hook();
    panic::set_hook(Box::new(|_| {}));
    let result = panic::catch_unwind(f);
    panic::set_hook(prev_hook);
    result
}
5

As an addendum: The solution proposed by @U007D also works in doctests:

/// My identity function that panic for an input of 42.
///
/// ```
/// assert_eq!(my_crate::my_func(23), 23);
///
/// let result = std::panic::catch_unwind(|| my_crate::my_func(42));
/// assert!(result.is_err());
/// ```
pub fn my_func(input: u32) -> u32 {
    if input == 42 {
        panic!("Error message.");
    } else {
        input
    }
}
2

From the Documentation on Unit testing, in the Testing Panics section

pub fn divide_non_zero_result(a: u32, b: u32) -> u32 {
    if b == 0 {
        panic!("Divide-by-zero error");
    } else if a < b {
        panic!("Divide result is zero");
    }
    a / b
}

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

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

    #[test]
    #[should_panic]
    fn test_any_panic() {
        divide_non_zero_result(1, 0);
    }

    #[test]
    #[should_panic(expected = "Divide result is zero")]
    fn test_specific_panic() {
        divide_non_zero_result(1, 10);
    }
}

The output when running cargo test would be

$ cargo test

running 2 tests
test tests::test_bad_add ... FAILED
test tests::test_add ... ok

failures:

---- tests::test_bad_add stdout ----
        thread 'tests::test_bad_add' panicked at 'assertion failed: `(left == right)`
  left: `-1`,
 right: `3`', src/lib.rs:21:8
note: Run with `RUST_BACKTRACE=1` for a backtrace.


failures:
    tests::test_bad_add

test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out
1

The main issues with the accepted answer with using #[should_panic] attributes are:

  • unrelated panics might cause a test to pass
  • it does not suppress the printing of the panic message to the console, resulting in unclean test execution log
  • it is not possible to add additional checks after the panic has happened

As a better alternative, I would highly recommend checking out the library called fluent-asserter

By using it, you can easily write an assertion that checks if a panic has occurred, as follows:

#[test]
fn assert_that_code_panics() {
    let panicking_action = || panic!("some panic message");

    assert_that_code!(panicking_action)
        .panics()
        .with_message("some panic message");
}

The good thing with this is that:

  • it uses a fluent interface, resulting in a readable assertion
  • it suppresses the printing of the panic message to the console, resulting in a clean test execution log
  • you can add additional assertions after the panic check
0

When using rust crate test_case, use the panics idiom.

extern crate test_case;
use test_case::test_case;

#[test_case(0 => panics)]
#[test_case(1)]
fn test_divisor(divisor: usize) {
    let _result = 1 / divisor;
}

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.