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

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)
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

Exe

In each test project (excluding test library projects), set

OutputType

Exe

in the project file:

xml

<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>

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]

[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 custom attributes that inherit from

FactAttribute

TheoryAttribute

. These custom user-defined attributes must now provide source information. For example, if the attribute looked like this:

csharp

internal sealed class MyFactAttribute : FactAttribute
{
    public MyFactAttribute()
    {
    }
}

it must be changed to this:

csharp

internal sealed class MyFactAttribute : FactAttribute
{
    public MyFactAttribute(
        [CallerFilePath] string? sourceFilePath = null,
        [CallerLineNumber] int sourceLineNumber = -1
    ) : base(sourceFilePath, sourceLineNumber)
    {
    }
}

Step 9: Inheriting from BeforeAfterTestAttribute (if applicable)

Identify if there are any custom attributes that inherit from

BeforeAfterTestAttribute

. These custom user-defined attributes must update their method signatures. Previously, they would have

Before

After

overrides that look like this:

csharp

    public override void Before(MethodInfo methodUnderTest)
    {
        // Possibly some custom logic here
        base.Before(methodUnderTest);
        // Possibly some custom logic here
    }

    public override void After(MethodInfo methodUnderTest)
    {
        // Possibly some custom logic here
        base.After(methodUnderTest);
        // Possibly some custom logic here
    }

it must be changed to this:

csharp

    public override void Before(MethodInfo methodUnderTest, IXunitTest test)
    {
        // Possibly some custom logic here
        base.Before(methodUnderTest, test);
        // Possibly some custom logic here
    }

    public override void After(MethodInfo methodUnderTest, IXunitTest test)
    {
        // Possibly some custom logic here
        base.After(methodUnderTest, test);
        // Possibly some custom logic here
    }

Step 10: Address new xUnit analyzer warnings (if applicable)

xunit.v3 introduced new analyzer warnings. The most notable is xUnit1051 (use

TestContext.Current.CancellationToken

for methods accepting

CancellationToken

). Address these if present.

Step 11: Migrate

Xunit.SkippableFact

(if applicable)

If there are any package references to

Xunit.SkippableFact

, remove all these package references entirely.

Then, follow these steps to eliminate usages of APIs coming from the removed package reference:

Update any
```
SkippableFact
```
attribute to the regular
```
Fact
```
attribute.
Update any
```
SkippableTheory
```
attribute to the regular
```
Theory
```
attribute.
Change
```
Skip.If
```
method calls to
```
Assert.SkipWhen
```
.
Change
```
Skip.IfNot
```
method calls to
```
Assert.SkipUnless
```
.

Step 12: Update companion packages (if applicable)

```
Xunit.Combinatorial
```
1.x → latest 2.x
```
Xunit.StaFact
```
1.x → latest 3.x

Step 13: Build and verify

Build the solution and fix any remaining compilation errors. Run

dotnet test

to verify all tests pass with the same results as before migration.

migrate-xunit-to-xunit-v3

NPX Install

Tags

SKILL.md Content

xunit.v3 Migration

When to Use

When Not to Use

Inputs

Workflow

Step 1: Identify xUnit.net projects and verify compatibility

Step 2: Update package references

Step 3: Set
`OutputType`
to
`Exe`

Step 4: Configure test platform

Step 5: Remove
`Xunit.Abstractions`
usings

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

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

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

Step 9: Inheriting from BeforeAfterTestAttribute (if applicable)

Step 10: Address new xUnit analyzer warnings (if applicable)

Step 11: Migrate
`Xunit.SkippableFact`
(if applicable)

Step 12: Update companion packages (if applicable)

Step 13: Build and verify

migrate-xunit-to-xunit-v3

NPX Install

Tags

SKILL.md Content

xunit.v3 Migration

When to Use

When Not to Use

Inputs

Workflow

Step 1: Identify xUnit.net projects and verify compatibility

Step 2: Update package references

Step 3: Set OutputType to Exe

Step 4: Configure test platform

Step 5: Remove Xunit.Abstractions usings

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

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

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

Step 9: Inheriting from BeforeAfterTestAttribute (if applicable)

Step 10: Address new xUnit analyzer warnings (if applicable)

Step 11: Migrate Xunit.SkippableFact (if applicable)

Step 12: Update companion packages (if applicable)

Step 13: Build and verify

Step 3: Set
`OutputType`
to
`Exe`

Step 5: Remove
`Xunit.Abstractions`
usings

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

Step 11: Migrate
`Xunit.SkippableFact`
(if applicable)