feat(core): add same-ness testing functions and modernise test patterns

Adds same-ness testing utilities that distinguish between value equality
and reference equality for different Go types, alongside comprehensive
refactoring of existing test suites to use modern assertion patterns.

For value types (numbers, strings, booleans), same-ness means equal
values. For reference types (slices, maps, pointers, channels,
functions), same-ness means pointer equality to the same underlying
data structure.

New functions:
- IsSame() base function with comprehensive type handling.
- AssertSame() and AssertNotSame() testing assertions.
- asReflectValue() helper to avoid duplicate reflect.ValueOf() calls.
- isReflectValueSame() helper following established naming patterns.

Key features:
- Proper nil handling: typed nils of same type are considered same.
- Interface support with recursive comparison of contained values.
- Complexity-compliant implementation using helper functions.
- Interface comparison inlined directly into isSamePointer() for efficiency.

Test modernisation:
- Refactored as_test.go to use AssertEqual for length checks.
- Modernised compounderror_test.go with AssertSame, AssertEqual, AssertNotNil.
- Updated errgroup_test.go to use AssertSame for error instance checks.
- Improved lists_test.go with AssertNotSame for independence verification.
- Applied fatal assertion pattern consistently for critical preconditions.

Documentation updates:
- Added same-ness function documentation to README.md.
- Extended TESTING.md with assertion usage examples.
- Updated function documentation to match final implementation.

Includes comprehensive test suite with 263 lines of test code covering
all scenarios: value types, reference types, nil handling, different
types, interface wrapping, and reflect.Value handling.

Coverage increased to 97.0% with full linting compliance.

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

Author: Alejandro Mery

README.md

@@ -124,6 +124,13 @@ Key distinctions from `IsZero`:
 * **Structs**: `IsNil(struct{}{})` returns `false` (structs cannot be nil),
   `IsZero(struct{}{})` returns `true` (zero struct is uninitialized).
 
+#### Same Value Detection
+
+* `IsSame(a, b)` - reports whether two values are the same. For reference
+  types (slices, maps, pointers), compares by pointer equality. For value
+  types (numbers, strings, booleans), compares by equal values. Two nils
+  of the same type are considered the same.
+
 #### Other Utilities
 
 * `Coalesce[T](values...)` returns the first non-zero value.
@@ -466,6 +473,10 @@ both `*testing.T` and `MockT`:
   comparison.
 * `AssertSliceEqual[T](t, expected, actual, msg...)` - slice comparison using
   `reflect.DeepEqual`.
+* `AssertSame(t, expected, actual, msg...)` - same value/reference comparison
+  using pointer equality for reference types, value equality for basic types.
+* `AssertNotSame(t, expected, actual, msg...)` - different value/reference
+  comparison.
 * `AssertTrue(t, condition, msg...)` / `AssertFalse(t, condition, msg...)` -
   boolean assertions.
 * `AssertNil(t, value, msg...)` / `AssertNotNil(t, value, msg...)` - nil

TESTING.md

@@ -89,6 +89,8 @@ for log messages, not a complete message:
 core.AssertEqual(t, expected, actual, "value")
 core.AssertNotEqual(t, expected, actual, "value")
 core.AssertSliceEqual(t, expectedSlice, actualSlice, "slice")
+core.AssertSame(t, expected, actual, "same reference/value")
+core.AssertNotSame(t, expected, actual, "different reference/value")
 core.AssertTrue(t, condition, "condition")
 core.AssertFalse(t, condition, "negation")
 core.AssertNil(t, value, "nil check")

as_test.go

