VSTest -> Microsoft.Testing.Platform Migration

dotnet test

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

.csproj

.sln

.slnx

dotnet test

dotnet --version

vstest.console

dotnet test

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

:

xml

<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

Directory.Build.props

MSTest

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

MSTest.Sdk

EnableMSTestRunner

OutputType Exe

<UseVSTest>true</UseVSTest>

NUnit

NUnit3TestAdapter

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

YTest.MTP.XUnit2

OutputType

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

<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

dotnet test

.NET 10 SDK and later (recommended)

test

global.json

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

dotnet test

dotnet test --report-trx

Important:

global.json

does not support trailing commas. Ensure the JSON is strictly valid.

.NET 9 SDK and earlier

dotnet test

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

-c

-f

--no-build

--nologo

-v

--test-adapter-path

--blame

--blame-crash

--crashdump

Microsoft.Testing.Extensions.CrashDump

--blame-crash-dump-type <TYPE>

--crashdump-type <TYPE>

--blame-hang

--hangdump

Microsoft.Testing.Extensions.HangDump

--blame-hang-dump-type <TYPE>

--hangdump-type <TYPE>

--blame-hang-timeout <TIMESPAN>

--hangdump-timeout <TIMESPAN>

--collect "Code Coverage;Format=cobertura"

--coverage --coverage-output-format cobertura

-d|--diag <LOG_FILE>

--diagnostic

--filter <EXPRESSION>

--filter <EXPRESSION>

YTest.MTP.XUnit2

-l|--logger trx

--report-trx

Microsoft.Testing.Extensions.TrxReport

--results-directory <DIR>

--results-directory <DIR>

-s|--settings <FILE>

--settings <FILE>

.runsettings

-t|--list-tests

--list-tests

-- <RunSettings args>

--test-parameter

Filter migration

YTest.MTP.XUnit2

--filter

--filter

xUnit.net v3 filter flags

--filter-class "name"

*

--filter-not-class "name"

--filter-method "name"

--filter-not-method "name"

--filter-namespace "name"

--filter-not-namespace "name"

--filter-trait "name=value"

--filter-not-trait "name=value"

--filter-class Foo Bar

VSTest → xUnit.net v3 filter translation table

--filter

FullyQualifiedName~ClassName

--filter-class *ClassName*

FullyQualifiedName=Ns.Class.Method

--filter-method Ns.Class.Method

Name=MethodName

--filter-method *MethodName*

Category=Value

--filter-trait "Category=Value"

--filter-query "expr"

xUnit.net v3 query filter language

--filter-query

/<assemblyFilter>/<namespaceFilter>/<classFilter>/<methodFilter>[traitName=traitValue]

*

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-class

and

--filter-trait

, both conditions must match (AND behavior). For complex expressions, use

--filter-query

with the path-segment syntax. See the xUnit.net query filter language docs for full reference.

Step 6: Install MTP extension packages (if needed)

<!-- 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" />

Step 7: Update CI/CD pipelines

Azure DevOps

VSTest@3

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'

--

- task: DotNetCoreCLI@2
  displayName: Run tests
  inputs:
    command: 'test'
    arguments: '--no-build -- --report-trx --results-directory $(Agent.TempDirectory)'

GitHub Actions

dotnet test

Replace vstest.console.exe

vstest.console.exe

dotnet test

Step 8: Handle behavioral differences

Zero tests exit code

• Pass

  --ignore-exit-code 8

  when running tests
• Add to

  Directory.Build.props

  :

<PropertyGroup>
  <TestingPlatformCommandLineArguments>$(TestingPlatformCommandLineArguments) --ignore-exit-code 8</TestingPlatformCommandLineArguments>
</PropertyGroup>

• Use environment variable:

  TESTINGPLATFORM_EXITCODE_IGNORE=8

Step 9: Remove VSTest-only packages (optional)

• 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 runner

Note: If you need to maintain VSTest compatibility during a transition period, keep these packages.

Step 10: Verify

1. Run

   dotnet build

   -- confirm zero errors
2. Run

   dotnet test

   -- confirm all tests pass
3. Compare test pass/fail counts to the pre-migration baseline
4. Run the test executable directly (e.g.,

   ./bin/Debug/net8.0/MyTests.exe

   ) -- confirm it works
5. Verify CI pipeline produces the expected test result artifacts (TRX files, code coverage, crash dumps)
6. Test that Test Explorer in Visual Studio (17.14+) or VS Code discovers and runs tests

Validation

• All test projects use MTP runner (no VSTest-only configuration remains)

• dotnet build

  completes with zero errors

• dotnet test

  passes all tests and test counts match pre-migration baseline
• Test executable runs directly (e.g.,

  ./bin/Debug/net8.0/MyTests.exe

  )
• CI pipeline produces expected test result artifacts (TRX files, code coverage, crash dumps)
• Test Explorer in Visual Studio or VS Code discovers and runs tests
• No

  vstest.console.exe

  invocations remain in CI scripts

• <OutputType>Exe</OutputType>

  is set for all non-MSTest.Sdk test projects

Common Pitfalls

dotnet test

--

dotnet test -- --report-trx

--ignore-exit-code 8

Microsoft.NET.Test.Sdk

dotnet test

<OutputType>Exe</OutputType>

Condition="'$(IsTestProject)' == 'true'"

Directory.Build.props

IsTestProject

Directory.Build.props

$(MSBuildProjectName.EndsWith('.Tests'))

Next Steps

• Use

  run-tests

  for running tests on the new MTP platform
• Use

  mtp-hot-reload

  for iterative test fixing with hot reload on MTP

More Info

• Test platforms overview
• Migrate from VSTest to Microsoft.Testing.Platform
• Microsoft.Testing.Platform overview
• Testing with dotnet test
• Microsoft.Testing.Platform CLI options
• Microsoft.Testing.Platform extensions