Migrate Vstest To Mtp

VSTest -> Microsoft.Testing.Platform Migration

Migrate a .NET test solution from VSTest to Microsoft.Testing.Platform (MTP). The outcome is a solution where all test projects run on MTP, dotnet test works correctly, and CI/CD pipelines are updated.

First Action

Inspect the supplied project, Directory.Build.props, global.json, and CI files before searching the web or answering from memory. Resolve the framework and SDK mode first: .NET 9 and earlier use the compatibility property plus the -- separator; .NET 10 native MTP uses global.json, removes that property, and passes MTP arguments without the separator. For central properties, never condition on IsTestProject in Directory.Build.props; use a property already available there, such as MSBuildProjectName.

Important: Do not mix VSTest-based and MTP-based .NET test projects in the same solution or run configuration -- this is an unsupported scenario.

When to Use

• Switching from VSTest to Microsoft.Testing.Platform for any supported test framework
• Enabling dotnet run / dotnet watch / direct executable execution for test projects
• Enabling Native AOT or trimmed test execution
• Replacing vstest.console.exe with dotnet test on MTP
• Updating CI/CD pipelines from the VSTest task to the .NET Core CLI task
• Updating dotnet test arguments from VSTest syntax to MTP syntax

When Not to Use

• The project already runs on Microsoft.Testing.Platform and there is no remaining MTP behavioral difference to resolve (e.g., exit code 8 for zero tests discovered)
• Migrating between test frameworks (e.g., MSTest to xUnit.net) -- different effort entirely
• The project builds UWP or packaged WinUI test projects -- MTP does not support these yet
• The solution mixes .NET and non-.NET test adapters (e.g., JavaScript or C++ adapters) -- VSTest is required
• Upgrading MSTest versions -- use migrate-mstest-v1v2-to-v3 or migrate-mstest-v3-to-v4

Inputs

Execution and Answer Contract

• Discover project, props, global.json, and pipeline files in the current working directory. Open literal search results; the skill directory is not the user's repository. Continue after skill activation and do not ask for a discoverable path.
• For an implementation request, edit the files, then validate the effective MSBuild properties, the translated command, test counts, and requested artifacts. For a question, provide one exact command/configuration for the detected SDK and framework rather than a menu of near-equivalents.
• Preserve all build arguments and avoid introducing --no-build, new settings files, or unrelated package upgrades. Never retain --settings <file> unless that file exists.
• For .NET 9 and earlier, show the -- separator. For .NET 10 native MTP mode, explicitly say to remove it.
• When suppressing exit code 8 is intentional, warn that broad suppression can hide an accidental empty run caused by a bad filter; scope it to the known zero-test project/configuration.
• For an exit-code-8 question, show all three concrete forms: --ignore-exit-code 8, TestingPlatformCommandLineArguments, and TESTINGPLATFORM_EXITCODE_IGNORE=8.
• For xUnit v3 filters, give the directly usable --filter-class/--filter-method/--filter-trait command and explain AND behavior. When the resolved xUnit version supports it, include --filter-query path syntax for complex expressions and link the xUnit query-filter documentation.
• When translating reporters, coverage, or dumps, name each required package in the answer; a correct-looking option without its owning extension package is incomplete.
• Final results must name the framework runner opt-in, repository-selected SDK integration mode, exact translated command, extension packages, and verification evidence.

Workflow

Step 1: Assess the solution

1. Identify the test framework for each test project -- see the platform-detection skill for the package-to-framework mapping. Key indicators:
   • MSTest: References MSTest or MSTest.TestAdapter, or uses MSTest.Sdk (with <IsTestApplication> not set to false). Note: MSTest.TestFramework alone is a library dependency, not a test project.
   • NUnit: References NUnit3TestAdapter
   • xUnit.net: References xunit and xunit.runner.visualstudio
2. Resolve the SDK used by the repository/CI from global.json or explicit user context. Fall back to dotnet --version only when neither exists; the agent host SDK must not silently override a stated .NET 8/9 CI target.
3. Check whether a Directory.Build.props file exists at the solution or repo root -- all MTP properties should go there for consistency
4. Check for vstest.console.exe usage in CI scripts or pipeline definitions
5. Check for VSTest-specific dotnet test arguments in CI scripts: --filter, --logger, --collect, --settings, --blame*
6. Run dotnet test to establish a baseline of test pass/fail counts

Step 2: Set up Directory.Build.props

