dotnet-testing-advanced-xunit-upgrade-guide

Name: dotnet-testing-advanced-xunit-upgrade-guide
Author: kevintsengtw

28stars4forks

How to install dotnet-testing-advanced-xunit-upgrade-guide?

kevintsengtw/dotnet-testing-agent-skills/dotnet-testing-advanced-xunit-upgrade-guide

$npx -y skills add kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-advanced-xunit-upgrade-guide

Installs into the current project.

Summary

xUnit 2.9.x 到 3.x 升級完整指南。當需要將 xUnit v2 升級至 v3 或了解 xUnit v3 新功能與破壞性變更時使用。涵蓋套件更新、async void 修正、IAsyncLifetime 調整。包含新功能介紹: Assert.Skip、Explicit Tests、Matrix Theory、Assembly Fixtures。 Make sure to use this skill whenever the user mentions xUnit upgrade, xUnit v3, xUnit migration, xUn

Files · 1

View on GitHub

SKILL.md

1	# xUnit 升級指南：從 2.9.x 到 3.x
2
3	## 核心概念
4
5	### 套件命名變革
6
7	xUnit v3 採用全新的套件命名策略：
8
9	\| v1~v2 套件名稱 \| v3 套件名稱 \| 說明 \|
10	\| --------------------------- \| ----------------------------------- \| ------------ \|
11	\| `xunit` \| `xunit.v3` \| 主要測試框架 \|
12	\| `xunit.assert` \| `xunit.v3.assert` \| 斷言函式庫 \|
13	\| `xunit.core` \| `xunit.v3.core` \| 核心元件 \|
14	\| `xunit.abstractions` \| (移除) \| 不再需要 \|
15	\| `xunit.runner.visualstudio` \| `xunit.runner.visualstudio` (3.x.y) \| 測試執行器 \|
16
17	重要：使用 `xunit.v3` 套件名稱，不是 `xunit`。
18
19	### 最低運行時需求
20
21	- .NET Framework 4.7.2+ 或 .NET 8.0+ (推薦)
22	- 不支援：.NET Core 3.1、.NET 5/6/7
23
24	---
25
26	## 破壞性變更
27
28	涵蓋 OutputType 改為 Exe、async void 不再支援、IAsyncLifetime 繼承 IAsyncDisposable、SkippableFact 移除、僅支援 SDK-style 專案、自訂 DataAttribute 簽名變更等六項破壞性變更，每項皆附修正前後的程式碼對照。
29
30	> 完整破壞性變更清單與程式碼範例請參考 [references/breaking-changes.md](references/breaking-changes.md)
31
32	---
33
34	## 升級步驟
35
36	五步驟 SOP：建立升級分支 → 更新專案檔案（套件、OutputType）→ 修正 async void → 更新 using → 編譯與測試。另含 .NET 10 SDK MTP 模式遷移指南（global.json 設定、CLI 用法變更、VSTest 遷移步驟）。
37
38	> 完整升級步驟與 .NET 10 MTP 模式指南請參考 [references/upgrade-steps.md](references/upgrade-steps.md)
39
40	---
41
42	## xUnit 3.x 新功能
43
44	涵蓋 Assert.Skip / SkipUnless / SkipWhen 動態跳過、Explicit Tests、[Test] 屬性、MatrixTheoryData 矩陣測試、Assembly Fixtures、Test Pipeline Startup、多格式測試報告等新功能，每項皆附完整程式碼範例。
45
46	> 完整新功能範例請參考 [references/new-features.md](references/new-features.md)
47
48	### Testcontainers.XunitV3 整合套件
49
50	Testcontainers 官方推出 `Testcontainers.XunitV3`（4.9.0），專為 xUnit v3 設計的整合套件，自動管理容器的建立與銷毀，取代手動實作 `IAsyncLifetime` 的方式。
51
52	```xml
53	<PackageReference Include="Testcontainers.XunitV3" Version="4.9.0" />
54	```
55
56	> 若專案同時使用 Testcontainers 與 xUnit v3，建議採用此套件簡化容器生命週期管理。
57
58	---
59
60	## xunit.runner.json 設定
61
62	```json
63	{
64	"$schema": "https://xunit.net/schema/v3/xunit.runner.schema.json",
65	"parallelAlgorithm": "conservative",
66	"maxParallelThreads": 4,
67	"diagnosticMessages": true,
68	"internalDiagnosticMessages": false,
69	"methodDisplay": "classAndMethod",
70	"preEnumerateTheories": true,
71	"stopOnFail": false
72	}
73	```
74
75	---
76
77	## 常見問題與解決方案
78
79	### 問題 1：找不到 xunit.abstractions
80
81	移除 `using Xunit.Abstractions;`，相關類型已移到 `Xunit` 命名空間。
82
83	### 問題 2：IDE 無法發現測試
84
85	確認 IDE 版本：Visual Studio 2022 17.8+、Rider 2023.3+、VS Code 最新版。如仍有問題，可暫時停用 MTP：
86
87	```xml
88	<PropertyGroup>
89	<EnableMicrosoftTestingPlatform>false</EnableMicrosoftTestingPlatform>
90	</PropertyGroup>
91	```
92
93	> .NET 10 SDK 注意：若使用 MTP 模式，停用 MTP 會導致 `dotnet test` 錯誤。應改為移除 `global.json` 中的 `test` 區段。
94
95	---
96
97	## 升級檢查清單
98
99	### 升級前
100
101	- [ ] 確認目標框架版本 (.NET 8+ 或 .NET Framework 4.7.2+)
102	- [ ] 檢查專案檔案格式 (SDK-style)
103	- [ ] 識別所有 async void 測試方法
104	- [ ] 檢查 IAsyncLifetime 實作
105	- [ ] 評估相依套件相容性
106	- [ ] 建立備份分支
107
108	### 升級過程
109
110	- [ ] 更新套件參考 (使用 `xunit.v3`)
111	- [ ] 移除 `xunit.abstractions` 參考
112	- [ ] 修改 OutputType 為 Exe
113	- [ ] 修正所有 async void 測試方法
114	- [ ] 更新 using 陳述式
115	- [ ] 重構自訂屬性 (如有)
116	- [ ] 驗證編譯成功
117	- [ ] 執行所有測試
118
119	### 升級後驗證
120
121	- [ ] 功能完整性測試
122	- [ ] 效能基準比較
123	- [ ] CI/CD Pipeline 驗證
124	- [ ] 文檔更新
125	- [ ] 團隊培訓
126	- [ ] （.NET 10+）設定 `global.json` 啟用 MTP 模式並驗證 `dotnet test` 正常運作
127
128	---
129
130	## IDE 與工具支援
131
132	\| IDE \| 最低版本 \|
133	\| ------------- \| ---------- \|
134	\| Visual Studio \| 2022 17.8+ \|
135	\| VS Code \| 最新版 \|
136	\| Rider \| 2023.3+ \|
137
138	xUnit 3.x 預設啟用 Microsoft Testing Platform（MTP），搭配 .NET 10 SDK 可使用原生 MTP 模式。
139
140	> .NET 10 MTP 模式詳細設定請參考 [references/upgrade-steps.md](references/upgrade-steps.md)
141
142	---
143
144	## 輸出格式
145
146	- 產生升級後的測試專案 .csproj 設定（xunit.v3 套件、OutputType Exe）
147	- 包含 async void 修正為 async Task 的測試程式碼
148	- 包含 IAsyncLifetime 調整與 SkippableFact 替換範例
149	- 產生 xunit.runner.json 設定檔
150
151	## 參考資源
152
153	### 原始文章
154
155	本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
156
157	- Day 26 - xUnit 升級指南：從 2.9.x 到 3.x 的轉換
158	- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10377477
159	- 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day26
160
161	### 官方文件
162
163	- [xUnit.net 官方網站](https://xunit.net/)
164	- [xUnit v3 新功能文件](https://xunit.net/docs/getting-started/v3/whats-new)
165	- [xUnit 2.x → 3.x 官方遷移指南](https://xunit.net/docs/getting-started/v3/migration)
166	- [xunit.v3 NuGet 套件](https://www.nuget.org/packages/xunit.v3)
167
168	### 相關技能
169
170	- `dotnet-testing-xunit-project-setup` - xUnit 專案設定基礎
171	- `dotnet-testing-advanced-tunit-fundamentals` - TUnit 替代框架
172	- `dotnet-testing-advanced-testcontainers-database` - Testcontainers 資料庫整合測試（搭配 XunitV3 套件）

People who liked this also viewed

6 picks

Type

dotnet-testing-advanced-xunit-upgrade-guide

28stars4forks

View on GitHub

How to install dotnet-testing-advanced-xunit-upgrade-guide?

kevintsengtw/dotnet-testing-agent-skills/dotnet-testing-advanced-xunit-upgrade-guide

$npx -y skills add kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-advanced-xunit-upgrade-guide

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# xUnit 升級指南：從 2.9.x 到 3.x
2
3	## 核心概念
4
5	### 套件命名變革
6
7	xUnit v3 採用全新的套件命名策略：
8
9	\| v1~v2 套件名稱 \| v3 套件名稱 \| 說明 \|
10	\| --------------------------- \| ----------------------------------- \| ------------ \|
11	\| `xunit` \| `xunit.v3` \| 主要測試框架 \|
12	\| `xunit.assert` \| `xunit.v3.assert` \| 斷言函式庫 \|
13	\| `xunit.core` \| `xunit.v3.core` \| 核心元件 \|
14	\| `xunit.abstractions` \| (移除) \| 不再需要 \|
15	\| `xunit.runner.visualstudio` \| `xunit.runner.visualstudio` (3.x.y) \| 測試執行器 \|
16
17	重要：使用 `xunit.v3` 套件名稱，不是 `xunit`。
18
19	### 最低運行時需求
20
21	- .NET Framework 4.7.2+ 或 .NET 8.0+ (推薦)
22	- 不支援：.NET Core 3.1、.NET 5/6/7
23
24	---
25
26	## 破壞性變更
27
28	涵蓋 OutputType 改為 Exe、async void 不再支援、IAsyncLifetime 繼承 IAsyncDisposable、SkippableFact 移除、僅支援 SDK-style 專案、自訂 DataAttribute 簽名變更等六項破壞性變更，每項皆附修正前後的程式碼對照。
29
30	> 完整破壞性變更清單與程式碼範例請參考 [references/breaking-changes.md](references/breaking-changes.md)
31
32	---
33
34	## 升級步驟
35
36	五步驟 SOP：建立升級分支 → 更新專案檔案（套件、OutputType）→ 修正 async void → 更新 using → 編譯與測試。另含 .NET 10 SDK MTP 模式遷移指南（global.json 設定、CLI 用法變更、VSTest 遷移步驟）。
37
38	> 完整升級步驟與 .NET 10 MTP 模式指南請參考 [references/upgrade-steps.md](references/upgrade-steps.md)
39
40	---
41
42	## xUnit 3.x 新功能
43
44	涵蓋 Assert.Skip / SkipUnless / SkipWhen 動態跳過、Explicit Tests、[Test] 屬性、MatrixTheoryData 矩陣測試、Assembly Fixtures、Test Pipeline Startup、多格式測試報告等新功能，每項皆附完整程式碼範例。
45
46	> 完整新功能範例請參考 [references/new-features.md](references/new-features.md)
47
48	### Testcontainers.XunitV3 整合套件
49
50	Testcontainers 官方推出 `Testcontainers.XunitV3`（4.9.0），專為 xUnit v3 設計的整合套件，自動管理容器的建立與銷毀，取代手動實作 `IAsyncLifetime` 的方式。
51
52	```xml
53	<PackageReference Include="Testcontainers.XunitV3" Version="4.9.0" />
54	```
55
56	> 若專案同時使用 Testcontainers 與 xUnit v3，建議採用此套件簡化容器生命週期管理。
57
58	---
59
60	## xunit.runner.json 設定
61
62	```json
63	{
64	"$schema": "https://xunit.net/schema/v3/xunit.runner.schema.json",
65	"parallelAlgorithm": "conservative",
66	"maxParallelThreads": 4,
67	"diagnosticMessages": true,
68	"internalDiagnosticMessages": false,
69	"methodDisplay": "classAndMethod",
70	"preEnumerateTheories": true,
71	"stopOnFail": false
72	}
73	```
74
75	---
76
77	## 常見問題與解決方案
78
79	### 問題 1：找不到 xunit.abstractions
80
81	移除 `using Xunit.Abstractions;`，相關類型已移到 `Xunit` 命名空間。
82
83	### 問題 2：IDE 無法發現測試
84
85	確認 IDE 版本：Visual Studio 2022 17.8+、Rider 2023.3+、VS Code 最新版。如仍有問題，可暫時停用 MTP：
86
87	```xml
88	<PropertyGroup>
89	<EnableMicrosoftTestingPlatform>false</EnableMicrosoftTestingPlatform>
90	</PropertyGroup>
91	```
92
93	> .NET 10 SDK 注意：若使用 MTP 模式，停用 MTP 會導致 `dotnet test` 錯誤。應改為移除 `global.json` 中的 `test` 區段。
94
95	---
96
97	## 升級檢查清單
98
99	### 升級前
100
101	- [ ] 確認目標框架版本 (.NET 8+ 或 .NET Framework 4.7.2+)
102	- [ ] 檢查專案檔案格式 (SDK-style)
103	- [ ] 識別所有 async void 測試方法
104	- [ ] 檢查 IAsyncLifetime 實作
105	- [ ] 評估相依套件相容性
106	- [ ] 建立備份分支
107
108	### 升級過程
109
110	- [ ] 更新套件參考 (使用 `xunit.v3`)
111	- [ ] 移除 `xunit.abstractions` 參考
112	- [ ] 修改 OutputType 為 Exe
113	- [ ] 修正所有 async void 測試方法
114	- [ ] 更新 using 陳述式
115	- [ ] 重構自訂屬性 (如有)
116	- [ ] 驗證編譯成功
117	- [ ] 執行所有測試
118
119	### 升級後驗證
120
121	- [ ] 功能完整性測試
122	- [ ] 效能基準比較
123	- [ ] CI/CD Pipeline 驗證
124	- [ ] 文檔更新
125	- [ ] 團隊培訓
126	- [ ] （.NET 10+）設定 `global.json` 啟用 MTP 模式並驗證 `dotnet test` 正常運作
127
128	---
129
130	## IDE 與工具支援
131
132	\| IDE \| 最低版本 \|
133	\| ------------- \| ---------- \|
134	\| Visual Studio \| 2022 17.8+ \|
135	\| VS Code \| 最新版 \|
136	\| Rider \| 2023.3+ \|
137
138	xUnit 3.x 預設啟用 Microsoft Testing Platform（MTP），搭配 .NET 10 SDK 可使用原生 MTP 模式。
139
140	> .NET 10 MTP 模式詳細設定請參考 [references/upgrade-steps.md](references/upgrade-steps.md)
141
142	---
143
144	## 輸出格式
145
146	- 產生升級後的測試專案 .csproj 設定（xunit.v3 套件、OutputType Exe）
147	- 包含 async void 修正為 async Task 的測試程式碼
148	- 包含 IAsyncLifetime 調整與 SkippableFact 替換範例
149	- 產生 xunit.runner.json 設定檔
150
151	## 參考資源
152
153	### 原始文章
154
155	本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
156
157	- Day 26 - xUnit 升級指南：從 2.9.x 到 3.x 的轉換
158	- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10377477
159	- 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day26
160
161	### 官方文件
162
163	- [xUnit.net 官方網站](https://xunit.net/)
164	- [xUnit v3 新功能文件](https://xunit.net/docs/getting-started/v3/whats-new)
165	- [xUnit 2.x → 3.x 官方遷移指南](https://xunit.net/docs/getting-started/v3/migration)
166	- [xunit.v3 NuGet 套件](https://www.nuget.org/packages/xunit.v3)
167
168	### 相關技能
169
170	- `dotnet-testing-xunit-project-setup` - xUnit 專案設定基礎
171	- `dotnet-testing-advanced-tunit-fundamentals` - TUnit 替代框架
172	- `dotnet-testing-advanced-testcontainers-database` - Testcontainers 資料庫整合測試（搭配 XunitV3 套件）

People who liked this also viewed

6 picks

Type