TUnit 新世代測試框架入門基礎

TUnit 框架核心特色

1. Source Generator 驅動的測試發現

TUnit 與傳統測試框架最大的差異在於使用 Source Generator 在編譯時期完成測試發現，避免反射成本、完全支援 Native AOT、更快的啟動時間。

// TUnit 在編譯時期就透過 Source Generator 產生測試註冊程式碼
public class ModernTests
{
    [Test] // 編譯時期就被處理和最佳化
    public async Task TestMethod()
    {
        await Assert.That(true).IsTrue();
    }
}

2. AOT (Ahead-of-Time) 編譯支援

傳統 JIT：C# 原始碼 → IL 中間碼 → 執行時期 JIT 編譯 → 機器碼 → 執行
AOT：    C# 原始碼 → 編譯時期直接產生 → 機器碼 → 直接執行

AOT 優勢：超快啟動時間、更小的記憶體占用、可預測的效能、更適合容器化部署。大型專案可達 10-30 倍啟動時間改善。

3. Microsoft.Testing.Platform 採用

TUnit 建構在微軟最新的 Microsoft.Testing.Platform 之上，而非傳統的 VSTest 平台。

重要注意事項： TUnit 專案不需要也不應該安裝 Microsoft.NET.Test.Sdk 套件。

4. 預設並行執行

TUnit 將並行執行設為預設，需要時可用 [NotInParallel("GroupName")] 控制特定測試群組依序執行。

TUnit 專案建立

支援手動建立（console 模板 + TUnit 套件）或使用 TUnit Template（dotnet new tunit，推薦）。專案需設定 csproj（TUnit 套件、IsTestProject）與 GlobalUsings.cs。所有測試方法必須是非同步的（async Task）。

完整專案建立步驟與 csproj 範例請參閱 references/project-setup.md

測試屬性與參數化

基本測試 [Test]

TUnit 統一使用 [Test] 屬性，不像 xUnit 區分 [Fact] 和 [Theory]：

[Test]
public async Task Add_輸入1和2_應回傳3()
{
    var calculator = new Calculator();
    var result = calculator.Add(1, 2);
    await Assert.That(result).IsEqualTo(3);
}

參數化測試 [Arguments]

[Test]
[Arguments(1, 2, 3)]
[Arguments(-1, 1, 0)]
[Arguments(0, 0, 0)]
public async Task Add_多組輸入_應回傳正確結果(int a, int b, int expected)
{
    var calculator = new Calculator();
    var result = calculator.Add(a, b);
    await Assert.That(result).IsEqualTo(expected);
}

decimal 不是 attribute 常數型別，[Arguments(1.5m)] 會編譯失敗（CS0182）。 TUnit 0.60.15 起會把 double 或 string 常值自動轉成 decimal 參數：參數宣告為 decimal，寫 [Arguments(1.5)] 或 [Arguments("19.99")] 即可。更早的版本不支援這個轉換，請改用 [MethodDataSource] 提供 decimal 值。

TUnit.Assertions 斷言系統

TUnit 採用流暢式（Fluent）斷言設計，所有斷言都是非同步的。支援相等性、布林值、數值比較、字串、集合、例外等多種斷言，並可透過 And / Or 組合條件。

await Assert.That(actual).IsEqualTo(expected);
await Assert.That(email).Contains("@").And.EndsWith(".com");
await Assert.That(() => action()).Throws<InvalidOperationException>();

完整斷言類型與範例請參閱 references/tunit-assertions-detail.md

測試生命週期管理

TUnit 支援建構式 / Dispose 模式，以及 [Before(Test)]、[Before(Class)]、[After(Test)]、[After(Class)] 等屬性。

執行順序：Before(Class) → 建構式 → Before(Test) → 測試方法 → After(Test) → Dispose → After(Class)

完整生命週期範例與屬性對照表請參閱 references/lifecycle-management.md

並行執行控制與 xUnit 遷移

TUnit 預設並行執行所有測試，使用 [NotInParallel] 控制特定群組依序執行。提供完整的 xUnit → TUnit 語法對照表、遷移範例、CLI 執行指令與 IDE 整合設定。

完整並行控制、語法對照與遷移範例請參閱 references/xunit-migration.md

效能比較

場景	xUnit	TUnit	TUnit AOT	效能提升
簡單測試執行	1,400ms	1,000ms	60ms	23x (AOT)
非同步測試	1,400ms	930ms	26ms	54x (AOT)
並行測試	1,425ms	999ms	54ms	26x (AOT)

常見問題與解決方案

套件相容性 — 移除 Microsoft.NET.Test.Sdk，TUnit 使用新的測試平台
IDE 整合問題 — 確認 IDE 版本支援 Microsoft.Testing.Platform，啟用相關預覽功能
非同步斷言遺忘 — 所有斷言都需要 await，測試方法必須是 async Task

適用場景評估

適合使用 TUnit

全新專案：沒有歷史包袱
效能要求高：大型測試套件（1000+ 測試）
技術棧先進：使用 .NET 8+，計劃採用 AOT
CI/CD 重度使用：測試執行時間直接影響部署頻率
容器化部署：快速啟動時間很重要

暫時不建議

Legacy 專案：已有大量 xUnit 測試
保守團隊：需要穩定性勝過創新性
複雜測試生態：大量使用 xUnit 特定套件
舊版 .NET：還在 .NET 6/7

輸出格式

產生 TUnit 測試類別（含 [Test]、[Arguments] 屬性）
產生 .csproj 設定（TUnit 套件參考）
提供 GlobalUsings.cs 設定
包含 xUnit 到 TUnit 的遷移程式碼對照

參考資源

範例檔案

templates/basic-test-examples.cs - [Test] 屬性、非同步斷言與參數化測試的入門範例
templates/assertion-examples.cs - TUnit 斷言系統的完整範例，涵蓋各種斷言類型
templates/lifecycle-examples.cs - Before/After 屬性與建構式／Dispose 模式，含執行順序示範
templates/GlobalUsings.cs - TUnit 專案的全域 using 設定
templates/tunit-project.csproj - 專案設定（net9.0、TUnit 1.24.0）。走 Microsoft.Testing.Platform，刻意不安裝 Microsoft.NET.Test.Sdk
templates/xunit-migration-guide.md - xUnit 與 TUnit 的語法對照，供遷移評估使用

原始文章

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

Day 28 - TUnit 入門 - 下世代 .NET 測試框架探索
- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10377828
- 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day28

dotnet-testing-advanced-tunit-fundamentals

SKILL.mdskills/dotnet-testing-advanced-tunit-fundamentals/SKILL.md