dotnet-testing-advanced-xunit-upgrade-guide_skill

Overview

This skill is a practical, step-by-step guide for upgrading xUnit test projects from 2.9.x to 3.x. It highlights package renames, required project changes, breaking changes to fix, and new xUnit v3 features you can adopt to improve tests. Use it to plan and execute a safe migration with verification and CI checks.

How this skill works

The guide inspects project files, package references, and test code patterns to identify required changes: switch to xunit.v3 packages, change OutputType to Exe, update target frameworks, and find async void tests and old abstractions. It documents code fixes (async Task, IAsyncLifetime adjustments), updated DataAttribute signatures, and new test features like Assert.Skip, Explicit tests, MatrixTheoryData, and AssemblyFixture, plus recommended verification steps.

When to use it

• When migrating an existing xUnit 2.x test suite to xUnit 3.x
• When evaluating compatibility impact of updating test dependencies
• When CI or IDE fails to discover tests after an attempted upgrade
• When adopting xUnit v3 features like Assert.Skip or Matrix Theory
• When consolidating async cleanup logic to IAsyncLifetime/DisposeAsync

Best practices

• Create a dedicated upgrade branch and back up the test project before changes
• Target supported runtimes (.NET 8+ or .NET Framework 4.7.2+) and convert to SDK-style if needed
• Search and replace async void test methods to async Task using a regex
• Move all cleanup to DisposeAsync when implementing IAsyncLifetime to avoid missing Dispose calls
• Replace SkippableFact/SkippableTheory with Assert.Skip or SkipUnless/SkipWhen attributes
• Run full build, dotnet test, and CI pipeline validation after changes

Example use cases

• Update a large test suite: change PackageReference to xunit.v3, set OutputType to Exe, and fix failures
• Implement AssemblyFixture to provision and tear down an integration database across tests
• Convert custom DataAttribute implementations to the new async signature and return type
• Run selective long-running tests by marking them [Fact(Explicit = true)] and gating with Assert.Skip
• Adopt MatrixTheoryData to generate Cartesian product test cases for combinatorial coverage