dotnet-testing-fluentvalidation-testing

FluentValidation 驗證器測試指南

為什麼要測試驗證器？

驗證器是應用程式的第一道防線，測試驗證器能：

1. 確保資料完整性 - 防止無效資料進入系統
2. 業務規則文件化 - 測試即活文件，清楚展示業務規則
3. 安全性保障 - 防止惡意或不當資料輸入
4. 重構安全網 - 業務規則變更時提供保障
5. 跨欄位邏輯驗證 - 確保複雜邏輯正確運作

前置需求

套件安裝

<PackageReference Include="FluentValidation" Version="12.1.1" />
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.4.0" />
<PackageReference Include="NSubstitute" Version="5.3.0" />
<PackageReference Include="AwesomeAssertions" Version="9.4.0" />

注意：FluentValidation.TestHelper 命名空間（TestValidate、ShouldHaveValidationErrorFor 等 API）已包含在 FluentValidation 主套件中，不需要額外安裝獨立套件。只需 using FluentValidation.TestHelper; 即可使用。

FluentValidation 12.x 注意事項：FluentValidation 12.0 為主要版本升級，最低需求為 .NET 8。已移除的 API 包括 Transform/TransformForEach（改用 Must + 手動轉換）、InjectValidator（改用建構子注入 + SetValidator）、CascadeMode.StopOnFirstFailure（改用 RuleLevelCascadeMode = CascadeMode.Stop）。ShouldHaveAnyValidationError 已更名為 ShouldHaveValidationErrors。完整遷移指南請參閱 FluentValidation 12.0 Upgrade Guide。

基本 using 指令

using FluentValidation;
using FluentValidation.TestHelper;
using Microsoft.Extensions.Time.Testing;
using NSubstitute;
using Xunit;
using AwesomeAssertions;

核心測試模式

本節涵蓋 7 種核心測試模式，每種模式包含驗證器定義與完整測試範例。

完整程式碼範例請參考 references/core-test-patterns.md

• 模式 1：基本欄位驗證 — 使用 TestValidate + ShouldHaveValidationErrorFor / ShouldNotHaveValidationErrorFor 測試單一欄位規則
• 模式 2：參數化測試 — 使用 [Theory] + [InlineData] 測試多種無效/有效輸入組合
• 模式 3：跨欄位驗證 — 密碼確認、自訂 Must() 規則等多欄位關聯驗證
• 模式 4：時間相依驗證 — 注入 TimeProvider，搭配 FakeTimeProvider 控制時間進行測試
• 模式 5：條件式驗證 — 使用 .When() 的可選欄位驗證，測試條件觸發與跳過情境
• 模式 6：非同步驗證 — MustAsync + TestValidateAsync，搭配 NSubstitute Mock 外部服務
• 模式 7：集合驗證 — 驗證集合非空與元素有效性

快速範例：基本欄位驗證

public class UserValidatorTests
{
    private readonly UserValidator _validator = new();

    [Fact]
    public void Validate_空白使用者名稱_應該驗證失敗()
    {
        var result = _validator.TestValidate(
            new UserRegistrationRequest { Username = "" });

        result.ShouldHaveValidationErrorFor(x => x.Username)
              .WithErrorMessage("使用者名稱不可為 null 或空白");
    }
}