複雜物件比對指南（Complex Object Comparison）

適用情境

此技能專注於 .NET 測試中的複雜物件比對場景，使用 AwesomeAssertions 的 BeEquivalentTo API 處理各種進階比對需求。

核心使用場景

1. 深層物件結構比對 (Object Graph Comparison)

當需要比對包含多層巢狀屬性的複雜物件時：

[Fact]
public void ComplexObject_深層結構比對_應完全相符()
{
    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);

    // 深層物件比對
    actual.Should().BeEquivalentTo(expected);
}

2. 循環參照處理 (Circular Reference Handling)

處理物件之間存在循環參照的情況：

[Fact]
public void TreeStructure_循環參照_應正確處理()
{
    // 建立具有父子雙向參照的樹狀結構
    var parent = new TreeNode { Value = "Root" };
    var child1 = new TreeNode { Value = "Child1", Parent = parent };
    var child2 = new TreeNode { Value = "Child2", Parent = parent };
    parent.Children = new[] { child1, child2 };

    var actualTree = treeService.GetTree("Root");

    // 處理循環參照
    actualTree.Should().BeEquivalentTo(parent, options =>
        options.IgnoringCyclicReferences()
               .WithMaxRecursionDepth(10)
    );
}

3-6. 進階比對模式

FluentAssertions 還提供多種進階比對模式：動態欄位排除（排除時間戳記、自動生成欄位）、巢狀物件欄位排除、大量資料效能最佳化比對（選擇性屬性比對、抽樣驗證策略）、以及嚴格/寬鬆排序控制。

📖 完整程式碼範例請參閱 references/detailed-comparison-patterns.md

比對選項速查表

常見比對模式與解決方案

模式 1：Entity Framework 實體比對

[Fact]
public void EFEntity_資料庫實體_應排除導航屬性()
{
    var expected = new Product { Id = 1, Name = "Laptop", Price = 999 };
    var actual = dbContext.Products.Find(1);

    actual.Should().BeEquivalentTo(expected, options =>
        options.ExcludingMissingMembers()  // 排除 EF 追蹤屬性
               .Excluding(p => p.CreatedAt)
               .Excluding(p => p.UpdatedAt)
    );
}

模式 2：API Response 比對

[Fact]
public void ApiResponse_JSON反序列化_應忽略額外欄位()
{
    var expected = new UserDto 
    { 
        Id = 1, 
        Username = "john_doe" 
    };

    var response = await httpClient.GetAsync("/api/users/1");
    var actual = await response.Content.ReadFromJsonAsync<UserDto>();

    actual.Should().BeEquivalentTo(expected, options =>
        options.ExcludingMissingMembers()  // 忽略 API 額外欄位
    );
}

模式 3：測試資料建構器比對

[Fact]
public void Builder_測試資料_應匹配預期結構()
{
    var expected = new OrderBuilder()
        .WithId(1)
        .WithCustomer("John Doe")
        .WithItems(3)
        .Build();

    var actual = orderService.CreateOrder(orderRequest);

    actual.Should().BeEquivalentTo(expected, options =>
        options.Excluding(o => o.OrderNumber)  // 系統生成
               .Excluding(o => o.CreatedAt)
    );
}

錯誤訊息最佳化

提供有意義的錯誤訊息

[Fact]
public void Comparison_錯誤訊息_應清楚說明差異()
{
    var expected = new User { Name = "John", Age = 30 };
    var actual = userService.GetUser(1);

    // 使用 because 參數提供上下文
    actual.Should().BeEquivalentTo(expected, options =>
        options.Excluding(u => u.Id)
               .Because("ID 是系統自動生成的，不應納入比對")
    );
}

使用 AssertionScope 進行批次驗證

[Fact]
public void MultipleComparisons_批次驗證_應一次顯示所有失敗()
{
    var users = userService.GetAllUsers();

    using (new AssertionScope())
    {
        foreach (var user in users)
        {
            user.Id.Should().BeGreaterThan(0);
            user.Name.Should().NotBeNullOrEmpty();
            user.Email.Should().MatchRegex(@"^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$");
        }
    }
    // 所有失敗會一起報告，而非遇到第一個失敗就停止
}

與其他技能整合

此技能可與以下技能組合使用：

• awesome-assertions-guide: 基礎斷言語法與常用 API
• autofixture-data-generation: 自動生成測試資料
• test-data-builder-pattern: 建構複雜測試物件
• unit-test-fundamentals: 單元測試基礎與 3A 模式

最佳實踐建議

✅ 推薦做法

1. 優先使用屬性排除而非包含：除非只需驗證少數屬性，否則使用 Excluding 更清楚
2. 建立可重用的排除擴充方法：避免在每個測試重複排除邏輯
3. 為大量資料比對設定合理策略：平衡效能與驗證完整性
4. 使用 AssertionScope 進行批次驗證：一次看到所有失敗原因
5. 提供有意義的 because 說明：幫助未來維護者理解測試意圖

❌ 避免做法

1. 避免過度依賴完整物件比對：考慮只驗證關鍵屬性
2. 避免忽略循環參照問題：使用 IgnoringCyclicReferences() 明確處理
3. 避免在每個測試重複排除邏輯：提取為擴充方法
4. 避免對大量資料做完整深度比對：使用抽樣或關鍵屬性驗證

疑難排解

Q1: BeEquivalentTo 效能很慢怎麼辦？

A: 使用以下策略優化：

• 使用 Including 只比對關鍵屬性
• 對大量資料採用抽樣驗證
• 使用 WithMaxRecursionDepth 限制遞迴深度
• 考慮使用 AssertKeyPropertiesOnly 快速比對關鍵欄位

Q2: 如何處理 StackOverflowException？

A: 通常由循環參照引起：

options.IgnoringCyclicReferences()
       .WithMaxRecursionDepth(10)

Q3: 如何排除所有時間相關欄位？

A: 使用路徑模式匹配：

options.Excluding(ctx => ctx.Path.EndsWith("At"))
       .Excluding(ctx => ctx.Path.EndsWith("Time"))
       .Excluding(ctx => ctx.Path.Contains("Timestamp"))

Q4: 比對失敗但看不出差異？

A: 啟用詳細追蹤：

options.WithTracing()  // 產生詳細的比對追蹤資訊

範本檔案參考

本技能提供以下範本檔案：

• templates/comparison-patterns.cs: 常見比對模式範例
• templates/exclusion-strategies.cs: 欄位排除策略與擴充方法

參考資源

原始文章

本技能內容提煉自「老派軟體工程師的測試修練 – 30 天挑戰」系列文章：

• Day 05 – AwesomeAssertions 進階技巧與複雜情境應用
  • 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10374425
  • 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day05

官方文件

• AwesomeAssertions GitHub
• AwesomeAssertions Documentation

相關技能

• awesome-assertions-guide – AwesomeAssertions 基礎與進階用法
• unit-test-fundamentals – 單元測試基礎