xUnit -> MSTest Migration

Workflow

1. Establish the baseline

1. In one discovery pass, batch-read the test projects plus Directory.Build.props, Directory.Packages.props, global.json, and runner configuration, and search the source for the high-risk constructs below.
2. State the detected source version:

- xunit 2.x and related packages -> xUnit v2 - xunit.v3 or xunit.v3.* -> xUnit v3

1. Identify VSTest or MTP from the project and repository configuration. Use platform-detection only when the platform is ambiguous, and preserve the detected platform.
2. Record the target frameworks and stop if MSTest v4 does not support them.
3. If the Fast Path requires a new baseline, run the existing test command once and record discovered, passed, failed, and skipped counts.
4. Inventory high-risk constructs before editing:

- IClassFixture, ICollectionFixture, CollectionDefinition, custom FactAttribute/TheoryAttribute/DataAttribute - Assert.Throws, ThrowsAny, IsType, Record.Exception, event assertions - ITestOutputHelper, TestContext.Current, IAsyncLifetime - CollectionBehavior, xunit.runner.json, shared static or external state

2. Replace packages without switching runners

Remove xUnit packages from project files and central package files. This includes xunit*, xunit.v3.*, xunit.runner.visualstudio, YTest.MTP.XUnit2, and xUnit-specific companion packages that are being replaced.

Default to the MSTest v4 metapackage for an incremental conversion:

<!-- Example pin: replace with the exact stable v4 version resolved from the configured package source. -->
<PackageReference Include="MSTest" Version="4.1.0" />

The metapackage includes Microsoft.NET.Test.Sdk, MSTest.TestAdapter, MSTest.TestFramework, and MSTest.Analyzers. When preserving VSTest, prefer retaining a source project's explicit Microsoft.NET.Test.Sdk pin and update it to a version compatible with the chosen MSTest version; this keeps runner/version compatibility reviewable. A repository that intentionally relies on the metapackage's transitive dependency may preserve that convention instead. For the example pin above, MSTest 4.1.0 requires Microsoft.NET.Test.Sdk 18.0.1+; incompatible older pins can cause NU1605.

When preserving MTP, do not carry xUnit's UseMicrosoftTestingPlatformRunner property into the MSTest project. Prefer MSTest.Sdk at the resolved version. If repository conventions require the metapackage route, set <EnableMSTestRunner>true</EnableMSTestRunner> and <OutputType>Exe</OutputType>. Retain TestingPlatformDotnetTestSupport=true only for repositories that continue to invoke MTP applications through VSTest command mode; native .NET 10+ MTP mode does not require it. When preserving VSTest with MSTest.Sdk, set <UseVSTest>true</UseVSTest>.

Do not change TargetFramework. Remove xunit.runner.json only after porting its relevant settings.

3. Perform the mechanical conversion

Apply the common rewrites first:

| xUnit | MSTest | |---|---| | no class attribute | [TestClass] | | [Fact] | [TestMethod] | | [Theory] + [InlineData] | [TestMethod] + [DataRow] | | [MemberData] | [DynamicData] | | [Fact(Skip = "...")] | [TestMethod] + [Ignore("...")] | | [Trait("Category", value)] | [TestCategory(value)] | | [Trait("Owner", value)] | [Owner(value)] | | other [Trait(key, value)] | [TestProperty(key, value)] | | Assert.Equal / NotEqual | Assert.AreEqual / AreNotEqual | | Assert.True / False | Assert.IsTrue / IsFalse | | Assert.Null / NotNull | Assert.IsNull / IsNotNull |

Remove using Xunit; and using Xunit.Abstractions;. Add using Microsoft.VisualStudio.TestTools.UnitTesting; for the metapackage option; MSTest.Sdk supplies it as an implicit global using.

Preserve existing class inheritance. Do not mechanically seal classes.

4. Resolve semantic mappings

Load the mapping cheatsheet for every high-risk construct found in Step 1. These rules are mandatory:

• xUnit Assert.Throws<T> is exact-type and maps to MSTest Assert.ThrowsExactly<T>.
• xUnit Assert.ThrowsAny<T> permits derived types and maps to MSTest Assert.Throws<T>.
• xUnit Assert.IsType<T> is exact-type and maps to Assert.IsExactInstanceOfType<T>; Assert.IsAssignableFrom<T> maps to Assert.IsInstanceOfType<T>.
• xUnit Assert.Equal on sequences compares elements. Use Assert.AreSequenceEqual on MSTest 4.3+ or CollectionAssert.AreEqual with materialized lists on earlier v4; never replace sequence equality with reference-based Assert.AreEqual.
• [Ignore] and [Timeout] are modifiers; keep [TestMethod] so the test is discovered.
• [DataRow] values must exactly match parameter types.
• TestContext.Current.CancellationToken maps to an injected MSTest TestContext.CancellationToken; never replace it with CancellationToken.None or a new CancellationTokenSource.
• Owner is a reserved VSTest property. Map [Trait("Owner", value)] to [Owner(value)], not [TestProperty("Owner", value)].
• Assertions with no MSTest equivalent (Assert.Collection, Assert.All, Assert.Equivalent, Record.Exception, event assertions) require an explicit manual rewrite. Never delete an assertion without replacing its verification.

Apply the mechanical and semantic rewrites in one edit pass when the inventory makes the required mappings clear. Do not run an intermediate build by default; use compiler errors from final verification to drive only unresolved conversions.

5. Preserve lifecycle, fixture scope, and parallelization

• Keep constructor setup and IDisposable/IAsyncDisposable when valid. Map IAsyncLifetime to [TestInitialize]/[TestCleanup].
• Map IClassFixture<T> to class-scoped initialization and cleanup.
• For ICollectionFixture<T>, preserve both sharing and serialization. Prefer a static Lazy<T> helper used by each member class; add [DoNotParallelize] only when the source collection disabled parallelization. Use assembly initialization only when the fixture is genuinely assembly-wide.
• Replace ITestOutputHelper with injected or property-based MSTest TestContext.

xUnit runs classes in parallel by default; MSTest runs them serially. Unless the source disabled parallelism, preserve xUnit behavior with:

[assembly: Parallelize(Workers = 0, Scope = ExecutionScope.ClassLevel)]

Never use ExecutionScope.MethodLevel to emulate xUnit. Before applying a fixture-scope or parallelization decision, state what the source shared or serialized and how the target preserves it.

6. Verify parity

1. Run tests once with the same platform, filter, and configuration used for the baseline. dotnet test builds by default; run a separate build only when needed to isolate a compilation failure.
2. Compare discovered, passed, failed, and skipped counts.
3. Investigate every difference before declaring completion:

- missing cases -> discovery attributes, DynamicData, or DataRow literal types - changed exception behavior -> exact-vs-derived assertion mapping - shared-state failures or large duration changes -> fixture scope and parallelization - silently skipped tests -> missing [TestMethod] or incorrect runtime-skip conversion

1. Confirm no xUnit package, namespace, attribute, runner configuration, or fixture interface remains unless explicitly documented for manual follow-up.
2. Read back any runner or parallelization configuration you changed and report its file path and effective setting.

Related skills