Edit

MSTest runner overview

  • Article

The MSTest runner is a lightweight and portable alternative to VSTest for running 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.

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

Enable MSTest runner in a MSTest project

It's recommended to use MSTest SDK as it greatly simplifies your project configuration, the updating of the project and 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.3.1">

  <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-preview.23623.1 or newer.

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>
    <OutputType>Exe</OutputType>

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

    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
  </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
    -->
    <PackageReference Include="MSTest" Version="3.2.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>

Configurations and filters

.runsettings

The MSTest runner supports the runsettings through the command-line option --settings. The following commands show 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.

Using dotnet run:

dotnet run --project Contoso.MyTests -- --filter "FullyQualifiedName~UnitTest1|TestCategory=CategoryA"

Using dotnet exec:

dotnet exec Contoso.MyTests.dll --filter "FullyQualifiedName~UnitTest1|TestCategory=CategoryA"

-or-

dotnet Contoso.MyTests.dll --filter "FullyQualifiedName~UnitTest1|TestCategory=CategoryA"

Using the executable:

Contoso.MyTests.exe --filter "FullyQualifiedName~UnitTest1|TestCategory=CategoryA"