Dotnet Testing Advanced Xunit Upgrade Guide
Published by kevintsengtw in dotnet-testing-agent-skills
What this skill does
|
Add Dotnet Testing Advanced Xunit Upgrade Guide to your agent
Review the source and files first. When you are ready, copy the prompt instruction or use the CLI command supported by your environment.
Install with a prompt
Paste this into a compatible coding agent:
add this skill "dotnet-testing-advanced-xunit-upgrade-guide" from https://github.com/kevintsengtw/dotnet-testing-agent-skillsInstall with the CLI
Run this command in a controlled environment after reviewing the repository:
npx skills add https://github.com/kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-advanced-xunit-upgrade-guideSkill instructions
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 設定檔
參考資源
範例檔案
- templates/upgrade-checklist.md - 升級檢查清單,從升級前準備到完成後驗證的勾選式表單
- templates/code-migration-examples.cs - 各項破壞性變更的前後對照(
async void、IAsyncLifetime、SkippableFact) - templates/new-features-examples.cs - v3 新功能範例:
[Test]、Explicit Tests、動態 Skip、Matrix Theory Data、Assembly Fixture - templates/xunit-v3-project.csproj - 升級後的專案設定(net8.0、
xunit.v33.2.2、OutputType=Exe、AwesomeAssertions 9.4.0) - templates/xunit.runner.json - v3 的 runner 設定(
parallelAlgorithm、maxParallelThreads、methodDisplay等)
原始文章
本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章:
- Day 26 - xUnit 升級指南:從 2.9.x 到 3.x 的轉換
官方文件
相關技能
dotnet-testing-xunit-project-setup- xUnit 專案設定基礎dotnet-testing-advanced-tunit-fundamentals- TUnit 替代框架dotnet-testing-advanced-testcontainers-database- Testcontainers 資料庫整合測試(搭配 XunitV3 套件)
Files included
- references/breaking-changes.md
- references/new-features.md
- references/upgrade-steps.md
- SKILL.md
- templates/code-migration-examples.cs
- templates/new-features-examples.cs
- templates/upgrade-checklist.md
- templates/xunit-v3-project.csproj
- templates/xunit.runner.json

