feat(testing): add AssertMustFoo() variants that call t.FailNow() on failure

Add 14 new AssertMustFoo() functions that automatically call t.FailNow()
when assertions fail, providing a cleaner alternative to the manual
`if !AssertFoo() { t.FailNow() }` pattern.

New functions follow Go testing conventions where "Fatal" methods
terminate execution, similar to t.Error() vs t.Fatal():

- AssertMustEqual[T], AssertMustNotEqual[T], AssertMustSliceEqual[T]
- AssertMustTrue, AssertMustFalse, AssertMustNil, AssertMustNotNil
- AssertMustContains, AssertMustError, AssertMustNoError, AssertMustErrorIs
- AssertMustPanic, AssertMustNoPanic, AssertMustTypeIs[T]

All functions include comprehensive tests using MockT.Run() to verify
both success (execution continues) and failure (t.FailNow() called,
execution terminates) scenarios.

Documentation added to README.md with clear explanation of Error vs
Fatal patterns and usage examples.

Signed-off-by: Alejandro Mery <amery@apptly.co>

Author: amery

README.md

@@ -507,6 +507,57 @@ both `*testing.T` and `MockT`:
 * `AssertPanic(t, fn, expectedPanic, msg...)` / `AssertNoPanic(t, fn, msg...)` -
   panic testing.
 
+#### Fatal Assertions
+
+All `AssertMustFoo()` functions call the corresponding `AssertFoo()` function
+and automatically call `t.FailNow()` if the assertion fails, terminating test
+execution immediately. These follow Go testing conventions where "Fatal"
+methods terminate execution, similar to `t.Error()` vs `t.Fatal()`.
+
+**Key Differences:**
+
+* `AssertFoo()` - like `t.Error()`, logs failure and allows test to continue.
+* `AssertMustFoo()` - like `t.Fatal()`, logs failure and terminates test
+  execution.
+
+**Fatal Assertion Functions:**
+
+* `AssertMustEqual[T](t, expected, actual, msg...)` - terminate on inequality.
+* `AssertMustNotEqual[T](t, expected, actual, msg...)` - terminate on equality.
+* `AssertMustSliceEqual[T](t, expected, actual, msg...)` - terminate on slice
+  inequality.
+* `AssertMustTrue(t, condition, msg...)` /
+  `AssertMustFalse(t, condition, msg...)` - terminate on boolean mismatch.
+* `AssertMustNil(t, value, msg...)` / `AssertMustNotNil(t, value, msg...)` -
+  terminate on nil check failure.
+* `AssertMustContains(t, text, substring, msg...)` - terminate if substring not
+  found.
+* `AssertMustError(t, err, msg...)` / `AssertMustNoError(t, err, msg...)` -
+  terminate on error expectation mismatch.
+* `AssertMustErrorIs(t, err, target, msg...)` - terminate on error chain
+  mismatch.
+* `AssertMustTypeIs[T](t, value, msg...) T` - terminate on type assertion
+  failure, returns cast value.
+* `AssertMustPanic(t, fn, expectedPanic, msg...)` /
+  `AssertMustNoPanic(t, fn, msg...)` - terminate on panic expectation mismatch.
+
+**Usage Examples:**
+
+```go
+// Error pattern - logs failure, test continues
+AssertEqual(t, expected, actual, "value check")
+// execution continues even if assertion fails
+
+// Fatal pattern - logs failure, test terminates
+AssertMustEqual(t, expected, actual, "critical value check")
+// execution stops here if assertion fails
+
+// Traditional early abort pattern (equivalent to AssertMust*)
+if !AssertEqual(t, expected, actual, "critical value") {
+    t.FailNow()
+}
+```
+
 ### Advanced Testing Utilities
 
 * `TestCase` interface - standardised interface for table-driven tests with
@@ -563,7 +614,7 @@ Context-aware error group with cancellation:
 For detailed development setup, build commands, and AI agent guidance:
 
 * [AGENT.md](./AGENT.md) - Development guidelines, build system, and testing
