feat(test): diagnose failed effect assertions

hemx-test/src/lib.rs

@@ -492,10 +492,28 @@ impl EffectInspector {
         })
     }
 
-    /// Assert that a generated target receives an HTML update containing text.
+    /// Check that a generated target receives an HTML update containing text.
     /// req: test/001 req: dx/006
     pub fn updates_html_containing(&self, target: impl GeneratedTarget, needle: &str) -> bool {
+        self.has_html_update_containing(target.__hemx_resource_id(), needle)
+    }
+
+    /// Assert that a generated target receives an HTML update containing text.
+    ///
+    /// Unlike wrapping [`Self::updates_html_containing`] in `assert!`, failures include the
+    /// expected resource and payload fragment together with every actual effect operation.
+    /// req: test/001 req: test/018 req: dx/006
+    #[track_caller]
+    pub fn assert_updates_html_containing(&self, target: impl GeneratedTarget, needle: &str) {
         let resource = target.__hemx_resource_id();
+        assert!(
+            self.has_html_update_containing(resource, needle),
+            "expected an HTML update for {resource:?} containing {needle:?}; actual effects: {:#?}",
+            self.batch.ops
+        );
+    }
+
+    fn has_html_update_containing(&self, resource: ResourceId, needle: &str) -> bool {
         self.batch.ops.iter().any(|op| {
             matches!(
                 op,

hemx-test/tests/inspector.rs

@@ -17,6 +17,30 @@ fn inspects_tuple_effects() {
     }));
 }
 
+#[test]
+fn html_update_assertion_reports_expectation_and_actual_effects() {
+    // req: test/018
+    let target = TestTarget(ResourceKind::Slot, 42);
+    let inspected = hemx_test::inspect(Effect::Put {
+        target: ResourceRef::unscoped(ResourceId::new(ResourceKind::Slot, 7)),
+        payload: Payload::Html(String::from("<p>actual</p>")),
+    });
+
+    let panic = std::panic::catch_unwind(|| {
+        inspected.assert_updates_html_containing(target, "expected fragment");
+    })
+    .expect_err("a mismatched target and payload must fail");
+    let message = panic
+        .downcast_ref::<String>()
+        .map(String::as_str)
+        .or_else(|| panic.downcast_ref::<&str>().copied())
+        .expect("assertion panic must carry a message");
+
+    assert!(message.contains("expected fragment"), "{message}");
+    assert!(message.contains("ResourceId"), "{message}");
+    assert!(message.contains("actual"), "{message}");
+}
+
 #[test]
 fn finds_keyed_slot_targets() {
     let rows = KeyedSlot::<u32, String>::new(9);