skip to content

You are migrating a ticketing library's xUnit.net v2 test suite to xunit.v3; what breaks, and in what order do you fix it?

level: seniorimportance: should knowfreq 40%

answer

  1. packages first, then project, then code
  2. xunit -> xunit.v3, drop xunit.abstractions
  3. OutputType Exe
  4. Xunit.Abstractions namespace is gone
  5. async void tests now fail

basics

~20 s

Swap the packages (xunit to xunit.v3, or xunit.v3.mtp-off to stay on VSTest), make the project an executable, fix compile errors from moved APIs, then run-time failures such as async void tests, and finally adopt v3 features.

solid answer

~40 s

Work outside-in. **Packages**: replace `xunit` with `xunit.v3`, or with `xunit.v3.mtp-off` plus `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio` if CI must stay on VSTest; remove `xunit.abstractions`; move helper libraries to `xunit.v3.extensibility.core`. **Project**: set `<OutputType>Exe</OutputType>`, since the build fails otherwise, and confirm targets are .NET 8+ or .NET Framework 4.7.2+. **Compile errors**: delete `using Xunit.Abstractions;` (`ITestOutputHelper` now lives in `Xunit`), change `IAsyncLifetime` methods to `ValueTask`, replace `CollectionBehavior` parallel settings with `[assembly: Parallelization(...)]`, and rework custom discoverers or attributes against the new extensibility API. **Run time**: `async void` tests now fail with "Tests marked as 'async void' are no longer supported"; convert them to `async Task`. **Then improve**: pass `TestContext.Current.CancellationToken`, replace early-return skips with `Assert.Skip*`, and mark slow checks `Explicit`. Migrate one project at a time and compare test counts before and after.

code

xml · 18 lines
xml
<!-- Before: xUnit.net v2 (versions come from Directory.Packages.props) -->
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Test.Sdk" />
  <PackageReference Include="xunit" />
  <PackageReference Include="xunit.runner.visualstudio" />
</ItemGroup>

<!-- After: xunit.v3 on Microsoft.Testing.Platform -->
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <OutputType>Exe</OutputType>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="xunit.v3" />
</ItemGroup>

go deeper

for a junior

Know the headline changes: new package xunit.v3, the project must be an executable, and async void tests are no longer allowed.

for a middle

Walk through the ordered steps (packages, project, compile errors, run-time failures) and the main API moves: Xunit.Abstractions, IAsyncLifetime, parallelization settings.

for a senior

Run the migration safely: one project at a time, compare discovered and passing counts, choose mtp-off where CI depends on VSTest, and budget for custom extensibility code.

for a principal

Sequence a portfolio migration: which suites move first, whether the platform switch is bundled or separate, and how to keep CI signal trustworthy throughout.

