dotnet-testing-autofixture-customization（dotnet 测试自动夹具定制）

AutoFixture 進階：自訂化測試資料生成策略

概述

本技能涵蓋 AutoFixture 的進階自訂化功能，讓您能根據業務需求精確控制測試資料的生成邏輯。

核心技術

1. DataAnnotations 整合：AutoFixture 自動識別 [StringLength]、[Range] 等驗證屬性
2. 屬性範圍控制：使用 .With() 配合 Random.Shared 動態產生隨機值
3. 自訂 ISpecimenBuilder：實作精確控制特定屬性的建構器
4. 優先順序管理：理解 Insert(0) vs Add() 的差異
5. 泛型化設計：建立支援多種數值型別的可重用建構器

安裝套件

<PackageReference Include="AutoFixture" Version="4.18.1" />
<PackageReference Include="AutoFixture.Xunit2" Version="4.18.1" />

DataAnnotations 自動整合

AutoFixture 能自動識別 System.ComponentModel.DataAnnotations 的驗證屬性：

public class Person
{
    public Guid Id { get; set; }
    [StringLength(10)]
    public string Name { get; set; } = string.Empty;
    [Range(10, 80)]
    public int Age { get; set; }
    public DateTime CreateTime { get; set; }
}

[Fact]
public void AutoFixture_應能識別DataAnnotations()
{
    var fixture = new Fixture();
    var person = fixture.Create<Person>();
    person.Name.Length.Should().Be(10);        // StringLength(10)
    person.Age.Should().BeInRange(10, 80);     // Range(10, 80)
}

使用.With() 控制屬性範圍

固定值 vs 動態值

// ❌ 固定值：只執行一次，所有物件相同值
.With(x => x.Age, Random.Shared.Next(30, 50))

// ✅ 動態值：每個物件都重新計算
.With(x => x.Age, () => Random.Shared.Next(30, 50))

Random.Shared 的優點

自訂 ISpecimenBuilder

涵蓋 RandomRangedDateTimeBuilder（精確控制特定 DateTime 屬性）、ImprovedRandomRangedNumericSequenceBuilder（改進版數值範圍建構器）、泛型化 NumericRangeBuilder<TValue>（支援 int/long/decimal/double/float 等多種型別），以及流暢介面擴充方法 AddRandomRange。每個建構器皆附完整實作與使用範例。

完整 ISpecimenBuilder 實作範例請參考 references/specimen-builder-examples.md

優先順序管理：Insert(0) vs Add()

AutoFixture 內建的 RangeAttributeRelay、NumericSequenceGenerator 可能比自訂建構器有更高優先順序：

// ❌ 可能失效：被內建建構器攔截
fixture.Customizations.Add(new MyNumericBuilder(30, 50, "Age"));

// ✅ 正確：確保最高優先順序
fixture.Customizations.Insert(0, new MyNumericBuilder(30, 50, "Age"));

int vs DateTime 處理差異

最佳實踐

應該做

1. 善用 DataAnnotations — 充分利用現有模型驗證規則，AutoFixture 自動產生符合限制的資料
2. 使用 Random.Shared — 避免重複值問題，執行緒安全、效能更好
3. Insert(0) 確保優先順序 — 自訂數值建構器務必用 Insert(0)
4. 泛型化設計 — 建立可重用的泛型建構器，使用擴充方法提供流暢介面

應該避免

1. 忽略建構器優先順序 — 不要假設 Add() 一定生效
2. 過度複雜的邏輯 — 建構器保持單一職責
3. 使用 new Random() — 可能產生重複值，非執行緒安全

程式碼範本

請參考 templates 資料夾中的範例檔案：

• dataannotations-integration.cs - DataAnnotations 自動整合
• custom-specimen-builders.cs - 自訂 ISpecimenBuilder 實作
• numeric-range-extensions.cs - 泛型化數值範圍建構器與擴充方法

與其他技能的關係

• autofixture-basics：本技能的前置知識，需先掌握基礎用法
• autodata-xunit-integration：下一步學習目標，將自訂化與 xUnit 整合
• autofixture-nsubstitute-integration：進階整合，結合 Mock 與自訂資料生成

輸出格式

• 產生自訂 ISpecimenBuilder 實作類別
• 產生 ICustomization 組合類別
• 提供 fixture.Customizations.Insert(0,...) 設定範例
• 包含 DataAnnotations 整合與泛型化建構器程式碼

參考資源

原始文章

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

• Day 11 - AutoFixture 進階：自訂化測試資料生成策略

- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10375153 - 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day11

官方文件

• AutoFixture GitHub
• AutoFixture 官方文件
• ISpecimenBuilder 介面