Macro cool_asserts::assert_panics

macro_rules! assert_panics {
    ($expression:expr, |$panic:ident: Box<$(dyn)? Any $(+ Send)? $(+ 'static)?>| $body:expr) => { ... };
    ($expression:expr, |$msg:ident $(: &str)?| $body:expr) => { ... };
    ($expression:expr, |$value:ident: &$type:ty| $body:expr) => { ... };
    ($expression:expr $(,)?) => { ... };
    ($expression:expr $(, $rule:ident($arg:expr))+ $(,)?) => { ... };
}

Assert that an expression panics.

This macro asserts that a given expression panics. If the expression doesn't panic, this macro will panic, with a description including the expression itself, as well as the return value of the expression.

This macro is intended to replace #[should_panic] in rust tests:

• It allows for checking that a particular expression or statement panics, rather than an entire test function.
• It allows checking for the presence or absence of multiple substrings. should_panic can only test for a single substring (with expected), and can't test for absence at all.

Examples

use cool_asserts::assert_panics;

assert_panics!({
    let _x = 1 + 2;
    panic!("Panic Message");
});

use cool_asserts::assert_panics;

assert_panics!(1 + 2);

Substring checking

Optionally, provide a list of conditions of the form includes(pattern) or excludes(pattern). If given, the assertion will check that the panic message contains or does not contain each of the given patterns. It uses str::contains, which means that anything implementing Pattern can be used as a matcher.

Examples

use cool_asserts::assert_panics;

assert_panics!(
    panic!("Custom message: {}", "message"),
    includes("message: message"),
    includes("Custom"),
    excludes("Foo"),
);

// THIS EXAMPLE PANICS

use cool_asserts::assert_panics;

// The expression panics, which passes the assertion, but it fails
// the message test, which means the overall assertion fails.
assert_panics!(
    panic!("Message"),
    excludes("Message")
);

Generic message testing

If the includes(..) and excludes(..) are not powerful enough, assert_panics can also accept a closure as an argument. If the expression panics, the closure is called with the panic message as an &str. This closure can contain any additional assertions you wish to perform on the panic message.

Examples

use cool_asserts::assert_panics;

assert_panics!(panic!("{}, {}!", "Hello", "World"), |msg| {
    assert_eq!(msg, "Hello, World!")
});

use cool_asserts::assert_panics;

assert_panics!(
    assert_panics!(
        panic!("Message"),
        |msg| panic!("Custom Message")
    ),
    includes("Custom Message"),
    excludes("assertion failed")
)

Generic panic values

If you need to test panics that aren't event messages– that is, that aren't String or &str values provided by most panics (including most assertions)– you can provide a reference type in the closure. The macro will attermpt to cast the panic value to that type. It will fail the assertion if the type doesn't match; otherwise the closure will be called.

use cool_asserts::assert_panics;

assert_panics!(panic!(10i64), |value: &i64| {
    assert_eq!(value, &10);
})

use cool_asserts::assert_panics;

assert_panics!(
    assert_panics!(
        panic!(10i64),
        |value: &i32| {
            panic!("CUSTOM PANIC");
        }
    ),
    includes("expression panic type mismatch"),
    includes("i32"),
    // Currently, type_name of Any returns &dyn Any, rather than the actual type
    // includes("i64"),
    excludes("expression didn't panic"),
    excludes("CUSTOM PANIC")
);