MSTest SDK overview
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 providing 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. 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, you would have a global.json file that specifies the MSTest.Sdk
version 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've fully opted-in to using the MSTest runner, including with dotnet test which requires modifying your CI, 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 easily 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>
This page lists all extensions available.
Warning
Please review the licensing terms for each extension as they may vary.
Enabled and disabled extensions are combined with the extensions provided by your selected extension profile.
This can be used to enable an additional extension on top of the implicit Default
profile (as seen in the previous CrashDumpExtension example).
Or to disable an extension that is coming from the selected profile. In this case disabling 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.
.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 usings you would 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>
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 all dependencies and default usings you would 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>
Migrating to MSTest SDK
Consider the following steps that are required to migrate to the MSTest SDK.
Update your project(s)
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/3.3.1"
- 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.
Removing default properties:
- <EnableMSTestRunner>true</EnableMSTestRunner>
- <OutputType>Exe</OutputType>
- <IsPackable>false</IsPackable>
- <IsTestProject>true</IsTestProject>
Removing 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 have to update your CI configuration. For more information, see dotnet test integration to guide your understanding of all the required changes.
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"'