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.

• 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

• 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

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

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.

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>

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

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.

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

.

• task: VSTest@3 inputs: testAssemblyVer2: '**/*Tests.dll' runSettingsFile: 'test.runsettings'

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

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

• 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

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

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

• 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

• Use

  run-tests

  for running tests on the new MTP platform
• Use

  mtp-hot-reload

  for iterative test fixing with hot reload on MTP

• 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