Edit

Share via

MSTest SDK overview

  • Article

Introduced in .NET 9, MSTest.Sdk is a MSBuild project SDK for building MSTest apps. It's possible to build a MSTest app without this SDK, however, the MSTest SDK is:

  • Tailored towards providing a first-class experience for testing with MSTest.
  • The recommended target for most users.
  • Easy to configure for other users.

The MSTest SDK discovers and runs your tests using the MSTest runner.

You can enable MSTest.Sdk in a project by simply updating the Sdk attribute of the Project node of your project:

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

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
    </PropertyGroup>

    <!-- references to the code to test -->

</Project>

Note

/3.3.1 is given as example as it's the first version of the SDK, but it can be replaced with any newer version.

To simplify handling of versions, we recommend setting the SDK version at solution level using the global.json file. For example, your project file would look like:

<Project Sdk="MSTest.Sdk">

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
    </PropertyGroup>

    <!-- references to the code to test -->

</Project>

Then, specify the MSTest.Sdk version in the global.json file as follows:

{
    "msbuild-sdks": {
        "MSTest.Sdk": "3.3.1"
    }
}

For more information, see Use MSBuild project SDKs.

When you build the project, all the needed components are restored and installed using the standard NuGet workflow set by your project.

You don't need anything else to build and run your tests and you can use the same tooling (for example, dotnet test or Visual Studio) used by a "classic" MSTest project.

Important

By switching to the MSTest.Sdk, you opt in to using the MSTest runner, including with dotnet test. That requires modifying your CI and local CLI calls, and also impacts the available entries of the .runsettings. You can use MSTest.Sdk and still keep the old integrations and tools by instead switching the runner.

Select the runner

By default, MSTest SDK relies on MSTest runner, but you can switch to VSTest by adding the property <UseVSTest>true</UseVSTest>.

Extend MSTest runner

You can customize MSTest runner experience through a set of NuGet package extensions. To simplify and improve this experience, MSTest SDK introduces two features:

MSTest runner profile

The concept of profiles allows you to select the default set of configurations and extensions that will be applied to your test project.

You can set the profile using the property TestingExtensionsProfile with one of the following three profiles:

  • Default - Enables the recommended extensions for this version of MSTest.SDK. This is the default when the property isn't set explicitly.
  • None - No extensions are enabled.
  • AllMicrosoft - Enable all extensions shipped by Microsoft (including extensions with a restrictive license).

Here's a full example, using the None profile:

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

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <TestingExtensionsProfile>None</TestingExtensionsProfile>
    </PropertyGroup>

    <!-- references to the code to test -->

</Project>

Enable or disable extensions

Extensions can be enabled and disabled by MSBuild properties with the pattern Enable[NugetPackageNameWithoutDots].

For example, to enable the crash dump extension (NuGet package Microsoft.Testing.Extensions.CrashDump), you can use the following property EnableMicrosoftTestingExtensionsCrashDump set to true:

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

<PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <EnableMicrosoftTestingExtensionsCrashDump>true</EnableMicrosoftTestingExtensionsCrashDump>
</PropertyGroup>

<!-- references to the code to test -->

</Project>

For a list of all available extensions, see Microsoft.Testing.Platform extensions.

Warning

It's important to review the licensing terms for each extension as they might vary.

Enabled and disabled extensions are combined with the extensions provided by your selected extension profile.

This property pattern can be used to enable an additional extension on top of the implicit Default profile (as seen in the previous CrashDumpExtension example).

You can also disable an extension that's coming from the selected profile. For example, disable the MS Code Coverage extension by setting <EnableMicrosoftTestingExtensionsCodeCoverage>false</EnableMicrosoftTestingExtensionsCodeCoverage>:

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

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <EnableMicrosoftTestingExtensionsCodeCoverage>false</EnableMicrosoftTestingExtensionsCodeCoverage>
    </PropertyGroup>

    <!-- references to the code to test -->

</Project>

Features

Outside of the selection of the runner and runner-specific extensions, MSTest.Sdk also provides additional features to simplify and enhance your testing experience.

Test with .NET Aspire

.NET Aspire is an opinionated, cloud-ready stack for building observable, production ready, distributed applications. .NET Aspire is delivered through a collection of NuGet packages that handle specific cloud-native concerns. For more information, see the .NET Aspire docs.

Note

This feature is available from MSTest.Sdk 3.4.0

By setting the property EnableAspireTesting to true, you can bring all dependencies and default using directives you need for testing with Aspire and MSTest.

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

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <EnableAspireTesting>true</EnableAspireTesting>
    </PropertyGroup>

    <!-- references to the code to test -->

</Project>

Test with Playwright

Playwright enables reliable end-to-end testing for modern web apps. For more information, see the official Playwright docs.

Note

This feature is available from MSTest.Sdk 3.4.0

By setting the property EnablePlaywright to true you can bring in all the dependencies and default using directives you need for testing with Playwright and MSTest.

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

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <EnablePlaywright>true</EnablePlaywright>
    </PropertyGroup>

    <!-- references to the code to test -->

</Project>

Migrate to MSTest SDK

Consider the following steps that are required to migrate to the MSTest SDK.

Update your project

When migrating an existing MSTest test project to MSTest SDK, start by replacing the Sdk="Microsoft.NET.Sdk" entry at the top of your test project with Sdk="MSTest.Sdk"

- Sdk="Microsoft.NET.Sdk"
+ Sdk="MSTest.Sdk"

Add the version to your global.json:

{
    "msbuild-sdks": {
        "MSTest.Sdk": "3.3.1"
    }
}

You can then start simplifying your project.

Remove default properties:

- <EnableMSTestRunner>true</EnableMSTestRunner>
- <OutputType>Exe</OutputType>
- <IsPackable>false</IsPackable>
- <IsTestProject>true</IsTestProject>

Remove default package references:

- <PackageReference Include="MSTest"
- <PackageReference Include="MSTest.TestFramework"
- <PackageReference Include="MSTest.TestAdapter"
- <PackageReference Include="MSTest.Analyzers"
- <PackageReference Include="Microsoft.NET.Test.Sdk"

Finally, based on the extensions profile you're using, you can also remove some of the Microsoft.Testing.Extensions.* packages.

Update your CI

Once you've updated your projects, if you're using MSTest runner (default) and if you rely on dotnet test to run your tests, you must update your CI configuration. For more information and to guide your understanding of all the required changes, see dotnet test integration.

Here's an example update when using the DotNetCoreCLI task in Azure DevOps:

\- task: DotNetCoreCLI@2
  inputs:
    command: 'test'
    projects: '**/**.sln'
-    arguments: '--configuration Release'
+    arguments: '--configuration Release -p:TestingPlatformCommandLineArguments="--report-trx --results-directory $(Agent.TempDirectory) --coverage"'

See also