Add unpack_chain_process macro and improve test docs

1 files changed, 141 insertions, 2 deletions

diff --git a/mingling_core/src/tester/chain_process_tester.rs b/mingling_core/src/tester/chain_process_tester.rs
index 20277fb..8189c28 100644
--- a/mingling_core/src/tester/chain_process_tester.rs
+++ b/mingling_core/src/tester/chain_process_tester.rs
@@ -52,7 +52,76 @@ where
     }
 }
 
+/// Unpacks the inner value from a `ChainProcess::Ok` result by downcasting it to the expected type.
+///
+/// This function extracts a reference to the output value of type `Type` from a `ChainProcess`
+/// result. It is useful when you know the exact output type and just want to get a reference to
+/// the inner data, without having to match on the enum yourself.
+///
+/// # Parameters
+///
+/// * `result` - A reference to the chain process result to unpack.
+///
+/// # Generic Constraints
+///
+/// * `C` - Must implement `ProgramCollect`, `Display`, `PartialEq` and have a `'static` lifetime.
+/// * `Type` - The expected output type. Must be `'static` and match the actual output type stored
+///   in the result.
+///
+/// # Panics
+///
+/// Panics in the following cases:
+/// - The result is `ChainProcess::Err`, outputting the error message via `Debug`.
+/// - The downcast fails because the actual output type does not match `Type`, panicking with a
+///   message indicating a type mismatch.
+///
+/// # Returns
+///
+/// A reference to the inner value of type `Type` if the result is `ChainProcess::Ok` and the
+/// downcast succeeds.
+pub fn unpack_chain_process_result<C, Type: 'static>(result: &ChainProcess<C>) -> &Type
+where
+    C: ProgramCollect + Display + PartialEq + 'static,
+{
+    match result {
+        ChainProcess::Ok((any, _next)) => any
+            .downcast_ref::<Type>()
+            .expect("Type mismatch: expected type does not match actual output type"),
+        ChainProcess::Err(chain_process_error) => panic!("{:?}", chain_process_error),
+    }
+}
+
 /// Asserts that a chain process result has the expected output type and next state.
+///
+/// This macro provides a convenient way to verify that a `ChainProcess` result meets expectations.
+/// It wraps `assert_next_eq`, allowing optional checks on the output type (`member_id`) and the
+/// next processing state.
+///
+/// # Parameters
+///
+/// * `$result` - An expression evaluating to a `ChainProcess<C>`.
+/// * `$expected_next` - (Optional) The expected next state, expressed as a path. If provided, the
+///   macro checks that the result's next state matches this value.
+/// * `$expected_type` - (Optional) The expected output type, expressed as a path. If provided, the
+///   macro checks that the result's `member_id` matches this value.
+///
+/// # Panics
+///
+/// Panics if the result is `ChainProcess::Err`, or if any provided expectation does not match the
+/// actual value.
+///
+/// # Examples
+///
+/// ```ignore
+/// // Check both next state and output type
+/// assert_next!(result, NextProcess::End, MyOutputType);
+///
+/// // Check only next state
+/// assert_next!(result, NextProcess::End);
+///
+/// // Check only that the result is Ok
+/// assert_next!(result);
+/// ```
 #[macro_export]
 macro_rules! assert_next {
     ($result:expr, $expected_next:path, $expected_type:path) => {
@@ -66,7 +135,26 @@ macro_rules! assert_next {
     };
 }
 
-/// Asserts that a chain process result is Ok and has the expected output type.
+/// Asserts that a chain process result is `Ok` without checking the output type or next state.
+///
+/// This macro checks that the `ChainProcess` result is `ChainProcess::Ok`, panicking if it is
+/// `ChainProcess::Err`. It does **not** validate the output type identifier (`member_id`) or the
+/// next processing state, making it useful when you only need to verify that the chain completed
+/// without errors.
+///
+/// # Parameters
+///
+/// * `$result` - An expression evaluating to a `ChainProcess<C>`.
+///
+/// # Panics
+///
+/// Panics if the result is `ChainProcess::Err`, displaying the error message.
+///
+/// # Example
+///
+/// ```ignore
+/// assert_chain_result!(result);
+/// ```
 #[macro_export]
 macro_rules! assert_chain_result {
     ($result:expr) => {
@@ -74,7 +162,24 @@ macro_rules! assert_chain_result {
     };
 }
 
-/// Alias for assert_chain_result.
+/// Alias for `assert_chain_result`.
+///
+/// This macro provides a more semantic name when asserting the result of a render operation.
+/// It checks that the `ChainProcess` result is `Ok` without verifying specific output types or next states.
+///
+/// # Parameters
+///
+/// * `$result` - An expression evaluating to a `ChainProcess<C>`.
+///
+/// # Panics
+///
+/// Panics if the result is `ChainProcess::Err`, displaying the error message.
+///
+/// # Example
+///
+/// ```ignore
+/// assert_render_result!(result);
+/// ```
 #[macro_export]
 macro_rules! assert_render_result {
     ($result:expr) => {
@@ -83,9 +188,43 @@ macro_rules! assert_render_result {
 }
 
 /// Asserts that the result's output type matches the expected member_id.
+///
+/// This macro checks that the `ChainProcess` result is `Ok` and that its output type identifier
+/// matches the expected type. It is a convenience wrapper around `assert_next_eq` with the `next`
+/// check skipped.
+///
+/// # Parameters
+///
+/// * `$result` - An expression evaluating to a `ChainProcess<C>`.
+/// * `$expected_type` - The expected output type (a path like `SomeType`).
+///
+/// # Panics
+///
+/// Panics if the result is `ChainProcess::Err` or if the output `member_id` does not match the
+/// expected type.
 #[macro_export]
 macro_rules! assert_member_id {
     ($result:expr, $expected_type:path) => {
         ::mingling::test::assert_next_eq(&$result, None, Some($expected_type))
     };
 }
+
+/// Unpacks a `ChainProcess::Ok` result by downcasting to the specified type.
+///
+/// This macro wraps the function `::mingling::test::unpack_chain_process_result` to provide
+/// a more ergonomic way to extract the inner value from a chain process result.
+///
+/// # Parameters
+///
+/// * `$result` - A reference to or expression evaluating to a `ChainProcess<C>`.
+/// * `$type` - The expected output type to downcast to.
+///
+/// # Panics
+///
+/// Panics if the result is `ChainProcess::Err` or if the downcast fails.
+#[macro_export]
+macro_rules! unpack_chain_process {
+    ($result:expr, $type:ty) => {
+        ::mingling::test::unpack_chain_process_result::<_, $type>(&$result)
+    };
+}