AutoFixture 與 Bogus 整合應用指南

核心概念

為什麼需要整合？

| 面向 | AutoFixture | Bogus | 整合方案 | | -------------- | ------------------------ | ------------------------ | ---------------- | | 資料真實感 | 低（GUID 格式字串） | 高（真實 Email/Phone） | 高 | | 物件關聯處理 | 自動 | 手動 | 自動 | | 循環參考處理 | 內建 | 無 | 整合 | | 設定複雜度 | 低 | 中 | 中 | | 適用場景 | 單元測試 | 整合測試/原型 | 兩者皆可 |

整合效果： user.Email 從 "Email1a2b3c4d" 變為 "john.doe@example.com"，其他屬性仍由 AutoFixture 自動填充。

套件安裝

<PackageReference Include="AutoFixture" Version="4.18.1" />
<PackageReference Include="AutoFixture.Xunit2" Version="4.18.1" />
<PackageReference Include="Bogus" Version="35.6.5" />
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="AwesomeAssertions" Version="9.4.0" />

整合方式總覽

| 整合方式 | 適用場景 | 複雜度 | | ---------------------------- | ------------------ | ------ | | 屬性層級 SpecimenBuilder | 特定屬性使用 Bogus | 低 | | 類型層級 SpecimenBuilder | 整個類型使用 Bogus | 中 | | 混合產生器 (HybridGenerator) | 統一 API 整合 | 中 | | 整合工廠 (IntegratedFactory) | 完整測試場景建構 | 高 | | 自訂 AutoData 屬性 | xUnit 整合 | 低 |

核心整合技術

ISpecimenBuilder 整合

透過 ISpecimenBuilder 介面實現屬性層級與類型層級的整合：

• 屬性層級：根據屬性名稱判斷（如 Email、Phone、FirstName），使用 Bogus 產生對應的真實感資料
• 類型層級：為整個類型（如 User、Address）註冊 Bogus Faker 產生器

常用 SpecimenBuilder

| SpecimenBuilder | 產生資料類型 | Bogus API | | ------------------------ | ------------------ | ------------------------ | | EmailSpecimenBuilder | Email 地址 | f.Internet.Email() | | PhoneSpecimenBuilder | 電話號碼 | f.Phone.PhoneNumber() | | NameSpecimenBuilder | 人名 | f.Name.FirstName() | | AddressSpecimenBuilder | 地址 | f.Address.FullAddress()|

擴充方法

• fixture.WithBogus() — 註冊所有 Bogus SpecimenBuilder
• fixture.WithOmitOnRecursion() — 處理循環參考
• fixture.WithSeed(seed) — 設定隨機種子
• fixture.WithRepeatCount(count) — 設定 CreateMany 預設數量

完整內容請參閱 references/core-integration-techniques.md

循環參考處理

當物件存在循環參考（如 User → Company → Employees(User)）時，使用 OmitOnRecursionBehavior 解決：

var fixture = new Fixture();
fixture.Behaviors.OfType<ThrowingRecursionBehavior>()
    .ToList()
    .ForEach(b => fixture.Behaviors.Remove(b));
fixture.Behaviors.Add(new OmitOnRecursionBehavior());

效果： 避免 StackOverflowException，循環參考的屬性設為 null 或空集合。

自訂 AutoData 屬性

public class BogusAutoDataAttribute : AutoDataAttribute
{
    public BogusAutoDataAttribute()
        : base(() => new Fixture().WithBogus())
    {
    }
}

// 使用方式
[Theory]
[BogusAutoData]
public void 使用整合資料測試(User user, Address address)
{
    user.Email.Should().Contain("@");
    address.City.Should().NotBeNullOrEmpty();
}

混合產生器與測試資料工廠

HybridTestDataGenerator

統一的測試資料產生 API，實作 ITestDataGenerator 介面：

• Generate<T>() — 產生單一物件
• Generate<T>(int count) — 產生指定數量的集合
• Generate<T>(Action<T> configure) — 產生物件後進行自訂設定

