# xUnit升级指南：从2.9.x到3.x ## 适用于当被要求执行以下任务时，请使用此技能： * 将现有的 xUnit 2.x 测试专案升级到 xUnit 3.x * 评估xUnit升级的影响范围 * 解决xUnit升级过程中的编译错误 * 使用xUnit 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`。 ### 最低运行时需求 xUnit 3.x 的严格要求： * **.NET Framework 4.7.2+** 或 * **.NET 8.0+**（推荐） **不支持的版本**： * .NET核心3.1 * .NET 5、6、7 ** ** ## 破坏性变更清单 ### 1\. 专测试案变成了执行档 <属性组> <输出类型>库 <属性组> <输出类型>Exe ### 2\. async void 测试不再支持 // ❌ xUnit 2.x - 3.x 中会失败 [事实] public async void 测试某些非同步功能() { var 结果 = 等待 SomeAsyncMethod(); 断言.True(结果); } // ✅ xUnit 3.x - 正确写法 [事实] public async Task 测试某些非同步功能() { var 结果 = 等待 SomeAsyncMethod(); 断言.True(结果); } ### 3\. IAsyncLifetime 变更在 xUnit 3.x 中，`IAsyncLifetime` 继承 `IAsyncDisposable`。如果同时实现 `IAsyncLifetime` 和 `IDisposable`，只调用 `DisposeAsync`，不会调用 `Dispose`。 // ⚠️ 需要注意的模式公共类 MyTestClass ：IAsyncLifetime、IDisposable { 公共异步任务InitializeAsync() { /* ... */ } public async Task DisposeAsync() { /* 会被呼叫 */ } public void Dispose() { /* 在 3.x 中不会被呼叫 */ } } // ✅ 建议：将清理逻辑统一放在DisposeAsync 公共类 MyTestClass：IAsyncLifetime { public async Task InitializeAsync() { /* 初始化 */ } public async Task DisposeAsync() { /*所有清理逻辑 */ } } ### 4\. SkippableFact/SkippableTheory 删除 // ❌ xUnit 2.x - 已移除 [可跳过的事实] public void 可跳过的测试() { Skip.If(某个条件, "跳过原因"); // 测试逻辑 } // ✅ xUnit 3.x - 使用 Assert.Skip [事实] public void 可跳过的测试() { if (某个条件) { Assert.Skip("跳过原因"); } // 测试逻辑 } ### 5\. 仅支持SDK式专案检查专案档案起始是否为： <项目Sdk =“Microsoft.NET.Sdk”> 如果是传统格式，必须先转换为SDK风格。 ** ** ## 升级步骤 ###步骤1：建立升级分支 git checkout -b 功能/升级-xunit-v3 ###步骤2：更新专案文件 <项目Sdk =“Microsoft.NET.Sdk”> <属性组> net8.0 <输出类型>Exe 启用 <可空>启用假 true <项目组> 运行时；建造;本国的;内容文件；分析器 <私有资产>全部 ###步骤3：修改async void测试使用IDE搜索： async\s+void.*\[(事实|理论)\] 将所有 `async void` 改为 `async Task`。 ###步骤 4：使用演示式更新 // 删除（不再需要） // 使用 Xunit.Abstractions; // 保留使用 Xunit； ###步骤5：编译与测试点网清洁点网恢复点网构建 dotnet 测试 -- 详细程度正常 ** ** ## xUnit 3.x 新功能 ### 动态跳过测试 **声明式(SkipUnless/SkipWhen)** ： [事实（SkipUnless = nameof（IsWindowsEnvironment）， Skip = "此测试仅在 Windows 环境执行")] public void 只在Windows上执行的测试() { // 测试逻辑 } 公共静态 bool IsWindowsEnvironment => RuntimeInformation.IsOSPlatform(OSPlatform.Windows); **命令式(Assert.Skip)** ： [事实] public void 根据环境变数跳过的测试() { var enableTests = Environment.GetEnvironmentVariable("ENABLE_INTEGRATION_TESTS"); if (string.IsNullOrEmpty(enableTests) || enableTests.ToLower() != "true") { Assert.Skip("集成测试已失效。设置ENABLE_INTEGRATION_TESTS=true来执行"); } // 逻辑测试... } ### 显式测试（显式测试） [事实（明确 = true）] public void 昂贵的集成测试() { // 这个要求测试默认情况下不会执行，除非明确说明 // 适用于性能测试、长时间执行的测试 } ### [测试] 属性 // 清晰写法相同功能 [测试] public void 使用Test属性的测试() { Assert.True(true); } [事实] public void 使用Fact属性的测试() { Assert.True(true); } ### 矩阵理论资料 (Matrix Theory Data) 公共静态 TheoryData TestData => 新 MatrixTheoryData( [1,2,3], // 数字资料 ["Hello", "World", "Test"] // 字串资料）； // 这会产生3×3=9个测试案例 [理论] [成员数据（名称（测试数据））] public void 矩阵测试范例(int number, string text) { number.Should().BePositive(); text.Should().NotBeNullOrEmpty(); } ### 装配夹具公共类DatabaseAssemblyFixture：IAsyncLifetime { 公共字符串 ConnectionString { 获取；私人套装； } 公共异步任务InitializeAsync() { // 建立测试资料库 ConnectionString =等待CreateTestDatabaseAsync(); } 公共异步任务 DisposeAsync() { //清理测试资料库等待 DropTestDatabaseAsync(); } } // 注册装配夹具 [程序集：AssemblyFixture(typeof(DatabaseAssemblyFixture))] // 在测试中使用公共类 UserServiceTests { 私有只读DatabaseAssemblyFixture _dbFixture；公共 UserServiceTests（DatabaseAssemblyFixture dbFixture） { _dbFixture = dbFixture; } [事实] public void Test1() { /* 使用 _dbFixture.ConnectionString */ } } ### 测试管道启动公共类 TestPipelineStartup ：ITestPipelineStartup { 公共异步任务ConfigureAsync（ITestPipelineBuilder构建器， CancellationToken（取消令牌） { // 全域初始化逻辑 Console.WriteLine("初始化测试环境..."); 等待InitializeDatabaseAsync(); } } // 注册 [程序集：TestPipelineStartup(typeof(TestPipelineStartup))] ** ** ## xunit.runner.json 设置 { "$schema": "https://xunit.net/schema/v3/xunit.runner.schema.json", "parallelAlgorithm": "保守", “最大并行线程”：4， “诊断消息”：正确， “内部诊断消息”：假， "methodDisplay": "classAndMethod", “preEnumerateTheories”：正确， “stopOnFail”：假 } ** ** ## 测试报告格式 xUnit 3.x 支持多种报告格式： # 生成CTRF格式报告 dotnet run ---ctrf results.json # 产生TRX格式报告 dotnet run -- -trx results.trx # 产生XML格式报告 dotnet run ---xml results.xml # 产生多种格式报告 dotnet run -- -xml results.xml -ctrf results.json -trx results.trx ** ** ## 常见问题及解决方案 ### 问题1：找不到xunit.abstractions **错误**：`类型或命名空间名称“抽象”不存在` **解决** ：删除 `using Xunit.Abstractions;`，相关类型已移至 `Xunit` 命名空间。 ### 问题2：自订DataAttribute无法运作 xUnit 3.x 中 `DataAttribute` 方法签名已变更：`GetData(MethodInfo)` → `GetDataAsync(MethodInfo, DisposalTracker)`，回传类型别改为`Task>`。 ###问题3：IDE无法找到测试确认IDE版本符合要求： * Visual Studio 2022 17.8+ * 骑士 2023.3+ * VS 代码（最新版本）如出现问题，可暂时停用Microsoft测试平台： <属性组> <启用MicrosoftTestingPlatform>假 ** ** ## 升级检查清单 ### 升级前 * 确认目标框架版本 (.NET 8+ 或 .NET Framework 4.7.2+) * 检查专案文件格式（SDK式） * 识别所有async void测试方法 * 查看 IAsyncLifetime 实作 *评估相依套件相容性 * 建立备份路径 ### 升级过程 * 更新套件参考（使用 `xunit.v3`） * 删除 `xunit.abstractions` 参考 * 修改OutputType为Exe * 修改所有async void测试方法 * 使用陈述式更新 * 重构自订属性（如有） * 验证编译成功 * 执行所有测试 ### 升级后验证 * 功能唯一测试 * 相当于基准比较 * CI/CD 管道验证 * 文档更新 * 团队培训 ** ** ## IDE 与工具支持 ### IDE版本需求 IDE | 最低版本 ---|--- 视觉工作室| 2022年17.8+ VS 代码 | 最新版本骑手 | 2023.3+ ### 微软测试平台 xUnit 3.x默认启用微软测试平台： <属性组> <启用MicrosoftTestingPlatform>true <输出类型>Exe ** ** ## 完善改进 xUnit 3.x 带来的完善： 1. **独立进程执行** ：测试在独立进程中执行，隔离性更好 2. **改进的硬件演算法**：更智慧的负载平衡 3. **更快的启动时间**：执行直接执行 4. **更好的记忆体隔离**：减少测试之间的干扰 ** ** ## 参考资源 ### 原始文章本技能内容提炼自「老派软体工程师的测试修练 - 30天挑战」系列文章： * **第 26 天 - xUnit 升级指南：从 2.9.x 到 3.x 的转换** * 铁人赛文章： * 示例程序代码： ### 官方文件 * [xUnit.net 官方网站]() * [xUnit v3新功能文件]() * [xUnit 2.x → 3.x 官方迁移指南]() * [xunit.v3 NuGet 套件]()

Dotnet 测试高级 Xunit 升级指南

包含技能