-  patterns
+  patterns.
 
 ### Quick Start
 

TESTING.md

@@ -112,6 +112,27 @@ core.AssertPanic(t, func() { panic("test") }, "panic")
 core.AssertNoPanic(t, func() { /* safe code */ }, "no panic")
 ```
 
+**Fatal Assertions (`AssertMust*`):**
+
+All `AssertMustFoo()` functions call the corresponding `AssertFoo()` function
+and automatically call `t.FailNow()` if the assertion fails, terminating test
+execution immediately:
+
+```go
+// Standard assertions - log failure, test continues
+core.AssertEqual(t, expected, actual, "value")
+// ... test execution continues even if assertion fails
+
+// Fatal assertions - log failure, test terminates
+core.AssertMustEqual(t, expected, actual, "critical value")
+// ... test execution stops here if assertion fails
+```
+
+**Key Difference:**
+
+* `AssertFoo()` - like `t.Error()`, allows test to continue after failure.
+* `AssertMustFoo()` - like `t.Fatal()`, terminates test on failure.
+
 ### Assertion Function Hierarchy Guidelines
 
 When creating custom assertion functions, follow these hierarchy principles.
@@ -151,11 +172,11 @@ func AssertCustomTrue(t core.T, condition bool, name string,
 
 **Key Principles:**
 
-- **Avoid circular dependencies**: Don't test assertions using themselves.
-- **Maintain consistency**: Derived functions should use base functions for
+* **Avoid circular dependencies**: Don't test assertions using themselves.
+* **Maintain consistency**: Derived functions should use base functions for
   uniform error formatting and logging behaviour.
-- **Use helper pattern**: Always call `t.Helper()` in assertion functions.
-- **Follow naming**: Use `Assert` prefix and descriptive suffixes.
+* **Use helper pattern**: Always call `t.Helper()` in assertion functions.
+* **Follow naming**: Use `Assert` prefix and descriptive suffixes.
 
 **Understanding Assertion Prefixes:**
 
@@ -178,10 +199,10 @@ core.AssertTrue(t, SliceContains(got, k), "key %q present", k)
 
 **Prefix Guidelines:**
 
-- Use **short, descriptive prefixes** (1-3 words).
-- The prefix will be combined with the actual value: `"prefix: value"`.
-- For formatted messages, use printf-style formatting: `"contains %v", key`.
-- Avoid complete sentences - they become redundant with the logged value.
+* Use **short, descriptive prefixes** (1-3 words).
+* The prefix will be combined with the actual value: `"prefix: value"`.
+* For formatted messages, use printf-style formatting: `"contains %v", key`.
+* Avoid complete sentences - they become redundant with the logged value.
 
 ## COMPLIANT Test Structure Patterns
 
@@ -916,11 +937,11 @@ Run with: `go test -tags=integration`
 
 ### Test Naming
 
-- Test functions: `TestFunctionName`.
-- Test types: `functionNameTestCase`.
-- TestCase interface methods:
-  - `func (tc testCaseType) Name() string` - returns test case name
-  - `func (tc testCaseType) Test(t *testing.T)` - runs the test logic
+* Test functions: `TestFunctionName`.
+* Test types: `functionNameTestCase`.
+* TestCase interface methods:
+  * `func (tc testCaseType) Name() string` - returns test case name
+  * `func (tc testCaseType) Test(t *testing.T)` - runs the test logic
 
 ### Documentation
 
@@ -943,11 +964,11 @@ func (tc parseURLTestCase) Test(t *testing.T) {
 
 ### Clean Tests
 
-- Use `t.Helper()` in all helper functions.
-- Prefer table-driven tests over individual test functions.
-- Keep setup and clean-up minimal.
-- Use meaningful assertion descriptions.
-- Test both success and failure paths.
+* Use `t.Helper()` in all helper functions.
+* Prefer table-driven tests over individual test functions.
+* Keep setup and clean-up minimal.
+* Use meaningful assertion descriptions.
+* Test both success and failure paths.
 
 ### Test Data
 
@@ -1101,28 +1122,28 @@ func validationTestCases(fieldName string) []validationTestCase {
 
 Before committing test code, verify ALL 6 requirements:
 
-- [ ] **TestCase Interface Validations**: Added `var _ TestCase = ...` for
+* [ ] **TestCase Interface Validations**: Added `var _ TestCase = ...` for
       all test case types
-- [ ] **Factory Functions**: Created `newTestCaseTypeName()` for all test
+* [ ] **Factory Functions**: Created `newTestCaseTypeName()` for all test
       case types
-- [ ] **Factory Usage**: All test case declarations use factory functions
+* [ ] **Factory Usage**: All test case declarations use factory functions
       (no naked struct literals)
-- [ ] **RunTestCases Usage**: All test functions use `RunTestCases(t, cases)`
-- [ ] **Anonymous Functions**: No `t.Run()` anonymous functions longer than
+* [ ] **RunTestCases Usage**: All test functions use `RunTestCases(t, cases)`
+* [ ] **Anonymous Functions**: No `t.Run()` anonymous functions longer than
       3 lines
-- [ ] **Test Case List Factories**: Complex test case generation uses
+* [ ] **Test Case List Factories**: Complex test case generation uses
       `myFooTestCases()` factory functions
 
 ## Summary
 
 By following these **MANDATORY** guidelines, all darvaza.org projects will
 have:
 
-- **Consistent testing patterns** across the entire ecosystem.
-- **Lint-compliant code** that meets complexity requirements.
-- **Maintainable tests** that are easy to read and modify.
-- **Reliable test suites** with excellent error reporting.
-- **Comprehensive coverage** with meaningful assertions.
+* **Consistent testing patterns** across the entire ecosystem.
+* **Lint-compliant code** that meets complexity requirements.
+* **Maintainable tests** that are easy to read and modify.
+* **Reliable test suites** with excellent error reporting.
+* **Comprehensive coverage** with meaningful assertions.
 
 The key is to treat test code with the same care as production code, using
 the excellent utilities provided by `darvaza.org/core` to maintain

TESTING_core.md

@@ -158,21 +158,20 @@ func TestAssertEqual(t *testing.T) {
 
 #### Testing Fatal/FailNow Scenarios
 
-MockT's Run() method enables testing functions that call Fatal/FailNow:
+MockT's Run() method enables testing functions that call Fatal/FailNow methods,
+including the `AssertMust*` family of functions which automatically call
+`t.FailNow()` on assertion failure:
 
 ```go
 func TestFatalAssertion(t *testing.T) {
     mock := &MockT{}
 
-    // Test function that would call Fatal on failure
-    ok := mock.Run("fatal test", func(mt T) {
-        // This calls mt.Error() but doesn't panic
-        AssertEqual(mt, 1, 2, "will fail")
-
-        // To test actual Fatal behaviour:
-        if !AssertEqual(mt, 1, 2, "critical failure") {
-            mt.FailNow() // This will panic and be caught by Run()
-        }
+    // Test AssertMust* functions that call FailNow() automatically
+    ok := mock.Run("fatal assertion test", func(mt T) {
+        // This will call mt.FailNow() and cause Run() to return false
+        AssertMustEqual(mt, 1, 2, "critical failure")
+        // Execution stops here - this line won't be reached
+        mt.Log("should not reach here")
     })
 
     // Verify the test failed and was handled properly
@@ -185,6 +184,18 @@ func TestFatalAssertion(t *testing.T) {
     if !mock.HasErrors() {
         t.Error("Should have recorded error messages")
     }
+
+    // Traditional pattern - equivalent to AssertMust*
+    mock.Reset()
+    ok = mock.Run("manual fatal test", func(mt T) {
+        if !AssertEqual(mt, 1, 2, "manual check") {
+            mt.FailNow() // This will panic and be caught by Run()
+        }
+    })
+    // Verify same behaviour as AssertMust*
+    if ok {
+        t.Error("Manual FailNow should also cause test failure")
+    }
 }
 ```