/migrate-xunit-to-xunit-v3

name: migrate-xunit-to-xunit-v3
description: >
  Migrate .NET test projects from xUnit.net v2 to xunit.v3 and fix v3 breaks.
  Use for package/CPM conversion, OutputType=Exe, preserving the VSTest or MTP
  runner (including projects currently using YTest.MTP.XUnit2), incompatible
  TFMs, async void tests,
  string-to-Type attributes, custom Fact/Theory/BeforeAfterTest attributes,
  Xunit.SkippableFact, xunit.abstractions/extensibility consolidation, and
  Xunit.Combinatorial/StaFact compatibility. Do not use for framework
  conversion or a runner-only migration. For xUnit v3 MTP filter syntax, also
  use 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 | No | Discover `.csproj`, `.sln`, `.slnx`, central props, and source in the current working directory; ask only if none are found or the target is ambiguous |

Workspace and Completion Contract

• Skill activation is not completion. For migrate/fix/update requests, inspect

the staged files, edit them, and run tests in the same task.

• The skill base directory contains only guidance. Search the current working

directory and open paths exactly as returned.

• If a tool rejects a searched path, classify the rejection before retrying.

Only a positively confirmed reader/path-normalization limitation with authorized access permits retrying through another permitted reader/editor.

• On a permission, policy, or content-exclusion denial, stop that path and

report the blocker. Never bypass the denial through other tools, shell commands, aliases, or agents, or infer or reconstruct the restricted content.

• If the rejection reason is unclear, treat the path as unavailable, not

missing. Continue only independently permitted work and explicitly disclose the incomplete migration.

• Do not ask the user to provide a path while workspace discovery can find it.
• Inventory project/central package files and all affected source in one pass.

A package-only migration is incomplete when v2-only APIs remain.

• End with the detected source version and runner, exact package compatibility

set, files changed, discovered/passed/failed/skipped counts, and any platform-specific result. A build without test discovery is not success.

• Package validity is empirical: record the configured feed query or resolved

package graph and a successful restore. In the final result, say how the selected exact versions were proven available; do not merely name a version and leave a judge or user to infer whether it exists.

Workflow

> **Commit strategy:** Do not create commits unless the user asks. Keep project > configuration and source edits logically separable in the diff, but finish > and verify the whole requested migration.

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

Decisions that change the result

Run this preflight before editing:

| Detected state | Required action | |---|---| | Project references `xunit.v3`, has the required executable/runner configuration, contains no remaining v2 packages or v2-only API patterns, and its existing test command passes | Stop: migration is already complete. Do not update versions, create props files, or modify source. Report the verified no-op result. If any required v3 adaptation remains, make only that repair instead of treating the package reference alone as completion. | | xUnit v2 uses `YTest.MTP.XUnit2` | Preserve MTP: remove that shim, set `UseMicrosoftTestingPlatformRunner=true`, and do not add `xunit.runner.visualstudio` or `IsTestingPlatformApplication=false`. | | xUnit v2 does not use the MTP shim | Preserve VSTest: keep/update `xunit.runner.visualstudio` and set `IsTestingPlatformApplication=false`. | | A custom type derives from `BeforeAfterTestAttribute` | Preserve that inheritance and its behavior. Add the `IXunitTest` parameter to both overrides and pass it to `base.Before`/`base.After`; do not replace the subclass with a direct interface implementation. | | A Type-based collection/orderer attribute points to a custom type | Migrate both the attribute syntax and the referenced type's v3 contract. For a collection factory, implement the required xUnit v3 `IXunitTestCollectionFactory` behavior; compiling the attribute while leaving an empty factory is not a complete migration. | | Companion packages are present | Resolve `xunit.v3`, Xunit.Combinatorial, and Xunit.StaFact as one compatible set from configured feeds. If the newest xunit.v3 major has no compatible stable companion on those feeds, select the newest compatible xunit.v3 major and explain the pin. Validate discovery, not just compilation. | | `OutputType=Exe` makes a `net*-windows` project fail on a non-Windows host | Add `EnableWindowsTargeting=true` when cross-building is intended, then rerun. Do not dismiss this migration-induced failure as pre-existing. |

Resolve package versions from the configured package source. Do not guess a version from the product's "v3" name or update unrelated packages. Change only files that contain a package, property, or source construct required by the applicable rule.

After editing a Ce