IntegratedTestDataFactory

完整場景建構工廠，支援進階功能：

• CreateFresh<T>() — 每次產生全新物件
• CreateMany<T>(count) — 批次建立
• GetCached<T>() — 快取機制，相同類型只產生一次
• CreateTestScenario() — 建立包含 Company、Users、Orders 的完整測試場景，自動建立關聯

TestBase 基底類別

統一 Fixture、Generator、Factory 的初始化與 Seed 管理，提供 Create<T>()、CreateMany<T>()、Create<T>(configure) 等便捷方法。

完整程式碼範例請參考 references/hybrid-generator-and-factory.md

Seed 管理與可重現性

重要限制

由於 AutoFixture 和 Bogus 有不同的隨機數管理機制：

• Seed 確保測試行為穩定性
• Seed 確保資料格式一致性
• 無法保證所有屬性值完全相同

建議做法

• 一般場景：使用 IntegratedTestDataFactory(seed: 12345) 確保穩定性
• 完全可重現：使用單一工具，如 Faker<User>().UseSeed(12345)
• 不需重現：不設定 Seed，每次產生不同的隨機資料

常見問題

Q1: 什麼時候該用整合方案，什麼時候用單一工具？

• 用整合方案：需要真實感資料（Email、Phone）且物件結構複雜的測試場景
• 用純 AutoFixture：只需要匿名資料填充的單元測試
• 用純 Bogus：需要完全可重現且資料格式嚴格的整合測試

Q2: SpecimenBuilder 匹配優先順序？

AutoFixture 按照 Customizations 集合的順序匹配，先加入的 Builder 優先。使用 fixture.Customizations.Insert(0, builder) 可確保最高優先。

Q3: 如何為新的實體類型加入 Bogus 支援？

1. 建立對應的 ISpecimenBuilder 實作
2. 在 Create() 方法中判斷屬性名稱或類型
3. 使用 Bogus Faker 產生對應的真實感資料
4. 在 WithBogus() 擴充方法中註冊

最佳實踐

建議做法

1. 永遠先處理循環參考 — fixture.WithOmitOnRecursion().WithBogus()
2. 為常用實體建立專用 SpecimenBuilder
3. 使用 Seed 確保測試穩定性
4. 建立測試基底類別統一資料產生邏輯
5. 適當使用快取提升效能

避免事項

1. 過度設計，保持簡單實用
2. 期望整合環境完全可重現
3. 忽略循環參考處理
4. 在每個測試中重新建立 Fixture

輸出格式

• 產生 ISpecimenBuilder 實作類別檔案（如 EmailSpecimenBuilder.cs）
• 產生 Fixture 擴充方法類別檔案（FixtureBogusExtensions.cs）
• 產生整合測試資料工廠或混合產生器類別
• 產生 BogusAutoDataAttribute 供 xUnit Theory 測試使用
• 搭配 OmitOnRecursionBehavior 處理循環參考

參考資源

範例檔案

• templates/specimen-builders.cs - 透過 ISpecimenBuilder 把 Bogus 接進 AutoFixture 的實作範例
• templates/hybrid-generator.cs - HybridTestDataGenerator 混合產生器、FixtureExtensions 擴充方法，以及在地化與 seed 版的自訂 AutoData 屬性
• templates/integrated-factory.cs - IntegratedTestDataFactory 整合工廠與完整測試情境，示範測試資料的生命週期管理

原始文章

• Day 15 - AutoFixture 與 Bogus 整合：結合兩者優勢
  • 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10375620
  • 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day15

官方文件

• AutoFixture GitHub
• Bogus GitHub Repository

相關技能

• autofixture-basics - AutoFixture 基礎使用
• autofixture-customization - AutoFixture 自訂化策略
• autodata-xunit-integration - AutoData 屬性整合
• bogus-fake-data - Bogus 假資料產生器