dotnet-testing-complex-object-comparison

name	dotnet-testing-complex-object-comparison
category	testing
subcategory	assertions
description	Specialized skill for handling complex object comparison and deep validation. Use when you need to compare deep objects, exclude specific properties, handle circular references, or validate DTOs/Entities. Covers BeEquivalentTo, Excluding, Including, custom comparison rules, etc. Keywords: object comparison, deep comparison, BeEquivalentTo, DTO comparison, Entity validation, excluding properties, circular reference, Excluding, Including, ExcludingNestedObjects, RespectingRuntimeTypes, WithStrictOrdering, ignore timestamp, exclude timestamp
targets	["*"]
license	MIT
metadata	{"author":"Kevin Tseng","version":"1.0.0","tags":".NET, testing, object comparison, BeEquivalentTo, AwesomeAssertions","related_skills":"awesome-assertions-guide, autofixture-basics, test-data-builder-pattern"}
claudecode	{}
opencode	{}
codexcli	{"short-description":".NET skill guidance for dotnet-testing-complex-object-comparison"}
copilot	{}
geminicli	{}
antigravity	{}

Source: kevintsengtw/dotnet-testing-agent-skills (MIT). Ported into dotnet-agent-harness.

Complex Object Comparison Guide

Applicable Scenarios

This skill focuses on complex object comparison scenarios in .NET testing, using AwesomeAssertions' BeEquivalentTo API to handle various advanced comparison needs.

Core Usage Scenarios

1. Deep Object Structure Comparison (Object Graph Comparison)

When comparing complex objects containing multi-layer nested properties:

[Fact]
public void ComplexObject_Deep_Structure_Comparison_Should_Match()
{
    var expected = new Order
    {
        Id = 1,
        Customer = new Customer
        {
            Name = "John Doe",
            Address = new Address
            {
                Street = "123 Main St",
                City = "Seattle",
                ZipCode = "98101"
            }
        },
        Items = new[]
        {
            new OrderItem { ProductName = "Laptop", Quantity = 1, Price = 999.99m },
            new OrderItem { ProductName = "Mouse", Quantity = 2, Price = 29.99m }
        }
    };

    var actual = orderService.GetOrder(1);

    // Deep object comparison
    actual.Should().BeEquivalentTo(expected);
}
```text

### 2. Circular Reference Handling (Circular Reference Handling)

Handling cases where objects have circular references:

```csharp
[Fact]
public void TreeStructure_Circular_Reference_Should_Handle_Correctly()
{
    // Create tree structure with parent-child bidirectional references
     parent =  TreeNode { Value =  };
     child1 =  TreeNode { Value = , Parent = parent };
     child2 =  TreeNode { Value = , Parent = parent };
    parent.Children = [] { child1, child2 };

     actualTree = treeService.GetTree();

    
    actualTree.Should().BeEquivalentTo(parent, options =>
        options.IgnoringCyclicReferences()
               .WithMaxRecursionDepth()
    );
}
```text



FluentAssertions provides various advanced comparison patterns: 
{
     expected =  Product { Id = , Name = , Price =  };
     actual = dbContext.Products.Find();

    actual.Should().BeEquivalentTo(expected, options =>
        options.ExcludingMissingMembers()  
               .Excluding(p => p.CreatedAt)
               .Excluding(p => p.UpdatedAt)
    );
}
```text



```csharp
[]

{
     expected =  UserDto
    {
        Id = ,
        Username = 
    };

     response =  httpClient.GetAsync();
     actual =  response.Content.ReadFromJsonAsync<UserDto>();

    actual.Should().BeEquivalentTo(expected, options =>
        options.ExcludingMissingMembers()  
    );
}
```text



```csharp
[]

{
     expected =  OrderBuilder()
        .WithId()
        .WithCustomer()
        .WithItems()
        .Build();

     actual = orderService.CreateOrder(orderRequest);

    actual.Should().BeEquivalentTo(expected, options =>
        options.Excluding(o => o.OrderNumber)  
               .Excluding(o => o.CreatedAt)
    );
}
```text





```csharp
[]

{
     expected =  User { Name = , Age =  };
     actual = userService.GetUser();

    
    actual.Should().BeEquivalentTo(expected, options =>
        options.Excluding(u => u.Id)
               .Because()
    );
}
```text



```csharp
[]

{
     users = userService.GetAllUsers();

     ( AssertionScope())
    {
         ( user  users)
        {
            user.Id.Should().BeGreaterThan();
            user.Name.Should().NotBeNullOrEmpty();
            user.Email.Should().MatchRegex();
        }
    }
    
}
```text



This skill can be combined  the following:

- **awesome-assertions-guide**: Basic assertion syntax  common APIs
- **autofixture-data-generation**: Automatically generate test data
- **test-data-builder-pattern**: Build complex test objects
- **unit-test-fundamentals**: Unit testing basics  A pattern





 **Prefer Property Exclusion over Inclusion**: Unless only validating a few properties,  `Excluding`  clearer
 **Create Reusable Exclusion Extension Methods**: Avoid repeating exclusion logic  each test
 **Set Reasonable Strategies  Large Data Comparison**: Balance performance  validation completeness
 **Use AssertionScope  Batch Validation**: See all failure reasons at once
 **Provide Meaningful because Descriptions**: Help future maintainers understand test intent



 **Avoid Over-reliance  Complete Object Comparison**: Consider only validating key properties
 **Avoid Ignoring Circular Reference Issues**: Use `IgnoringCyclicReferences()` to explicitly handle
 **Avoid Repeating Exclusion Logic  Each Test**: Extract  extension methods
 **Avoid Full Deep Comparison  Large Data**: Use sampling  key property validation





**A:** Use the following strategies to optimize:

- Use `Including` to only compare key properties
- Use sampling validation  large data
- Use `WithMaxRecursionDepth` to limit recursion depth
- Consider  `AssertKeyPropertiesOnly`  quick comparison of key fields



**A:** Usually caused  circular references:

```csharp
options.IgnoringCyclicReferences()
       .WithMaxRecursionDepth()
```text



**A:** Use path pattern matching:

```csharp
options.Excluding(ctx => ctx.Path.EndsWith())
       .Excluding(ctx => ctx.Path.EndsWith())
       .Excluding(ctx => ctx.Path.Contains())
```text



**A:** Enable detailed tracing:

```csharp
options.WithTracing()  
```text



This skill provides the following template files:

- `templates/comparison-patterns.cs`: Common comparison pattern examples
- `templates/exclusion-strategies.cs`: Field exclusion strategies  extension methods





This skill content  distilled  the  article series:

- **Day  - AwesomeAssertions Advanced Techniques  Complex Scenario Applications**
  - Article: https:
  - Sample Code: https:



- [AwesomeAssertions GitHub](https:
- [AwesomeAssertions Documentation](https:



- `awesome-assertions-guide` - AwesomeAssertions basics  advanced usage
- `unit-test-fundamentals` - Unit testing basics