Dotnet Testing Advanced Xunit Upgrade Guide

Published by kevintsengtw in dotnet-testing-agent-skills

No known issues31 installs

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-skills

Install 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-guide

Skill instructions

xUnit 升級指南:從 2.9.x 到 3.x

核心概念

套件命名變革

xUnit v3 採用全新的套件命名策略:

v1~v2 套件名稱v3 套件名稱說明
xunitxunit.v3主要測試框架
xunit.assertxunit.v3.assert斷言函式庫
xunit.corexunit.v3.core核心元件
xunit.abstractions(移除)不再需要
xunit.runner.visualstudioxunit.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 Studio2022 17.8+
VS Code最新版
Rider2023.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 天挑戰」系列文章:

官方文件

相關技能

  • 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

More skills

Dotnet Testing Advanced Xunit Upgrade Guide: Install and Security