## Plan the migration outside-in A v2-to-v3 migration touches four layers, and fixing them in order keeps each step's errors small: **packages**, then the **project file**, then **compile errors**, then **run-time behaviour**, and only then **new features**. Migrating one test project at a time, and comparing the number of discovered tests before and after, catches tests that silently stopped being discovered. ## Step 1: packages | v2 reference | xunit.v3 replacement | |---|---| | `xunit` | `xunit.v3` (Microsoft.Testing.Platform v2) or `xunit.v3.mtp-off` (VSTest only) | | `xunit.runner.visualstudio` + `Microsoft.NET.Test.Sdk` | not needed with `xunit.v3`; still required with `xunit.v3.mtp-off` | | `xunit.abstractions` | removed; its types moved into the v3 packages | | `xunit.extensibility.core` / `xunit.extensibility.execution` in helper libraries | `xunit.v3.extensibility.core` | The choice between `xunit.v3` and `xunit.v3.mtp-off` is mostly about CI: the first runs on Microsoft.Testing.Platform, the second keeps VSTest-based pipelines and adapters working unchanged. ## Step 2: the project file - Add `<OutputType>Exe</OutputType>`. The xunit.v3 build targets stop the build with "xUnit.net v3 test projects must be executable" whenever the property has any other value. - Check target frameworks: .NET 8 or later, or .NET Framework 4.7.2 or later. Projects on older frameworks stay on v2 until retargeted. - Remove any hand-written `Main` or set `XunitAutoGeneratedEntryPoint` to `false` if you keep one. - Shared helper projects must not reference `xunit.v3`, or they inherit the executable requirement. ## Step 3: compile errors The common ones, roughly in the order they appear: 1. **`Xunit.Abstractions` no longer exists.** `ITestOutputHelper` is in the `Xunit` namespace; deleting the `using` usually suffices. 2. **`IAsyncLifetime` changed shape.** `InitializeAsync` and `DisposeAsync` return `ValueTask`, and the interface now extends `IAsyncDisposable`. 3. **Parallelism settings moved.** `CollectionBehavior`'s `DisableTestParallelization` and `MaxParallelThreads` are obsolete as errors in 4.x; use `[assembly: Parallelization(...)]`. 4. **Theory data is typed.** `TheoryData<T>` holds typed rows; code that treated it as `object[]` rows needs adjusting. 5. **Extensibility code.** Custom `DataAttribute` subclasses, test case discoverers, orderers and `BeforeAfterTestAttribute` implementations compile against a reworked API in `Xunit.v3` and usually need real changes, so budget for them separately. ## Step 4: run-time differences - **`async void` tests fail.** v3 rejects them with "Tests marked as 'async void' are no longer supported. Please convert to 'async Task' or 'async ValueTask'." v2 ran them, so they compile fine and fail only when run. - **Discovery of theory rows** can differ by runner; compare listed test counts rather than assuming they match. - **Configuration.** `xunit.runner.json` is still read; review settings like `parallelizeTestCollections`, which still works when `parallelMode` is not set. ## Step 5: adopt what v3 adds - Pass `TestContext.Current.CancellationToken` to async calls so timeouts and aborted runs stop work. - Replace early-`return` pseudo-skips with `Assert.Skip`, `Assert.SkipUnless` or `Assert.SkipWhen`, and attribute-level `SkipUnless`/`SkipWhen`. - Mark slow manual checks with `Explicit = true` instead of a permanent `Skip`. - Consider an assembly fixture for resources several classes rebuild. ## How it played out on the ticketing suite The ticketing library has three test projects: fast unit tests for pricing and seat holds, integration tests against a payment sandbox, and a helper library with shared fixtures. A sensible order is: - the **helper library** first, moved to `xunit.v3.extensibility.core` so it builds as a library again; - the **unit tests** next, where the work is mostly packages, `OutputType` and deleted `Xunit.Abstractions` usings; - the **sandbox tests** last, where `IAsyncLifetime` fixtures change signature, the old early-return "skip when the sandbox is down" becomes `Assert.SkipUnless`, and every sandbox call starts receiving `TestContext.Current.CancellationToken`. Each project lands as its own change with its before-and-after test counts in the description. ## Verifying the migration 1. Record the v2 test count per project and per class before starting. 2. After each project, run it as an executable and compare counts; a drop usually means an `async void` test, a broken custom data attribute or a theory whose data no longer binds. 3. Run the full suite in CI on both the old and new branch once, then delete the v2 configuration. 4. Keep the migration commit free of unrelated test changes so a reviewer can see what the framework change alone did.

  • Why do async void tests survive the compile step of a migration and only fail when run?
    `async void` is legal C#, and `[Fact]` places no compile-time restriction on the return type. xunit.v3's runner checks the method when invoking it and fails the test with "Tests marked as 'async void' are no longer supported. Please convert to 'async Task' or 'async ValueTask'." Comparing pass counts before and after the migration surfaces them quickly.
  • Should every project move to Microsoft.Testing.Platform as part of the migration?
    Not necessarily. `xunit.v3.mtp-off` keeps VSTest, together with `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio`, so CI that depends on VSTest options keeps working while the framework upgrade lands. Switching the platform can be a separate change once the suite is green on v3.

  • Migrating to xunit.v3 only means bumping the xunit package version to 3.x.
  • Test projects can remain class libraries after moving to xunit.v3.
  • Xunit.Abstractions is still needed for ITestOutputHelper in xunit.v3.
  • async void tests keep working in xunit.v3 because they compile.
  • xunit.v3 forces every project onto Microsoft.Testing.Platform.
  • Custom data attributes and discoverers move over without code changes.

Assumes migration from xUnit.net v2 (packages xunit and xunit.runner.visualstudio) to xunit.v3 4.x; the product line is called v3 while its packages are versioned 4.x.