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.

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 -- migration is done
• 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

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. Check the .NET SDK version (dotnet --version) -- this determines how dotnet test integrates with MTP
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.

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.