/migrate-xunit-to-xunit-v3

name: migrate-xunit-to-xunit-v3
description: >
  Migrates .NET test projects from xUnit.net v2 to xUnit.net v3.
  USE FOR: upgrading xunit to xunit.v3.
  DO NOT USE FOR: migrating between test frameworks (MSTest/NUnit to
  xUnit.net), migrating from VSTest to Microsoft.Testing.Platform
  (use migrate-vstest-to-mtp). For xUnit v3 MTP filter syntax
  (--filter-class, --filter-trait, --filter-query), also load
  migrate-vstest-to-mtp.
license: MIT

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

| Input | Required | Description | |-------|----------|-------------| | Test project or solution | Yes | The .NET project or solution containing xUnit.net v2 test projects |

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.

Step 5: Remove `Xunit.Abstractions` usings

Find any `using Xunit.Abstractions;` directives in C# files and remove them completely.

Step 6: Address `async void` breaking change (if applicable)

In xUnit.net v3, `async void` test methods are no longer supported and will fail to compile. Search for any test methods declared with `async void` and change them to `async Task`. Test methods can be identified via the `[Fact]` or `[Theory]` attributes or other test attributes.

Step 7: Address breaking change of attributes (if applicable)

In xUnit.net v3, some attributes were updated so that they accept a `System.Type` instead of two strings (fully qualified type name and assembly name). These attributes are:

• `CollectionBehaviorAttribute`
• `TestCaseOrdererAttribute`
• `TestCollectionOrdererAttribute`
• `TestFrameworkAttribute`

For example, `[assembly: CollectionBehavior("MyNamespace.MyCollectionFactory", "MyAssembly")]` must be converted to `[assembly: CollectionBehavior(typeof(MyNamespace.MyCollectionFactory))]`.

Step 8: Inheriting from FactAttribute or TheoryAttribute (if applicable)

Identify if there are any