将 .NET 测试从 xUnit v2/v3 迁移到…

当项目使用 xUnit.net v2/v3 且希望改用 MSTest v4、同时不改变目标框架和测试平台时使用。

适用场景

解决思路

1. 确认项目确实包含 xUnit 包或源码且用户想要 MSTest；若项目已使用 MSTest 且无 xUnit 测试，报告无需迁移且不做任何修改。
2. 不要将框架转换与目标框架升级或 VSTest/MTP 迁移合并；先完成并验证一个迁移再开始另一个。
3. 在当前工作目录中搜索待迁移的项目和源码，不要在本技能基础目录下查找用户文件；使用 glob/search 返回的字面路径打开文件，若某个读取或补丁工具拒绝刚找到的路径，换另一个可用工具重试，在耗尽当前工作区发现手段前不要向用户索要路径。
4. 按请求的交付物分类：'转换这个项目'意味着编辑、构建并测试；'给我一个计划'或'如何转换'意味着只回答；文件存在时不要用'请提供文件'替代执行。
5. 最终回复必须说明源 xUnit 版本、保留的 runner、更改的文件、应用的每个高风险语义映射以及实际测试计数；关于 fixture 生命周期、Owner 映射、取消或并行化的断言必须体现在结果源码中，而不仅是文字描述。
6. 完整迁移请求：检查项目、进行编辑、构建并运行测试，不要只给出计划就停止。
7. 聚焦编译错误或 API 问题：检查相关代码并只应用该映射，不要叙述整个工作流。
8. 不支持的目标框架：在更改包之前停止；MSTest v4 要求测试应用为 .NET 8+ 或 .NET Framework 4.6.2+；提供单独批准的 TFM 升级或 MSTest v3 作为中间目标。
9. 若已无 xUnit 包、命名空间、特性或 fixture 残留：停止，不做文件更改，报告无需迁移，并运行现有 dotnet test 命令一次以证明已是 MSTest 的项目健康。
10. 若源使用 VSTest：保留现有 VSTest 属性/配置；优先保留并更新源项目显式的 Microsoft.NET.Test.Sdk 版本固定；有意依赖 MSTest 元包传递依赖的仓库可保留该约定；不要引入 MTP 属性。
11. 若源使用 MTP：将 xUnit 特定的 MTP 选择替换为 MSTest MTP 配置；优先使用 MSTest.Sdk；若用元包，设置 EnableMSTestRunner=true 和 OutputType=Exe；保留原生与桥接命令集成，不要添加 <UseVSTest>true</UseVSTest> 或其他仅 VSTest 的配置。
12. 若源依赖 xUnit 默认并行化：当当前项目至少有两个可独立运行的测试类时，在编译的 .cs 文件中添加 [assembly: Parallelize(Workers = 0, Scope = ExecutionScope.ClassLevel)]；单类项目且无显式并行设置时省略，因为类级并发不可观察；无论当前类数量如何，都要转换显式的 CollectionBehavior 或 xunit.runner.json 设置；完成前读回更改的文件并在结果中命名它。
13. 对于详细映射和示例，在 references/mapping-cheatsheet.md 中搜索项目中实际存在的构造，只读取匹配部分，不要加载或复制整个参考。
14. 常规项目迁移走快速路径：一次批量发现读取/搜索、一次编辑、一次 dotnet test、一份简洁结果；不要列目录后又通过另一个工具重读相同文件；不要把项目文件复制到已加载技能或其 references/ 目录；除非已知还原是最新的，不要尝试 dotnet test --no-restore；当 dotnet test 足够时不要分开运行 restore、build 和 test；不要重跑已通过的测试命令或为确认而检查未更改的文件。
15. 可用时使用现有 CI/测试结果作为一致性基线；仅当计数不可用且迁移包含数据驱动测试、fixture、跳过、自定义扩展、共享状态或其他无法仅从源码建立一致性的行为时，才运行新的编辑前基线。
16. 在一次发现过程中批量读取测试项目以及 Directory.Build.props、Directory.Packages.props、global.json 和 runner 配置，并搜索源码中的高风险构造。
17. 说明检测到的源版本：xunit 2.x 及相关包 -> xUnit v2；xunit.v3 或 xunit.v3.* -> xUnit v3。
18. 从项目和仓库配置识别 VSTest 或 MTP；仅当平台不明确时使用 platform-detection，并保留检测到的平台。
19. 记录目标框架，若 MSTest v4 不支持则停止。
20. 若快速路径需要新基线，运行现有测试命令一次并记录发现、通过、失败和跳过计数。
21. 编辑前清点高风险构造：IClassFixture、ICollectionFixture、CollectionDefinition、自定义 FactAttribute/TheoryAttribute/DataAttribute；Assert.Throws、ThrowsAny、IsType、Record.Exception、事件断言；ITestOutputHelper、TestContext.Current、IAsyncLifetime；CollectionBehavior、xunit.runner.json、共享静态或外部状态。
22. 从项目文件和中央包文件中移除 xUnit 包，包括 xunit*、xunit.v3.*、xunit.runner.visualstudio、YTest.MTP.XUnit2 以及被替换的 xUnit 特定伴随包。
23. 增量转换默认使用 MSTest v4 元包：<PackageReference Include="MSTest" Version="4.1.0" />（示例版本，替换为从配置包源解析的确切稳定 v4 版本）；元包包含 Microsoft.NET.Test.Sdk、MSTest.TestAdapter、MSTest.TestFramework 和 MSTest.Analyzers；保留 VSTest 时优先保留源项目显式的 Microsoft.NET.Test.Sdk 版本固定并更新到与所选 MSTest 版本兼容的版本；MSTest 4.1.0 要求 Microsoft.NET.Test.Sdk 18.0.1+，不兼容的旧版本固定可能导致 NU1605。
24. 保留 MTP 时，不要将 xUnit 的 UseMicrosoftTestingPlatformRunner 属性带入 MSTest 项目；优先使用解析版本的 MSTest.Sdk；若仓库约定要求元包路线，设置 <EnableMSTestRunner>true</EnableMSTestRunner> 和 <OutputType>Exe</OutputType>；仅对继续通过 VSTest 命令模式调用 MTP 应用的仓库保留 TestingPlatformDotnetTestSupport=true；原生 .NET 10+ MTP 模式不需要它；使用 MSTest.Sdk 保留 VSTest 时设置 <UseVSTest>true</UseVSTest>。
25. 不要更改 TargetFramework；仅在移植相关设置后才移除 xunit.runner.json。
26. 应用常见重写：无类特性 -> [TestClass]；[Fact] -> [TestMethod]；[Theory] + [InlineData] -> [TestMethod] + [DataRow]；[MemberData] -> [DynamicData]；[Fact(Skip = "...")] -> [TestMethod] + [Ignore("...")]；[Trait("Category", value)] -> [TestCategory(value)]；[Trait("Owner", value)] -> [Owner(value)]；其他 [Trait(key, value)] -> [TestProperty(key, value)]；Assert.Equal/NotEqual -> Assert.AreEqual/AreNotEqual；Assert.True/False -> Assert.IsTrue/IsFalse；Assert.Null/NotNull -> Assert.IsNull/IsNotNull。
27. 移除 using Xunit; 和 using Xunit.Abstractions;；元包选项添加 using Microsoft.VisualStudio.TestTools.UnitTesting;；MSTest.Sdk 将其作为隐式全局 using 提供。
28. 保留现有类继承，不要机械地密封类。
29. 为第 1 步发现的每个高风险构造加载映射速查表；强制规则：xUnit Assert.Throws<T> 是精确类型，映射到 MSTest Assert.ThrowsExactly<T>；xUnit Assert.ThrowsAny<T> 允许派生类型，映射到 MSTest Assert.Throws<T>；xUnit Assert.IsType<T> 是精确类型，映射到泛型 Assert.IsExactInstanceOfType<T>；Assert.IsAssignableFrom<T> 映射到泛型 Assert.IsInstanceOfType<T>；当 xUnit 断言的类型化返回值被赋值时，保留该赋值并使用泛型 MSTest 重载而非非泛型 Type 重载；xUnit 对序列的 Assert.Equal 比较元素，在 MSTest 4.3+ 使用 Assert.AreSequenceEqual，在更早 v4 使用 CollectionAssert.AreEqual 配合物化列表，绝不要用基于引用的 Assert.AreEqual 替换序列相等；[Ignore] 和 [Timeout] 是修饰符，保留 [TestMethod] 以便测试被发现；[DataRow] 值必须与参数类型完全匹配；TestContext.Current.CancellationToken 映射到注入的 MSTest TestContext.CancellationToken，绝不要用 CancellationToken.None 或新的 CancellationTokenSource 替换；Owner 是保留的 VSTest 属性，将 [Trait("Owner", value)] 映射到 [Owner(value)] 而非 [TestProperty("Owner", value)]；无 MSTest 等价物的断言（Assert.Collection、Assert.All、Assert.Equivalent、Record.Exception、事件断言）需要显式手动重写，绝不要删除断言而不替换其验证。
30. 当清点使所需映射明确时，在一次编辑中应用机械和语义重写；默认不运行中间构建；使用最终验证的编译器错误仅驱动未解决的转换。
31. 保留构造函数设置和 IDisposable/IAsyncDisposable（当有效时）；将 IAsyncLifetime 映射到 [TestInitialize]/[TestCleanup]。
32. IClassFixture<T> 表示每个测试类一个 fixture 实例，由该类所有方法共享；映射为由接受 TestContext 的静态 [ClassInitialize] 方法创建一次的静态 T 字段，并从静态 [ClassCleanup] 释放一次；绝不要用 [TestInitialize]/[TestCleanup] 做此映射，因为那会为每个测试方法创建一个 fixture。
33. 对于 ICollectionFixture<T>，保留共享和序列化；优先使用每个成员类使用的静态 Lazy<T> 辅助；仅当源集合禁用并行化时才添加 [DoNotParallelize]；仅当 fixture 真正是程序集级时才使用程序集初始化。
34. 将 ITestOutputHelper 替换为构造函数注入或基于属性的 MSTest TestContext，并将每个 _output.WriteLine(...) 调用替换为对应的 TestContext.WriteLine(...)；在最终结果中明确命名 TestContext 注入/属性和 WriteLine 映射；'迁移了输出' 不足以证明一致性。
35. xUnit 默认并行运行类；MSTest 串行运行；当当前项目有两个或更多可独立运行的测试类时，用 [assembly: Parallelize(Workers = 0, Scope = ExecutionScope.ClassLevel)] 保留该有效行为；对于无显式 xUnit 并行设置的单类项目，不要添加程序集策略；始终转换显式的 CollectionBehavior 或 xunit.runner.json 设置；绝不要用 ExecutionScope.MethodLevel 模拟 xUnit；在应用 fixture 作用域或并行化决策前，说明源共享或序列化了什么以及目标如何保留它。
36. 使用与基线相同的平台、过滤器和配置运行测试一次；dotnet test 默认构建；仅当需要隔离编译失败时才单独构建。
37. 比较发现、通过、失败和跳过计数。
38. 在宣布完成前调查每个差异：缺失用例 -> 发现特性、DynamicData 或 DataRow 字面量类型；异常行为改变 -> 精确与派生断言映射；共享状态失败或持续时间大幅变化 -> fixture 作用域和并行化；静默跳过的测试 -> 缺少 [TestMethod] 或不正确的运行时跳过转换。
39. 确认没有 xUnit 包、命名空间、特性、runner 配置或 fixture 接口残留，除非明确记录为手动跟进。
40. 在最终通过的测试后，读回每个实现高风险映射的更改文件，以及任何 runner 或并行化配置；在结果中命名文件和实现其生命周期、数据、跳过、输出、断言、fixture 作用域或并行化行为的确切目标 API；保留类型参数和成员名如 [ClassInitialize]、TestContext.WriteLine 和 Assert.IsExactInstanceOfType<T>；'转换了特性' 或 '迁移了输出' 等笼统说法不是一致性的证据。
41. 保持最终回复简洁且以结果为导向：Changed 命名文件和所应用的确切高风险映射；Verified 给出最终测试命令和发现/通过/失败/跳过计数；Preserved 说明未更改的目标框架和测试平台，以及任何 fixture 或并行化作用域决策；Remaining 指出手动跟进或说明无。
42. 完成标准：识别当前 xUnit 版本和测试平台；转换 xUnit 包和源码构造；目标框架和测试平台保持不变；fixture 作用域和有效并行化决策明确，包括并发不可观察时的合理省略；构建成功；测试发现和结果计数与基线匹配；任何不支持的自定义扩展点被指出而非近似处理。
43. 若用户还想要 MTP，单独运行 migrate-vstest-to-mtp；仅在建立一致性后使用 writing-mstest-tests 来润色转换后的 MSTest 代码。

适用边界 · 注意事项

• 不要用于 xUnit v2 到 v3 的迁移。
• 不要用于 MSTest 升级、NUnit/TUnit 转换或仅 runner 的 VSTest 到 MTP 迁移。
• 不要与目标框架升级或 VSTest/MTP 迁移合并进行。