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

Workspace and Completion Contract

• Skill activation is not completion. For migrate/fix/update requests, inspect the staged files, edit them, and run tests in the same task.
• The skill base directory contains only guidance. Search the current working directory and open paths exactly as returned. If a tool rejects a path just found by search, retry with another available reader/editor instead of concluding that files are missing.
• Do not ask the user to provide a path while workspace discovery can find it.
• Inventory project/central package files and all affected source in one pass. A package-only migration is incomplete when v2-only APIs remain.
• End with the detected source version and runner, exact package compatibility set, files changed, discovered/passed/failed/skipped counts, and any platform-specific result. A build without test discovery is not success.
• Package validity is empirical: record the configured feed query or resolved package graph and a successful restore. In the final result, say how the selected exact versions were proven available; do not merely name a version and leave a judge or user to infer whether it exists.

Workflow

Commit strategy: Do not create commits unless the user asks. Keep project configuration and source edits logically separable in the diff, but finish and verify the whole requested migration.

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.

Decisions that change the result

Run this preflight before editing:

Resolve package versions from the configured package source. Do not guess a version from the product's "v3" name or update unrelated packages. Change only files that contain a package, property, or source construct required by the applicable rule.

After editing a Central Package Management project, read back both Directory.Packages.props and the project file. Confirm that PackageVersion owns the version, the renamed PackageReference is versionless, and OutputType=Exe is effective.

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. Query the configured package source and pin the latest stable versions that actually exist. Also update xunit.runner.visualstudio only for VSTest projects; do not add it to MTP projects.

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.
  • Set <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> in an existing shared Directory.Build.props, or in the test project when no shared props file exists.
  • Do not add xunit.runner.visualstudio; it is a VSTest runner and weakens platform preservation.
• If the project did NOT reference YTest.MTP.XUnit2 (the common case):
  • Set <IsTestingPlatformApplication>false</IsTestingPlatformApplication> in an existing shared Directory.Build.props, or directly in the test project when no shared props file exists. Do not create a repository-wide props file solely for one project. This keeps the project on VSTest.