xUnit 升級指南：從 2.9.x 到 3.x
核心概念
套件命名變革
xUnit v3 採用全新的套件命名策略：
| v1~v2 套件名稱 | v3 套件名稱 | 說明 |
|---|---|---|
xunit | xunit.v3 | 主要測試框架 |
xunit.assert | xunit.v3.assert | 斷言函式庫 |
xunit.core | xunit.v3.core | 核心元件 |
xunit.abstractions | (移除) | 不再需要 |
xunit.runner.visualstudio | xunit.runner.visualstudio (3.x.y) | 測試執行器 |
重要：使用 xunit.v3 套件名稱，不是 xunit。
最低運行時需求
- .NET Framework 4.7.2+ 或 .NET 8.0+ (推薦)
- 不支援：.NET Core 3.1、.NET 5/6/7
破壞性變更
涵蓋 OutputType 改為 Exe、async void 不再支援、IAsyncLifetime 繼承 IAsyncDisposable、SkippableFact 移除、僅支援 SDK-style 專案、自訂 DataAttribute 簽名變更等六項破壞性變更，每項皆附修正前後的程式碼對照。
完整破壞性變更清單與程式碼範例請參考 references/breaking-changes.md
升級步驟
五步驟 SOP：建立升級分支 → 更新專案檔案（套件、OutputType）→ 修正 async void → 更新 using → 編譯與測試。另含.NET 10 SDK MTP 模式遷移指南（global.json 設定、CLI 用法變更、VSTest 遷移步驟）。
完整升級步驟與.NET 10 MTP 模式指南請參考 references/upgrade-steps.md
xUnit 3.x 新功能
涵蓋 Assert.Skip / SkipUnless / SkipWhen 動態跳過、Explicit Tests、[Test] 屬性、MatrixTheoryData 矩陣測試、Assembly Fixtures、Test Pipeline Startup、多格式測試報告等新功能，每項皆附完整程式碼範例。
完整新功能範例請參考 references/new-features.md
Testcontainers.XunitV3 整合套件
Testcontainers 官方推出 Testcontainers.XunitV3（4.9.0），專為 xUnit v3 設計的整合套件，自動管理容器的建立與銷毀，取代手動實作 IAsyncLifetime 的方式。
<PackageReference Include="Testcontainers.XunitV3" Version="4.9.0" />若專案同時使用 Testcontainers 與 xUnit v3，建議採用此套件簡化容器生命週期管理。
xunit.runner.json 設定
{
"$schema": "https://xunit.net/schema/v3/xunit.runner.schema.json",
"parallelAlgorithm": "conservative",
"maxParallelThreads": 4,
"diagnosticMessages": true,
"internalDiagnosticMessages": false,
"methodDisplay": "classAndMethod",
"preEnumerateTheories": true,
"stopOnFail": false
}常見問題與解決方案
問題 1：找不到 xunit.abstractions
移除 using Xunit.Abstractions;，相關類型已移到 Xunit 命名空間。
問題 2：IDE 無法發現測試
確認 IDE 版本：Visual Studio 2022 17.8+、Rider 2023.3+、VS Code 最新版。如仍有問題，可暫時停用 MTP：
<PropertyGroup>
<EnableMicrosoftTestingPlatform>false</EnableMicrosoftTestingPlatform>
</PropertyGroup>.NET 10 SDK 注意：若使用 MTP 模式，停用 MTP 會導致dotnet test錯誤。應改為移除global.json中的test區段。
升級檢查清單
升級前
- 確認目標框架版本 (.NET 8+ 或.NET Framework 4.7.2+)
- 檢查專案檔案格式 (SDK-style)
- 識別所有 async void 測試方法
- 檢查 IAsyncLifetime 實作
- 評估相依套件相容性
- 建立備份分支
升級過程
- 更新套件參考 (使用
xunit.v3) - 移除
xunit.abstractions參考 - 修改 OutputType 為 Exe
- 修正所有 async void 測試方法
- 更新 using 陳述式
- 重構自訂屬性 (如有)
- 驗證編譯成功
- 執行所有測試
升級後驗證
- 功能完整性測試
- 效能基準比較
- CI/CD Pipeline 驗證
- 文檔更新
- 團隊培訓
- （.NET 10+）設定
global.json啟用 MTP 模式並驗證dotnet test正常運作
IDE 與工具支援
| IDE | 最低版本 |
|---|---|
| Visual Studio | 2022 17.8+ |
| VS Code | 最新版 |
| Rider | 2023.3+ |
xUnit 3.x 預設啟用 Microsoft Testing Platform（MTP），搭配.NET 10 SDK 可使用原生 MTP 模式。
.NET 10 MTP 模式詳細設定請參考 references/upgrade-steps.md
輸出格式
- 產生升級後的測試專案.csproj 設定（xunit.v3 套件、OutputType Exe）
- 包含 async void 修正為 async Task 的測試程式碼
- 包含 IAsyncLifetime 調整與 SkippableFact 替換範例
- 產生 xunit.runner.json 設定檔
參考資源
原始文章
本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
- Day 26 - xUnit 升級指南：從 2.9.x 到 3.x 的轉換
- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10377477 - 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day26
官方文件
相關技能
dotnet-testing-xunit-project-setup- xUnit 專案設定基礎dotnet-testing-advanced-tunit-fundamentals- TUnit 替代框架dotnet-testing-advanced-testcontainers-database- Testcontainers 資料庫整合測試（搭配 XunitV3 套件）