Critical: Set MTP runner properties in Directory.Build.props at the solution or repo root whenever possible, rather than per-project. This prevents inconsistent configuration where some projects use VSTest and others use MTP (an unsupported scenario). Note: MTP also requires test projects to have <OutputType>Exe</OutputType>. Only MSTest.Sdk sets this automatically. For all other setups (MSTest NuGet packages with EnableMSTestRunner, NUnit with EnableNUnitRunner, xUnit.net with YTest.MTP.XUnit2), prefer setting <OutputType>Exe</OutputType> centrally in Directory.Build.props with a condition that targets only test projects. If you cannot reliably target only test projects from Directory.Build.props, setting <OutputType>Exe</OutputType> per-project is an acceptable exception.

Conditioning in Directory.Build.props: Do NOT use Condition="'$(IsTestProject)' == 'true'" -- IsTestProject is set by the test SDK targets later in evaluation and is not available when Directory.Build.props is imported. Use a property that is available early, such as MSBuildProjectName, to target test projects by naming convention. For example, if all test projects end in .Tests:

<PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
  <OutputType>Exe</OutputType>
</PropertyGroup>

Adjust the condition (e.g., .EndsWith('Tests'), .Contains('.Test')) to match the test project naming convention used in the repository.

Put every applicable central property in that same condition: OutputType, the framework runner opt-in, and TestingPlatformDotnetTestSupport on .NET 9 and earlier. Do not leave an unconditional runner property that still affects production projects.

Step 3: Enable the framework-specific MTP runner

Each framework has its own opt-in property. Add these in Directory.Build.props for consistency.

MSTest

Option A -- MSTest NuGet packages (3.2.0+):

<PropertyGroup>
  <EnableMSTestRunner>true</EnableMSTestRunner>
  <OutputType>Exe</OutputType>
</PropertyGroup>

Ensure the project references MSTest 3.2.0 or later. If the version is already 3.2.0+, no MSTest version upgrade is needed for MTP migration.

Option B -- MSTest.Sdk:

When using MSTest.Sdk, MTP is enabled by default -- no EnableMSTestRunner or OutputType Exe property is needed (the SDK sets both automatically). The only action is: if the project has <UseVSTest>true</UseVSTest>, remove it. That property forces the project to use VSTest instead of MTP.

NUnit

Requires NUnit3TestAdapter 5.0.0 or later.

1. Update NUnit3TestAdapter to 5.0.0+:

<PackageReference Include="NUnit3TestAdapter" Version="5.0.0" />

1. Enable the NUnit runner:

<PropertyGroup>
  <EnableNUnitRunner>true</EnableNUnitRunner>
  <OutputType>Exe</OutputType>
</PropertyGroup>

xUnit.net

Add a reference to YTest.MTP.XUnit2 -- this package provides MTP support for xUnit.net v2 projects without requiring an upgrade to xunit.v3. You must also set OutputType to Exe:

<PackageReference Include="YTest.MTP.XUnit2" Version="0.4.0" />

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

Note: YTest.MTP.XUnit2 preserves the VSTest --filter syntax, so no filter migration is needed for xUnit.net v2. It also supports --settings for runsettings (xunit-specific configurations only), xunit.runner.json, TRX reporting via --report-trx, and --treenode-filter.

xUnit.net v3

xUnit.net v3 (xunit.v3 package) has built-in MTP support. Enable it with:

<PropertyGroup>
  <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
</PropertyGroup>

Important: xUnit.net v3 on MTP does NOT support the VSTest --filter syntax. You must translate filters to xUnit.net v3's native filter options (see Step 5).

Step 4: Configure dotnet test integration

The dotnet test integration depends on the .NET SDK version.

.NET 10 SDK and later (recommended)

Use the native MTP mode by adding a test section to global.json:

{
  "sdk": {
    "version": "10.0.100"
  },
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

In this mode, dotnet test arguments are passed directly -- for example, dotnet test --report-trx.

Important: global.json does not support trailing commas. Ensure the JSON is strictly valid.

.NET 9 SDK and earlier

Use the VSTest mode of dotnet test command to run MTP test projects by adding this property in Directory.Build.props:

<PropertyGroup>
  <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>
</PropertyGroup>

Important: In this mode, you must use -- to separate dotnet test build arguments from MTP arguments. For example: dotnet test --no-build -- --list-tests.

Step 5: Update dotnet test command-line arguments

VSTest-specific arguments must be translated to MTP equivalents. Build-related arguments (-c, -f, --no-build, --nologo, -v, etc.) are unchanged.