Migrate Xunit To Xunit V3

xunit.v3 Migration

Migrate .NET test projects from xUnit.net v2 to xUnit.net v3. The outcome is a solution where all test projects reference xunit.v3.* packages, compiles cleanly, and all tests pass with the same results as before migration.

When to Use

• Upgrading test projects from xunit (v2) packages to xunit.v3
• Resolving compilation errors after updating xunit package references to v3

When Not to Use

• Migrating between test frameworks (e.g., MSTest or NUnit to xUnit.net) — different effort entirely
• Migrating from VSTest to Microsoft.Testing.Platform — use migrate-vstest-to-mtp
• The projects already reference xunit.v3 — migration is done

Inputs

Workflow

Commit strategy: Commit after each major step so the migration is reviewable and bisectable. Separate project file changes from code changes.

Prioritization: Steps 1-5 are required for every migration. Steps 6-12 are conditional — only apply the ones relevant to the project's code patterns. Skip steps that don't apply.

Step 1: Identify xUnit.net projects and verify compatibility

Search for test projects referencing xUnit.net v2 packages:

• xunit
• xunit.abstractions
• xunit.assert
• xunit.core
• xunit.extensibility.core
• xunit.extensibility.execution
• xunit.runner.visualstudio

Make sure to check the package references in project files, MSBuild props and targets files, like Directory.Build.props, Directory.Build.targets, and Directory.Packages.props.

Verify target framework compatibility: xUnit.net v3 requires .NET 8+ or .NET Framework 4.7.2+. For test library projects, .NET Standard 2.0 is also supported. If any test projects have non-compatible target frameworks, STOP here — tell the user to upgrade the target framework first. Also verify the project uses SDK-style format.

Step 2: Update package references

1. Update any PackageReference or PackageVersion items for the new package names, based on the following mapping:

   • xunit → xunit.v3
   • xunit.abstractions → Remove entirely
   • xunit.assert → xunit.v3.assert
   • xunit.core → xunit.v3.core
   • xunit.extensibility.core and xunit.extensibility.execution → xunit.v3.extensibility.core (if both are referenced in a project consolidate to only a single entry as the two packages are merged)

2. Update all xunit.v3.* packages to the latest correct version available on NuGet. Also update xunit.runner.visualstudio to the latest version.

Step 3: Set OutputType to Exe

In each test project (excluding test library projects), set OutputType to Exe in the project file:

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

Depending on the solution in hand, there might be a centralized place where this can be added. For example:

• If all test projects share (or can share) a common Directory.Build.props, add the <OutputType>Exe</OutputType> property there. Note that the OutputType should not be added to Directory.Build.targets.
• If all test projects share a name pattern (e.g., *.Tests.csproj), add a conditional property group in Directory.Build.props that applies only to those projects, like <OutputType Condition="$(MSBuildProjectName.EndsWith('.Tests'))">Exe</OutputType>. Adjust the condition as needed to target only test projects.
• Otherwise, add the <OutputType>Exe</OutputType> property to each test project file individually.

Step 4: Configure test platform

Preserve the same test platform that was used with xUnit.net v2. xUnit.net v2 always uses VSTest except if the project used YTest.MTP.XUnit2.

• If the project had a reference to YTest.MTP.XUnit2:
  • Remove the reference to YTest.MTP.XUnit2 completely.
  • Add <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> to Directory.Build.props under an unconditional PropertyGroup.
• If the project did NOT reference YTest.MTP.XUnit2 (the common case):
  • Add <IsTestingPlatformApplication>false</IsTestingPlatformApplication> to Directory.Build.props under an unconditional PropertyGroup. If Directory.Build.props doesn't exist, create it. This keeps the project on VSTest.