---

name: migrate-vstest-to-mtp description: > Use this skill before answering, planning, or editing whenever .NET tests or CI are switching from VSTest to Microsoft.Testing.Platform (MTP), or an MTP migration behaves differently. Triggers include "switch from VSTest"; MSTest/NUnit/xUnit MTP enablement; OutputType=Exe only for test projects in Directory.Build.props; EnableMSTestRunner, EnableNUnitRunner, UseMicrosoftTestingPlatformRunner, or YTest.MTP.XUnit2; .NET 10 global.json test.runner and TestingPlatformDotnetTestSupport; translating VSTest filters, logger, coverage, blame, or dump arguments; replacing VSTest@3; and exit code 8 or zero tests. Also use for xUnit v3 MTP filters during a v2-to-v3 upgrade. Do not use for framework conversion, TFM, UWP, or WinUI. license: MIT

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

| Input | Required | Description | |-------|----------|-------------| | Project or solution path | No | The .csproj, .sln, or .slnx entry point containing test projects. Discover it yourself by globbing the working directory; ask only when nothing is found or the choice is genuinely ambiguous | | Test framework | No | MSTest, NUnit, xUnit.net v2, or xUnit.net v3. Auto-detected from package references | | .NET SDK version | No | Determines dotnet test integration mode. Prefer the repository's global.json or explicitly stated CI SDK; use host dotnet --version only when the repository does not pin or state one | | CI/CD pipeline files | No | Paths to pipeline definitions that invoke vstest.console or dotnet test |

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.

| VSTest argument | MTP equivalent | Notes | |-----------------|----------------|-------| | --test-adapter-path | Not applicable | MTP does not use external adapter discovery | | --blame | Not applicable | | | --blame-crash | --crashdump | Requires Microsoft.Testing.Extensions.CrashDump NuGet