@@ -162,8 +162,8 @@ func (tc sliceAsTestCase) Test(t *testing.T) {
 	t.Helper()
 
 	got := SliceAs[any, string](tc.input)
-	if len(got) != len(tc.want) {
-		t.Fatalf("SliceAs() len = %v, want %v", len(got), len(tc.want))
+	if !AssertEqual(t, len(tc.want), len(got), "slice length") {
+		return
 	}
 	for i, v := range got {
 		if v != tc.want[i] {
@@ -198,8 +198,8 @@ func (tc sliceAsFnTestCase) Test(t *testing.T) {
 	t.Helper()
 
 	got := SliceAsFn(tc.fn, tc.input)
-	if len(got) != len(tc.want) {
-		t.Fatalf("SliceAsFn() len = %v, want %v", len(got), len(tc.want))
+	if !AssertEqual(t, len(tc.want), len(got), "slice length") {
+		return
 	}
 	for i, v := range got {
 		if v != tc.want[i] {
@@ -299,8 +299,8 @@ func (tc asErrorsTestCase) Test(t *testing.T) {
 	t.Helper()
 
 	got := AsErrors(tc.input)
-	if len(got) != tc.wantLen {
-		t.Fatalf("AsErrors() len = %v, want %v", len(got), tc.wantLen)
+	if !AssertEqual(t, tc.wantLen, len(got), "slice length") {
+		return
 	}
 	for i, err := range got {
 		if err.Error() != tc.wantMsgs[i] {

compounderror_test.go

@@ -56,8 +56,8 @@ func (tc compoundErrorErrorTestCase) Test(t *testing.T) {
 	ce := &CompoundError{Errs: tc.errs}
 	result := ce.Error()
 
-	if result != tc.expected {
-		t.Fatalf("expected '%s', got '%s'", tc.expected, result)
+	if !AssertEqual(t, tc.expected, result, "error string") {
+		return
 	}
 }
 
@@ -74,13 +74,13 @@ func TestCompoundErrorErrors(t *testing.T) {
 	ce := &CompoundError{Errs: errs}
 	result := ce.Errors()
 
-	if len(result) != len(errs) {
-		t.Fatalf("expected %d errors, got %d", len(errs), len(result))
+	if !AssertEqual(t, len(errs), len(result), "error count") {
+		return
 	}
 
 	for i, err := range result {
-		if err != errs[i] {
-			t.Fatalf("expected error %d to be %v, got %v", i, errs[i], err)
+		if !AssertSame(t, errs[i], err, "error %d", i) {
+			return
 		}
 	}
 }
@@ -94,13 +94,13 @@ func TestCompoundErrorUnwrap(t *testing.T) {
 	ce := &CompoundError{Errs: errs}
 	result := ce.Unwrap()
 
-	if len(result) != len(errs) {
-		t.Fatalf("expected %d errors, got %d", len(errs), len(result))
+	if !AssertEqual(t, len(errs), len(result), "error count") {
+		return
 	}
 
 	for i, err := range result {
-		if err != errs[i] {
-			t.Fatalf("expected error %d to be %v, got %v", i, errs[i], err)
+		if !AssertSame(t, errs[i], err, "error %d", i) {
+			return
 		}
 	}
 }
@@ -191,16 +191,14 @@ func (tc compoundErrorAsErrorTestCase) Test(t *testing.T) {
 	result := ce.AsError()
 
 	if tc.expectNil {
-		if result != nil {
-			t.Fatalf("expected nil, got %v", result)
+		if !AssertNil(t, result, "result") {
+			return
 		}
 	} else {
-		if result == nil {
-			t.Fatalf("expected non-nil error, got nil")
-		}
-		if result != ce {
-			t.Fatalf("expected same CompoundError instance, got different")
+		if !AssertNotNil(t, result, "result") {
+			return
 		}
+		AssertSame(t, ce, result, "CompoundError instance")
 	}
 }
 
@@ -245,19 +243,19 @@ func (tc compoundErrorAppendErrorTestCase) Test(t *testing.T) {
 	result := ce.AppendError(tc.toAppend...)
 
 	// Test method chaining
-	if result != ce {
-		t.Fatalf("expected same CompoundError instance for chaining")
+	if !AssertSame(t, ce, result, "CompoundError instance") {
+		return
 	}
 
 	// Test length
-	if len(ce.Errs) != tc.expectedLen {
-		t.Fatalf("expected %d errors, got %d", tc.expectedLen, len(ce.Errs))
+	if !AssertEqual(t, tc.expectedLen, len(ce.Errs), "error count") {
+		return
 	}
 
 	// Test no nil errors were added
 	for i, err := range ce.Errs {
-		if err == nil {
-			t.Fatalf("unexpected nil error at index %d", i)
+		if !AssertNotNil(t, err, "error %d", i) {
+			return
 		}
 	}
 }
@@ -273,26 +271,26 @@ func TestCompoundErrorAppendErrorWithCompoundError(t *testing.T) {
 	result := ce1.AppendError(ce2)
 
 	// Test method chaining
-	if result != ce1 {
-		t.Fatalf("expected same CompoundError instance for chaining")
+	if !AssertSame(t, ce1, result, "CompoundError instance") {
+		return
 	}
 
 	// Should unwrap the compound error and append individual errors
 	expectedLen := 3 // original 1 + unwrapped 2
-	if len(ce1.Errs) != expectedLen {
-		t.Fatalf("expected %d errors, got %d", expectedLen, len(ce1.Errs))
+	if !AssertEqual(t, expectedLen, len(ce1.Errs), "error count") {
+		return
 	}
 
 	// Check error messages
 	errorStr := ce1.Error()
-	if !strings.Contains(errorStr, "first") {
-		t.Fatalf("expected 'first' in error string, got '%s'", errorStr)
+	if !AssertContains(t, errorStr, "first", "error string") {
+		return
 	}
-	if !strings.Contains(errorStr, "second") {
-		t.Fatalf("expected 'second' in error string, got '%s'", errorStr)
+	if !AssertContains(t, errorStr, "second", "error string") {
+		return
 	}
-	if !strings.Contains(errorStr, "third") {
-		t.Fatalf("expected 'third' in error string, got '%s'", errorStr)
+	if !AssertContains(t, errorStr, "third", "error string") {
+		return
 	}
 }
 
@@ -317,14 +315,14 @@ func TestCompoundErrorAppendErrorWithUnwrappable(t *testing.T) {
 	result := ce.AppendError(mock)
 
 	// Test method chaining
-	if result != ce {
-		t.Fatalf("expected same CompoundError instance for chaining")
+	if !AssertSame(t, ce, result, "CompoundError instance") {
+		return
 	}
 
 	// Should unwrap and append individual errors
 	expectedLen := 3 // original 1 + unwrapped 2
-	if len(ce.Errs) != expectedLen {
-		t.Fatalf("expected %d errors, got %d", expectedLen, len(ce.Errs))
+	if !AssertEqual(t, expectedLen, len(ce.Errs), "error count") {
+		return
 	}
 }
 
@@ -375,19 +373,17 @@ func (tc compoundErrorAppendTestCase) Test(t *testing.T) {
 	result := ce.Append(tc.err, tc.note, tc.args...)
 
 	// Test method chaining
-	if result != ce {
-		t.Fatalf("expected same CompoundError instance for chaining")
-	}
+	AssertSame(t, ce, result, "CompoundError instance")
 
 	// Test length
-	if len(ce.Errs) != tc.expectedLen {
-		t.Fatalf("expected %d errors, got %d", tc.expectedLen, len(ce.Errs))
+	if !AssertEqual(t, tc.expectedLen, len(ce.Errs), "error count") {
+		return
 	}
 
 	if tc.expectedLen > 0 {
 		lastErr := ce.Errs[len(ce.Errs)-1]
-		if lastErr == nil {
-			t.Fatalf("expected non-nil error")
+		if !AssertNotNil(t, lastErr, "last error") {
+			return
 		}
 
 		errorStr := lastErr.Error()
@@ -397,8 +393,10 @@ func (tc compoundErrorAppendTestCase) Test(t *testing.T) {
 				if len(tc.args) > 0 {
 					expectedNote = "wrapped note: 42" // for the formatted case
 				}
-				if !strings.Contains(errorStr, expectedNote) && !strings.Contains(errorStr, tc.note) {
-					t.Fatalf("expected note in error string, got '%s'", errorStr)
+				foundExpected := strings.Contains(errorStr, expectedNote)
+				foundOriginal := strings.Contains(errorStr, tc.note)
+				if !AssertTrue(t, foundExpected || foundOriginal, "note in error string") {
+					return
 				}
 			}
 		}
@@ -419,20 +417,20 @@ func TestCompoundErrorAppendChaining(t *testing.T) {
 		Append(errors.New("fourth"), "wrapped %s", "note")
 
 	// Test method chaining returns same instance
-	if result != ce {
-		t.Fatalf("expected same CompoundError instance for chaining")
+	if !AssertSame(t, ce, result, "CompoundError instance") {
+		return
 	}
 
 	// Test final length
 	expectedLen := 4
-	if len(ce.Errs) != expectedLen {
-		t.Fatalf("expected %d errors, got %d", expectedLen, len(ce.Errs))
+	if !AssertEqual(t, expectedLen, len(ce.Errs), "error count") {
+		return
 	}
 
 	// Test that all errors are non-nil
 	for i, err := range ce.Errs {
-		if err == nil {
-			t.Fatalf("unexpected nil error at index %d", i)
+		if !AssertNotNil(t, err, "error %d", i) {
+			return
 		}
 	}
 }
@@ -443,12 +441,12 @@ func TestCompoundErrorNilHandling(t *testing.T) {
 
 	_ = ce.AppendError(nil, errors.New("valid"), nil)
 
-	if len(ce.Errs) != 1 {
-		t.Fatalf("expected 1 error, got %d", len(ce.Errs))
+	if !AssertEqual(t, 1, len(ce.Errs), "error count") {
+		return
 	}
 
-	if ce.Errs[0].Error() != "valid" {
-		t.Fatalf("expected 'valid' error, got '%s'", ce.Errs[0].Error())
+	if !AssertEqual(t, "valid", ce.Errs[0].Error(), "error message") {
+		return
 	}
 }
 
@@ -462,13 +460,13 @@ func TestCompoundErrorIsInterface(t *testing.T) {
 	var _ error = ce
 
 	// Test that Error() method works
-	if ce.Error() == "" {
-		t.Fatalf("expected non-empty error string")
+	if !AssertTrue(t, ce.Error() != "", "non-empty error string") {
+		return
 	}
 
 	// Test that Errors() method works
 	errs := ce.Errors()
-	if len(errs) != 1 {
-		t.Fatalf("expected 1 error, got %d", len(errs))
+	if !AssertEqual(t, 1, len(errs), "error count") {
+		return
 	}
 }

errgroup_test.go

@@ -317,9 +317,7 @@ func testErrGroupSubsequentCancellation(t *testing.T) {
 	}
 
 	// Should keep the first error
-	if err := eg.Err(); err != cause1 {
-		t.Errorf("Expected first error %v, got %v", cause1, err)
-	}
+	AssertSame(t, cause1, eg.Err(), "error instance")
 }
 
 func testErrGroupNilCause(t *testing.T) {
@@ -332,9 +330,7 @@ func testErrGroupNilCause(t *testing.T) {
 		t.Error("Expected first cancellation to return true")
 	}
 
-	if err := eg.Err(); err != context.Canceled {
-		t.Errorf("Expected context.Canceled, got %v", err)
-	}
+	AssertSame(t, context.Canceled, eg.Err(), "error instance")
 }
 
 func TestErrGroupCancel(t *testing.T) {
@@ -357,9 +353,7 @@ func TestErrGroupOnError(t *testing.T) {
 	// Give time for onError to be called
 	time.Sleep(1 * time.Millisecond)
 
-	if errorReceived != testErr {
-		t.Errorf("Expected onError to receive %v, got %v", testErr, errorReceived)
-	}
+	AssertSame(t, testErr, errorReceived, "error instance")
 }
 
 func TestErrGroupContext(t *testing.T) {
@@ -494,9 +488,7 @@ func testErrGroupCatcherErrorWhenNotCancelled(t *testing.T) {
 	testErr := errors.New("test error")
 	result := eg.defaultErrGroupCatcher(testErr)
 
-	if result != testErr {
-		t.Errorf("Expected %v, got %v", testErr, result)
-	}
+	AssertSame(t, testErr, result, "error instance")
 }
 
 func testErrGroupCatcherErrorWhenCancelled(t *testing.T) {

lists_test.go

@@ -219,9 +219,7 @@ func (tc listCopyTestCase) Test(t *testing.T) {
 	}
 
 	// Verify they are different lists (not the same pointer)
-	if orig == copied {
-		t.Error("ListCopy should return a different list instance")
-	}
+	AssertNotSame(t, orig, copied, "list instance")
 
 	// Verify independence - modifying one doesn't affect the other
 	if orig.Len() > 0 {