dotnet-testing-advanced-xunit-upgrade-guide

xUnit Upgrade Guide: From 2.9.x to 3.x

Core Concepts

Package Naming Changes

xUnit v3 adopts an entirely new package naming strategy:

v1~v2 Package Name	v3 Package Name	Description
`xunit`	`xunit.v3`	Main test framework
`xunit.assert`	`xunit.v3.assert`	Assertion library
`xunit.core`	`xunit.v3.core`	Core components
`xunit.abstractions`	(Removed)	No longer needed
`xunit.runner.visualstudio`	`xunit.runner.visualstudio` (3.x.y)	Test runner

Important: Use the xunit.v3 package name, not xunit。

Minimum Runtime Requirements

.NET Framework 4.7.2+ or .NET 8.0+ (recommended)
Not supported：.NET Core 3.1、.NET 5/6/7

Breaking Changes

Covers six breaking changes including OutputType changed to Exe, async void no longer supported, IAsyncLifetime inheriting IAsyncDisposable, SkippableFact removed, only SDK-style projects supported, and custom DataAttribute signature changes, each with before-and-after code comparisons.

For the complete list of breaking changes and code examples, refer to references/breaking-changes.md

Upgrade Steps

Five-step SOP: create an upgrade branch → update project files (packages, OutputType) → fix async void → update using → compile and test. Also includes a .NET 10 SDK MTP mode migration guide (global.json configuration, CLI usage changes, VSTest migration steps).

For the complete upgrade steps and .NET 10 MTP mode guide, refer to references/upgrade-steps.md

xUnit 3.x New Features

Covers new features including Assert.Skip / SkipUnless / SkipWhen dynamic skipping, Explicit Tests, the [Test] attribute, MatrixTheoryData matrix testing, Assembly Fixtures, Test Pipeline Startup, and multi-format test reports, each with complete code examples.

For complete new feature examples, refer to references/new-features.md

Testcontainers.XunitV3 Integration Package

Testcontainers officially released Testcontainers.XunitV3(4.9.0), an integration package designed specifically for xUnit v3 that automatically manages container creation and disposal, replacing the manual implementation of IAsyncLifetime .

<PackageReference Include="Testcontainers.XunitV3" Version="4.9.0" />

If a project uses both Testcontainers and xUnit v3, it is recommended to adopt this package to simplify container lifecycle management.

xunit.runner.json Configuration

{
  "$schema": "https://xunit.net/schema/v3/xunit.runner.schema.json",
  "parallelAlgorithm": "conservative",
  "maxParallelThreads": 4,
  "diagnosticMessages": true,
  "internalDiagnosticMessages": false,
  "methodDisplay": "classAndMethod",
  "preEnumerateTheories": true,
  "stopOnFail": false
}

Common Issues and Solutions

Issue 1: xunit.abstractions not found

Remove using Xunit.Abstractions;, the related types have been moved to the Xunit namespace.

Issue 2: IDE cannot discover tests

Verify the IDE version: Visual Studio 2022 17.8+, Rider 2023.3+, latest VS Code. If problems persist, you can temporarily disable MTP:

<PropertyGroup>
  <EnableMicrosoftTestingPlatform>false</EnableMicrosoftTestingPlatform>
</PropertyGroup>

.NET 10 SDK Note: If using MTP mode, disabling MTP will cause the dotnet test error. Instead, remove the global.json section in test .

Upgrade Checklist

Before Upgrade

Confirm the target framework version (.NET 8+ or .NET Framework 4.7.2+)
Check the project file format (SDK-style)
Identify all async void test methods
Check IAsyncLifetime implementations
Evaluate dependency compatibility
Create backup branch

Upgrade process

Update package references (using xunit.v3)
Remove xunit.abstractions references
Change OutputType to Exe
Fix all async void test methods
Update using statements
Refactor custom attributes (if any)
Verify compilation succeeds
Run all tests

Post-upgrade verification

Functional integrity testing
Performance benchmark comparison
CI/CD Pipeline verification
Documentation update
Team training
(.NET 10+) Configure global.json Enable MTP mode and verify dotnet test works properly

IDE and tool support

IDE	Minimum version
Visual Studio	2022 17.8+
VS Code	Latest version
Rider	2023.3+

xUnit 3.x enables Microsoft Testing Platform (MTP) by default, and with the .NET 10 SDK, native MTP mode can be used.

For detailed configuration of .NET 10 MTP mode, refer to references/upgrade-steps.md

Output format

Generate the upgraded test project .csproj configuration (xunit.v3 package, OutputType Exe)
Include test code with async void fixed to async Task
Include examples of IAsyncLifetime adjustments and SkippableFact replacements
Generate the xunit.runner.json configuration file

Reference resources

Original article

The content of this skill is distilled from the "Old-School Software Engineer's Testing Practice - 30-Day Challenge" article series:

Day 26 - xUnit Upgrade Guide: Transitioning from 2.9.x to 3.x
- Ironman contest article:https://ithelp.ithome.com.tw/articles/10377477
- Sample code:https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day26

Official documentation

Related skills

dotnet-testing-xunit-project-setup - xUnit project configuration basics
dotnet-testing-advanced-tunit-fundamentals - TUnit alternative framework
dotnet-testing-advanced-testcontainers-database - Testcontainers database integration testing (with XunitV3 package)