feat: Add assert_panic function

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;
 
 #[doc = include_str!("../README.md")]
 #[cfg(doctest)]

crates/libtest2/src/panic.rs

@@ -0,0 +1,85 @@
+use libtest2_harness::{RunError, RunResult};
+
+/// Assert that a piece of code is intended to panic
+///
+/// This will wrap the provided closure with a call to [`catch_unwind`](`std::panic::catch_unwind`),
+/// and check the result for a panic. If the function fails to panic an error value is returned,
+/// otherwise `Ok(())` is returned.
+///
+/// # Examples
+/// Asserting that a test panics
+///
+/// ```rust
+/// fn panicky_test() {
+///     panic!("intentionally fails");
+/// }
+///
+/// let result = libtest2::assert_panic(panicky_test, None);
+/// assert!(result.is_ok());
+/// ```
+///
+/// Asserting that a test panics with a specific message, in which case the panic message must
+/// contain the provided substring.
+///
+/// ```rust
+/// fn panicky_test() {
+///     panic!("intentionally fails");
+/// }
+///
+/// let result = libtest2::assert_panic(panicky_test, Some("fail"));
+/// assert!(result.is_ok());
+///
+/// let result = libtest2::assert_panic(panicky_test, Some("can't find this"));
+/// assert!(result.is_err());
+/// ```
+pub fn assert_panic<T, F: FnOnce() -> T>(f: F, panic_message: Option<&str>) -> RunResult {
+    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(f));
+
+    match (result, panic_message) {
+        // The test should have panicked, but didn't.
+        (Ok(_), _) => {
+            // TODO: Rust includes the source file location here, consider doing the same?
+            Err(RunError::fail("test did not panic as expected"))
+        }
+
+        // The test panicked, as expected.
+        (Err(_), None) => Ok(()),
+
+        // The test panicked, as expected. We need to check the panic message
+        (Err(payload), Some(expected)) => {
+            // 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))
+                }
+            }
+        }
+    }
+}