Microsoft.Testing.Platform support in MSTest (MSTest runner)

Article
03/02/2025

MSTest supports running tests with both VSTest and Microsoft.Testing.Platform (MTP). The support for MTP is powered by the MSTest runner, which can run tests in all contexts (for example, continuous integration (CI) pipelines, CLI, Visual Studio Test Explorer, and VS Code Text Explorer). The MSTest runner is embedded directly in your MSTest test projects, and there are no other app dependencies, such as vstest.console or dotnet test, needed to run your tests. However, you can still run your tests using dotnet test.

The MSTest runner is open source and builds on the Microsoft.Testing.Platform library. You can find Microsoft.Testing.Platform code in the microsoft/testfx GitHub repository. The MSTest runner comes bundled with MSTest in 3.2.0 or newer.

Enable MSTest runner in an MSTest project

It's recommended to use MSTest SDK as it greatly simplifies your project configuration and updating the project, and it ensures a proper alignment of the versions of the platform (MSTest runner) and its extensions.

When you use MSTest SDK, by default you're opted in to using MSTest runner.

<Project Sdk="MSTest.Sdk/3.8.2">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

Alternatively, you can enable MSTest runner by adding the EnableMSTestRunner property and setting OutputType to Exe in your project file. You also need to ensure that you're using MSTest 3.2.0 or newer. We strongly recommend you update to the latest MSTest version available.

Consider the following example project file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- Enable the MSTest runner, this is an opt-in feature -->
    <EnableMSTestRunner>true</EnableMSTestRunner>
    <TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>

    <!--
      Displays error on console in addition to the log file. Note that this feature comes with a performance impact.
      For more information, visit https://learn.microsoft.com/dotnet/core/testing/unit-testing-platform-integration-dotnet-test#show-failure-per-test
      -->
    <TestingPlatformShowTestsFailure>true</TestingPlatformShowTestsFailure>

    <OutputType>Exe</OutputType>

    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!--
      MSTest meta package is the recommended way to reference MSTest.
      It's equivalent to referencing:
          Microsoft.NET.Test.Sdk
          MSTest.TestAdapter
          MSTest.TestFramework
          MSTest.Analyzers
      Starting with 3.8, it also includes:
          Microsoft.Testing.Extensions.TrxReport
          Microsoft.Testing.Extensions.CodeCoverage
    -->
    <PackageReference Include="MSTest" Version="3.8.0" />

    <!--
      Coverlet collector isn't compatible with MSTest runner, you can
      either switch to Microsoft CodeCoverage (as shown below),
      or switch to be using coverlet global tool
      https://github.com/coverlet-coverage/coverlet#net-global-tool-guide-suffers-from-possible-known-issue
    -->
    <PackageReference Include="Microsoft.Testing.Extensions.CodeCoverage"
                      Version="17.10.1" />
  </ItemGroup>

</Project>

Tip

To ensure all test projects in your solution use the MSTest runner, set the EnableMSTestRunner and TestingPlatformDotnetTestSupport properties in Directory.Build.props file instead of individual project files.

Configurations and filters

.runsettings

The MSTest runner supports the runsettings through the command-line option --settings. For the full list of supported MSTest entries, see Configure MSTest: Runsettings. The following commands show various usage examples.

Using dotnet run:

dotnet run --project Contoso.MyTests -- --settings config.runsettings

Using dotnet exec:

dotnet exec Contoso.MyTests.dll --settings config.runsettings

-or-

dotnet Contoso.MyTests.dll --settings config.runsettings

Using the executable:

Contoso.MyTests.exe --settings config.runsettings

Tests filter

You can provide the tests filter seamlessly using the command line option --filter. The following commands show some examples.