How do I write a Rust unit test that ensures that a panic has occurred?

Question

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!().

Answer 1

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
}

Answer 2

As Francis Gagné mentioned in his answer, I also find the #[should_panic] attribute to not be fine-grained enough for more complex tests--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()).

Answer 3

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.

Answer 4

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
}

Answer 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
    }
}

Answer 6

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