Merge pull request #24 from 21johnh21/HAWL/SWE-43211-add-function-for-deep-equality-checking

SWE-43211 add function for deep equality checking

Author: KyleKincer

AI_AGENT_TESTING_GUIDE.md

@@ -22,6 +22,7 @@ The `$t.assert` object provides these methods:
 
 ```4d
 $t.assert.areEqual($t; expected; actual; "message")
+$t.assert.areDeepEqual($t; expected; actual; "message"; maxDepth)  // Deep equality for objects/collections (maxDepth optional, default: 10)
 $t.assert.isTrue($t; condition; "message")  
 $t.assert.isFalse($t; condition; "message")
 $t.assert.isNull($t; value; "message")

README.md

@@ -25,6 +25,11 @@ Function test_user_creation($t : cs.Testing)
     
     $t.assert.isNotNull($t; $user.name; "User should have a name")
     $t.assert.areEqual($t; "John"; $user.name; "User name should be correct")
+    
+    // Compare complex objects with deep equality
+    var $expected : Object
+    $expected:=New object("name"; "John"; "email"; "john@example.com")
+    $t.assert.areDeepEqual($t; $expected; $user; "User object should match expected structure")
 
 // #tags: integration, database
 Function test_user_persistence($t : cs.Testing)

docs/guide.md

@@ -134,6 +134,7 @@ The framework includes built-in assertion methods accessible through `$t.assert`
 
 ### Basic Assertions
 - `$t.assert.areEqual($t; $expected; $actual; $message)` - Values must be equal
+- `$t.assert.areDeepEqual($t; $expected; $actual; $message; $maxDepth)` - Deep equality comparison for objects and collections (optional `$maxDepth`, default: 10)
 - `$t.assert.isTrue($t; $value; $message)` - Value must be true
 - `$t.assert.isFalse($t; $value; $message)` - Value must be false
 - `$t.assert.isNull($t; $value; $message)` - Value must be null
@@ -157,6 +158,68 @@ Function test_calculations($t : cs.Testing.Testing)
     $t.assert.isNotNull($t; $result; "Function should return a result")
 ```
 
+### Deep Equality Assertions
+
+The `areDeepEqual` function performs recursive comparison of nested objects and collections, providing detailed difference reporting when values don't match. This is especially useful for testing complex data structures.
+
+**Basic Usage:**
+```4d
+Function test_object_comparison($t : cs.Testing.Testing)
+    var $expected; $actual : Object
+    $expected:={name: "John"; age: 30; address: {city: "New York"; zip: "10001"}}
+    $actual:={name: "John"; age: 30; address: {city: "New York"; zip: "10001"}}
+    
+    // Deep comparison of nested structures
+    $t.assert.areDeepEqual($t; $expected; $actual; "Objects should match")
+```
+
+**With Custom Max Depth:**
+```4d
+Function test_deep_nesting($t : cs.Testing.Testing)
+    var $expected; $actual : Object
+    // ... very deeply nested objects ...
+    
+    // Increase max depth for very deep structures (default is 10)
+    $t.assert.areDeepEqual($t; $expected; $actual; "Deep objects should match"; 20)
+```
+
+**Accessing Differences Programmatically:**
+When a deep equality assertion fails, the framework stores detailed difference information in `$t.lastDeepEqualDifferences`:
+
+```4d
+Function test_with_difference_analysis($t : cs.Testing.Testing)
+    var $expected; $actual : Object
+    $expected:={name: "John"; age: 30}
+    $actual:={name: "John"; age: 25}
+    
+    $t.assert.areDeepEqual($t; $expected; $actual; "Objects should match")
+    
+    // If assertion fails, analyze differences
+    If ($t.failed)
+        var $diff : Object
+        For each ($diff; $t.lastDeepEqualDifferences)
+            $t.log("Difference at "+$diff.path+": "+$diff.type)
+        End for each
+    End if
+```
+
+**Features:**
+- **Recursive Comparison**: Compares nested objects and collections at all levels
+- **Detailed Reporting**: Provides path-based difference reporting (e.g., `user.address.city`)
+- **Circular Reference Protection**: Max depth limit prevents infinite loops (default: 10 levels)
+- **Type Safety**: Detects type mismatches between expected and actual values
+- **Missing/Extra Keys**: Reports missing keys in actual object and extra keys not in expected
+- **Collection Support**: Handles collections with different lengths and element differences
+- **Programmatic Access**: Differences available via `$t.lastDeepEqualDifferences` collection
+
+**Difference Types:**
+- `different_value` - Values differ at a specific path
+- `missing_key` - Key exists in expected but not in actual
+- `extra_key` - Key exists in actual but not in expected
+- `different_type` - Types differ between expected and actual
+- `different_length` - Collections have different lengths
+- `max_depth_exceeded` - Recursion depth limit reached (increase `$maxDepth` if needed)
+
 ## Output Formats
 
 The framework provides terse output by default for cleaner results, with verbose mode available when more detail is needed.