Migrate from Microsoft.Testing.Platform v1 to v2

The stable version Microsoft.Testing.Platform v2 is now available. This migration guide explores what's changed in Microsoft.Testing.Platform v2 and how you can migrate to this version.

Source breaking changes

These are breaking changes that might cause build errors after migration.

Dropped unsupported target frameworks

Support for target frameworks from .NET Core 3.1 to .NET 7 is dropped. The minimum supported .NET version is .NET 8. This change doesn't affect .NET Framework. .NET Framework 4.6.2 continues to be the minimum supported .NET Framework target.

Removed obsolete types

The following types were marked obsolete in MTP v1. In MTP v2, they are removed completely:

• ITestApplicationLifecycleCallbacks: use ITestHostApplicationLifetime instead.
• TestNodeFileArtifact: use FileArtifactProperty instead.
• KeyValuePairStringProperty: use TestMetadataProperty instead.
• TestSessionContext.Client: use IClientInfo instead.

This breaking change doesn't affect typical users of test frameworks. It only affects test framework authors and extension authors.

API signature changes

• A CancellationToken parameter was added to IOutputDevice.DisplayAsync(IOutputDeviceDataProducer, IOutputDeviceData).
• Methods in ITestSessionLifetimeHandler interface are changed to have an ITestSessionContext parameter instead of both SessionUid and CancellationToken parameters.
• IDataConsumer is moved from Microsoft.Testing.Platform.Extensions.TestHost namespace to Microsoft.Testing.Platform.Extensions.

This breaking change doesn't affect typical users of test frameworks. It only affects test framework authors and extension authors.

Behavior breaking changes

These are breaking changes that might affect the behavior at runtime.

Compatibility with VSTest-based dotnet test

The dotnet test command has two implementations:

• VSTest-based implementation: this was the only implementation up to .NET 9 SDK.
• MTP-based implementation: this was added starting in .NET 10 SDK.

Running MTP test projects with .NET 10 SDK now requires opting-in to the MTP-based dotnet test and can no longer be run with the VSTest-based implementation, which was previously enabled by TestingPlatformDotnetTestSupport MSBuild property in MTP v1.

To opt-in the MTP-based implementation, create global.json in repository or solution root (or update existing global.json if you have one already), to have test runner set as Microsoft.Testing.Platform, as shown in the following example:

{
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

Attempting to run the VSTest-based dotnet test with MTP v2 will produce the following error:

Testing with VSTest target is no longer supported by Microsoft.Testing.Platform on .NET 10 SDK and later. If you use dotnet test, you should opt-in to the new dotnet test experience. For more information, see https://aka.ms/dotnet-test-mtp-error

Rename of command-line options

• The --diagnostic-output-fileprefix command-line option was renamed to --diagnostic-file-prefix.
• The --diagnostic-filelogger-synchronouswrite command-line option was renamed to --diagnostic-synchronous-write.