Rediger

MSTest SDK configuration

This article covers advanced configuration options for MSTest.Sdk. For basic setup and getting started, see Get started with MSTest.

Important

By default, MSTest.Sdk uses the MSTest runner with MTP, including with dotnet test. This requires modifying your CI and local CLI calls, and also impacts the available entries of the .runsettings. You can keep the old integrations and tools by switching to VSTest.

MSTest.Sdk sets EnableMSTestRunner and TestingPlatformDotnetTestSupport to true by default. For more information about dotnet test and its different modes, see Testing with dotnet test.

Test utility helper libraries

If the project that uses MSTest.Sdk is intended to be a test utility helper library, and doesn't by itself contain any runnable tests, the project should have <IsTestApplication>false</IsTestApplication>.

Select the runner

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

Extend MTP

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

Microsoft.Testing.Platform 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:

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

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

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

</Project>
Extension/Profile None Default AllMicrosoft
Code Coverage ✔️ ✔️
Crash Dump ✔️
Fakes ✔️¹
Hang Dump ✔️
Hot Reload ✔️
Retry ✔️
Trx ✔️ ✔️
AzureDevOpsReport ✔️²

¹ MSTest.Sdk 3.7.0+ ² MSTest.Sdk 3.11.0+

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/4.1.0">

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

</Project>

For a list of all available extensions, see MTP features.

Starting with MSTest.Sdk 4.3, enable the experimental JUnit report extension with <EnableMicrosoftTestingExtensionsJUnitReport>true</EnableMicrosoftTestingExtensionsJUnitReport>, then pass --report-junit when you run the test application. The extension is available only with Microsoft.Testing.Platform and isn't included in the Default or AllMicrosoft profiles.

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/4.1.0">

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

</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 Aspire

Aspire is an opinionated, cloud-ready stack for building observable, production ready, distributed applications. Aspire is delivered through a collection of NuGet packages that handle specific cloud-native concerns. For more information, see the 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/4.1.0">

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

</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/4.1.0">

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

</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": "4.1.0"
    }
}

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 MTP (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.

If you're using the VSTest mode of dotnet test, 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 -- --report-trx --results-directory $(Agent.TempDirectory) --coverage'

Experimental features

The following MSTest 4.3 features are experimental. Their public APIs are subject to change, and they're surfaced behind experimental diagnostics, so opting in requires acknowledging the corresponding diagnostic ID. Use them with that caveat in mind.

Reflection source generator

Note

Introduced in MSTest 4.3.0 (experimental).

The MSTest reflection source generator discovers tests at compile time instead of relying on runtime reflection, which makes test projects compatible with trimming and Native AOT. Enable it by adding the MSTest.SourceGeneration package. When the source generator is active, test classes must declare [TestClass] directly rather than inherit it; the MSTEST0069 analyzer flags classes that rely on an inherited [TestClass].

Starting with MSTest 4.3.2, MSTestSourceGenMode defaults to ReflectionFree for trimmed and Native AOT projects.

Starting with MSTest 4.4, reflection-free generation materializes complete inherited attribute metadata, including AttributeUsage and AllowMultiple. When the generator can't materialize metadata statically, MSTest falls back to reflection where the runtime supports it.

Programmatic test filtering with ITestFilter

Note

Introduced in MSTest 4.3.0 (experimental).

The experimental ITestFilter extension point, registered through [TestFilterProviderAttribute], lets you decide programmatically whether each test runs, before any test class is loaded. This is useful for custom selection logic that can't be expressed with command-line filters.

Implement ITestFilter.Filter(TestFilterContext) to inspect metadata without loading the test class:

public sealed class MyFilter : ITestFilter
{
    public TestFilterResult Filter(TestFilterContext context) =>
        context.DisplayName.Contains("Nightly", StringComparison.Ordinal)
            ? TestFilterResult.Run : TestFilterResult.Drop;
}

Return TestFilterResult.Run to run the test, Drop to omit it without a result, or Skip(reason) to report a skipped result. MSTest can call one filter instance concurrently, so implementations must be thread-safe. Command-line and test-explorer filters run before ITestFilter, while [Ignore] is evaluated afterward.

Starting with MSTest 4.4, .NET projects can use the generic, type-safe registration form [assembly: TestFilterProvider<MyFilter>]. The compiler then enforces that MyFilter implements ITestFilter and has a public parameterless constructor. The generic attribute isn't available for .NET Framework. For a multi-targeted project, select the generic or non-generic form with a target-framework preprocessor symbol.

#if NET
[assembly: TestFilterProvider<MyFilter>]
#else
[assembly: TestFilterProvider(typeof(MyFilter))]
#endif

Starting with MSTest 4.4, the MSTEST0081 analyzer fully validates the non-generic registration form. For the generic form, it still reports generic filter types and assemblies that register more than one provider.

TestRun.Current and planned tests

Note

Introduced in MSTest 4.3.0 (experimental).

The experimental TestRun.Current API (from RFC 014) exposes information about the current run, including the set of planned tests, so extensions and fixtures can inspect what's scheduled to execute.

Known limitations

The NuGet-provided MSBuild SDKs (including MSTest.Sdk) have limited tooling support when it comes to updating their version, meaning that the usual NuGet update and Visual Studio UI for managing NuGet packages doesn't work as expected. You'll need to manually update the version in the global.json file and in the project file. (This applies even if you use Dependabot due to issues dependabot-core#12824 and dependabot-core#8615.)

See also

  • Last updated on