From dotnet-test
Migrates .NET test projects from VSTest to Microsoft.Testing.Platform (MTP) for MSTest, NUnit, xUnit v2/v3. Updates configs, CLI filters, CI/CD pipelines.
npx claudepluginhub dotnet/skills --plugin dotnet-testThis skill uses the workspace's default tool permissions.
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.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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.
dotnet run / dotnet watch / direct executable execution for test projectsvstest.console.exe with dotnet test on MTPdotnet test arguments from VSTest syntax to MTP syntaxmigrate-mstest-v1v2-to-v3 or migrate-mstest-v3-to-v4| Input | Required | Description |
|---|---|---|
| Project or solution path | Yes | The .csproj, .sln, or .slnx entry point containing test projects |
| 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. Auto-detected via dotnet --version |
| CI/CD pipeline files | No | Paths to pipeline definitions that invoke vstest.console or dotnet test |
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.NUnit3TestAdapterxunit and xunit.runner.visualstudiodotnet --version) -- this determines how dotnet test integrates with MTPDirectory.Build.props file exists at the solution or repo root -- all MTP properties should go there for consistencyvstest.console.exe usage in CI scripts or pipeline definitionsdotnet test arguments in CI scripts: --filter, --logger, --collect, --settings, --blame*dotnet test to establish a baseline of test pass/fail countsCritical: Always set MTP properties in
Directory.Build.propsat the solution or repo root -- never per-project. This prevents inconsistent configuration where some projects use VSTest and others use MTP (an unsupported scenario).
Note: MTP requires test projects to have
<OutputType>Exe</OutputType>. OnlyMSTest.Sdksets this automatically. For all other setups (MSTest NuGet packages withEnableMSTestRunner, NUnit withEnableNUnitRunner, xUnit.net withYTest.MTP.XUnit2), you must set<OutputType>Exe</OutputType>explicitly -- either per-project or inDirectory.Build.propswith a condition that targets only test projects.
Each framework has its own opt-in property. Add these in Directory.Build.props for consistency.
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.
Requires NUnit3TestAdapter 5.0.0 or later.
NUnit3TestAdapter to 5.0.0+:<PackageReference Include="NUnit3TestAdapter" Version="5.0.0" />
<PropertyGroup>
<EnableNUnitRunner>true</EnableNUnitRunner>
<OutputType>Exe</OutputType>
</PropertyGroup>
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.XUnit2preserves the VSTest--filtersyntax, so no filter migration is needed for xUnit.net v2. It also supports--settingsfor runsettings (xunit-specific configurations only),xunit.runner.json, TRX reporting via--report-trx, and--treenode-filter.
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
--filtersyntax. You must translate filters to xUnit.net v3's native filter options (see Step 5).
The dotnet test integration depends on the .NET SDK version.
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.jsondoes not support trailing commas. Ensure the JSON is strictly valid.
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 separatedotnet testbuild arguments from MTP arguments. For example:dotnet test --no-build -- --list-tests.
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 package |
--blame-crash-dump-type <TYPE> | --crashdump-type <TYPE> | Requires CrashDump extension |
--blame-hang | --hangdump | Requires Microsoft.Testing.Extensions.HangDump NuGet package |
--blame-hang-dump-type <TYPE> | --hangdump-type <TYPE> | Requires HangDump extension |
--blame-hang-timeout <TIMESPAN> | --hangdump-timeout <TIMESPAN> | Requires HangDump extension |
--collect "Code Coverage;Format=cobertura" | --coverage --coverage-output-format cobertura | Per-extension arguments |
-d|--diag <LOG_FILE> | --diagnostic | |
--filter <EXPRESSION> | --filter <EXPRESSION> | Same syntax for MSTest, NUnit, and xUnit.net v2 (with YTest.MTP.XUnit2). For xUnit.net v3, see filter migration below |
-l|--logger trx | --report-trx | Requires Microsoft.Testing.Extensions.TrxReport NuGet package |
--results-directory <DIR> | --results-directory <DIR> | Same |
-s|--settings <FILE> | --settings <FILE> | MSTest and NUnit still support .runsettings |
-t|--list-tests | --list-tests | Same |
-- <RunSettings args> | --test-parameter | Applicable only to MSTest and NUnit |
MSTest, NUnit, and xUnit.net v2 (with YTest.MTP.XUnit2): The VSTest --filter syntax is identical on both VSTest and MTP. No changes needed.
xUnit.net v3 (native MTP): xUnit.net v3 does NOT support the VSTest --filter syntax on MTP. See the VSTest -> MTP filter translation section in references/filter-syntax.md for the complete translation table. Key translation example:
# VSTest
dotnet test --filter "FullyQualifiedName~IntegrationTests&Category=Smoke"
# xUnit.net v3 MTP -- using individual filters (AND behavior)
dotnet test -- --filter-class *IntegrationTests* --filter-trait "Category=Smoke"
# xUnit.net v3 MTP -- using query language (assembly/namespace/class/method[trait])
dotnet test -- --filter-query "/*/*/*IntegrationTests*/*[Category=Smoke]"
Note: When combining
--filter-classand--filter-trait, both conditions must match (AND behavior). For complex expressions, use--filter-querywith the path-segment syntax. See the xUnit.net query filter language docs for full reference.
If CI scripts use TRX reporting, crash dumps, or hang dumps, add the corresponding NuGet packages:
<!-- TRX report generation (replaces --logger trx) -->
<PackageReference Include="Microsoft.Testing.Extensions.TrxReport" Version="1.6.2" />
<!-- Crash dump collection (replaces --blame-crash) -->
<PackageReference Include="Microsoft.Testing.Extensions.CrashDump" Version="1.6.2" />
<!-- Hang dump collection (replaces --blame-hang) -->
<PackageReference Include="Microsoft.Testing.Extensions.HangDump" Version="1.6.2" />
<!-- Code coverage (replaces --collect "Code Coverage") -->
<PackageReference Include="Microsoft.Testing.Extensions.CodeCoverage" Version="17.13.0" />
If using the VSTest task (VSTest@3): Replace with the .NET Core CLI task (DotNetCoreCLI@2):
# Before (VSTest task)
- task: VSTest@3
inputs:
testAssemblyVer2: '**/*Tests.dll'
runSettingsFile: 'test.runsettings'
# After (.NET Core CLI task)
- task: DotNetCoreCLI@2
displayName: Run tests
inputs:
command: 'test'
arguments: '--no-build --configuration Release'
If already using DotNetCoreCLI@2: Update arguments per Step 5 translations. Remember the -- separator on .NET 9 and earlier:
- task: DotNetCoreCLI@2
displayName: Run tests
inputs:
command: 'test'
arguments: '--no-build -- --report-trx --results-directory $(Agent.TempDirectory)'
Update dotnet test invocations in workflow files with the same argument translations from Step 5.
If any script invokes vstest.console.exe directly, replace it with dotnet test. The test projects are now executables and can also be run directly.
VSTest silently succeeds when zero tests are discovered. MTP fails with exit code 8. Options:
--ignore-exit-code 8 when running testsDirectory.Build.props:<PropertyGroup>
<TestingPlatformCommandLineArguments>$(TestingPlatformCommandLineArguments) --ignore-exit-code 8</TestingPlatformCommandLineArguments>
</PropertyGroup>
TESTINGPLATFORM_EXITCODE_IGNORE=8Once migration is complete and verified, remove packages that are only needed for VSTest:
Microsoft.NET.Test.Sdk -- not needed for MTP (MSTest.Sdk v4 already omits it by default)xunit.runner.visualstudio -- only needed for VSTest discovery of xUnit.net (not needed when using YTest.MTP.XUnit2)NUnit3TestAdapter VSTest-only features -- the adapter is still needed but only for the MTP runnerNote: If you need to maintain VSTest compatibility during a transition period, keep these packages.
dotnet build -- confirm zero errorsdotnet test -- confirm all tests pass./bin/Debug/net8.0/MyTests.exe) -- confirm it worksdotnet build completes with zero errorsdotnet test passes all tests and test counts match pre-migration baseline./bin/Debug/net8.0/MyTests.exe)vstest.console.exe invocations remain in CI scripts<OutputType>Exe</OutputType> is set for all non-MSTest.Sdk test projects| Pitfall | Solution |
|---|---|
| Mixing VSTest and MTP projects in the same solution | Migrate all test projects together -- mixed mode is unsupported |
dotnet test arguments ignored on .NET 9 and earlier | Use -- to separate build args from MTP args: dotnet test -- --report-trx |
| Exit code 8 on CI without failures | MTP fails when zero tests run; use --ignore-exit-code 8 or fix test discovery |
| MSTest.Sdk v4 + vstest.console no longer works | MSTest.Sdk v4 no longer adds Microsoft.NET.Test.Sdk -- add it explicitly or switch to dotnet test |
Missing <OutputType>Exe</OutputType> | Required for all setups except MSTest.Sdk (which sets it automatically) |
run-tests for running tests on the new MTP platformmtp-hot-reload for iterative test fixing with hot reload on MTP