feat: Add functions assert_panic and assert_panic_contains

Author: skogseth

crates/libtest2/src/lib.rs

@@ -50,6 +50,7 @@
 
 mod case;
 mod macros;
+mod panic;
 
 #[doc(hidden)]
 pub mod _private {
@@ -73,6 +74,7 @@ pub use libtest2_harness::RunResult;
 pub use libtest2_harness::TestContext;
 pub use libtest2_proc_macro::main;
 pub use libtest2_proc_macro::test;
+pub use panic::{assert_panic, assert_panic_contains};
 
 #[doc = include_str!("../README.md")]
 #[cfg(doctest)]

crates/libtest2/src/panic.rs

@@ -0,0 +1,136 @@
+//! This module contains functions related to handling panics
+
+use libtest2_harness::{RunError, RunResult};
+
+// TODO: Rust includes the source file location in this error, consider doing the same?
+const DID_NOT_PANIC: &str = "test did not panic as expected";
+
+/// Assert that a piece of code is intended to panic
+///
+/// This will wrap the provided closure and check the result for a panic. If the function fails to panic
+/// an error value is returned, otherwise `Ok(())` is returned.
+///
+/// ```rust
+/// fn panicky_test() {
+///     panic!("intentionally fails");
+/// }
+///
+/// let result = libtest2::assert_panic(panicky_test);
+/// assert!(result.is_ok());
+/// ```
+///
+/// If you also want to check that the panic contains a specific message see [`assert_panic_contains`].
+///
+/// # Notes
+/// This function will wrap the provided closure with a call to [`catch_unwind`](`std::panic::catch_unwind`),
+/// and will therefore inherit the caveats of this function, most notably that it will be unable to catch
+/// panics if they are not implemented via unwinding.
+pub fn assert_panic<T, F: FnOnce() -> T>(f: F) -> RunResult {
+    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)) {
+        // The test should have panicked, but didn't.
+        Ok(_) => Err(RunError::fail(DID_NOT_PANIC)),
+
+        // The test panicked, as expected.
+        Err(_) => Ok(()),
+    }
+}
+
+/// Assert that a piece of code is intended to panic with a specific message
+///
+/// This will wrap the provided closure and check the result for a panic. If the function fails to panic with
+/// a message that contains the expected string an error value is returned, otherwise `Ok(())` is returned.
+///
+/// ```rust
+/// fn panicky_test() {
+///     panic!("intentionally fails");
+/// }
+///
+/// let result = libtest2::assert_panic_contains(panicky_test, "fail");
+/// assert!(result.is_ok());
+///
+/// let result = libtest2::assert_panic_contains(panicky_test, "can't find this");
+/// assert!(result.is_err());
+/// ```
+///
+/// If you don't want to check that the panic contains a specific message see [`assert_panic`].
+///
+/// # Notes
+/// This function will wrap the provided closure with a call to [`catch_unwind`](`std::panic::catch_unwind`),
+/// and will therefore inherit the caveats of this function, most notably that it will be unable to catch
+/// panics if they are not implemented via unwinding.
+pub fn assert_panic_contains<T, F: FnOnce() -> T>(f: F, expected: &str) -> RunResult {
+    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)) {
+        // The test should have panicked, but didn't.
+        Ok(_) => Err(RunError::fail(DID_NOT_PANIC)),
+
+        // The test panicked, as expected. We need to check the panic message
+        Err(payload) => {
+            // The `panic` information is just an `Any` object representing the
+            // value the panic was invoked with. For most panics (which use
+            // `panic!` like `println!`), this is either `&str` or `String`.
+            let maybe_panic_str = payload
+                .downcast_ref::<String>()
+                .map(|s| s.as_str())
+                .or_else(|| payload.downcast_ref::<&str>().copied());
+
+            // Check the panic message against the expected message.
+            match maybe_panic_str {
+                Some(panic_str) if panic_str.contains(expected) => Ok(()),
+
+                Some(panic_str) => {
+                    let error_msg = ::std::format!(
+                        r#"panic did not contain expected string
+      panic message: {panic_str:?}
+ expected substring: {expected:?}"#
+                    );
+
+                    Err(RunError::fail(error_msg))
+                }
+
+                None => {
+                    let type_id = (*payload).type_id();
+                    let error_msg = ::std::format!(
+                        r#"expected panic with string value,
+ found non-string value: `{type_id:?}`
+     expected substring: {expected:?}"#,
+                    );
+
+                    Err(RunError::fail(error_msg))
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn assert_panic_with_panic() {
+        assert_panic(|| panic!("some message")).unwrap();
+    }
+
+    #[test]
+    fn assert_panic_no_panic() {
+        let result = assert_panic(|| { /* do absolutely nothing */ });
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn assert_panic_contains_correct_panic_message() {
+        assert_panic_contains(|| panic!("some message"), "mess").unwrap();
+    }
+
+    #[test]
+    fn assert_panic_contains_no_panic() {
+        let result = assert_panic_contains(|| { /* do absolutely nothing */ }, "fail");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn assert_panic_contains_wrong_panic_message() {
+        let result = assert_panic_contains(|| panic!("some message"), "fail");
+        assert!(result.is_err());
+    }
+}