diff --git a/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md b/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md index 37e690a993f9a..75cb30d95fe02 100644 --- a/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md +++ b/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md @@ -1,26 +1,29 @@ --- -title: Use Microsoft.Testing.Platform with VSTest mode of `dotnet test` +title: Use Microsoft.Testing.Platform in the VSTest mode of `dotnet test` description: Learn how to run Microsoft.Testing.Platform tests through dotnet test. author: nohwnd ms.author: jajares ms.date: 03/26/2025 --- -# Use Microsoft.Testing.Platform with VSTest mode of `dotnet test` +# Use Microsoft.Testing.Platform in the VSTest mode of `dotnet test` -This article describes `dotnet test` integration for Microsoft.Testing.Platform that is provided by Microsoft.Testing.Platform.MSBuild when running with VSTest mode of `dotnet test`. +This article explains the integration of `dotnet test` for Microsoft.Testing.Platform, which is provided by Microsoft.Testing.Platform.MSBuild when running in the VSTest mode of `dotnet test`. -Before reading this article, it's advised to read [Testing with dotnet test](unit-testing-with-dotnet-test.md) first. +Before diving into this article, it's recommended to first read [Testing with dotnet test](unit-testing-with-dotnet-test.md), which explains the two modes of `dotnet test` (VSTest and MTP modes). -By default, `dotnet test` is using VSTest behavior to run tests. To enable support for `Microsoft.Testing.Platform` in `dotnet test`, there are two options: +By default, `dotnet test` uses VSTest to run tests. To enable support for `Microsoft.Testing.Platform` in `dotnet test`, you have two options: -1. Use `dotnet test` in VSTest mode, and specify `true` MSBuild property in your project file. -2. Use `dotnet test` in MTP mode, and enjoy more native support of MTP in `dotnet test`. This is only supported starting with .NET 10 SDK. +1. Use `dotnet test` in VSTest mode and specify `true` MSBuild property in your project file. +2. Use `dotnet test` in MTP mode for more native support of MTP in `dotnet test`, which is only supported starting with the .NET 10 SDK. -Both of these options are explained in details in the [Testing with dotnet test](unit-testing-with-dotnet-test.md) article. +Both options are explained in detail in the [Testing with dotnet test](unit-testing-with-dotnet-test.md) article. > [!IMPORTANT] -> The remaining of this article is specific to the first option. +> The rest of this article is specific to the VSTest mode of `dotnet test`. +> +> [!CAUTION] +> Starting with .NET 10 SDK, it's recommended to not use the VSTest mode of `dotnet test` when running with Microsoft.Testing.Platform. ## Show failure per test diff --git a/docs/core/testing/unit-testing-mstest-sdk.md b/docs/core/testing/unit-testing-mstest-sdk.md index fae458543daa1..fc27fba9e0064 100644 --- a/docs/core/testing/unit-testing-mstest-sdk.md +++ b/docs/core/testing/unit-testing-mstest-sdk.md @@ -61,7 +61,7 @@ You don't need anything else to build and run your tests and you can use the sam > [!IMPORTANT] > By switching to the `MSTest.Sdk`, you opt in to using the [MSTest runner (enables Microsoft.Testing.Platform for MSTest)](./unit-testing-mstest-runner-intro.md), including with [dotnet test](./microsoft-testing-platform-integration-dotnet-test.md). 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). -> In more details, MSTest.Sdk, by default, will set `EnableMSTestRunner` and `TestingPlatformDotnetTestSupport` to true. For more information about dotnet test and its different modes for running Microsoft.Testing.Platform, see [Testing with dotnet test](./unit-testing-with-dotnet-test.md). +> By default, MSTest.Sdk sets `EnableMSTestRunner` and `TestingPlatformDotnetTestSupport` to true. For more information about dotnet test and its different modes for running Microsoft.Testing.Platform, see [Testing with dotnet test](./unit-testing-with-dotnet-test.md). ## Select the runner diff --git a/docs/core/testing/unit-testing-with-dotnet-test.md b/docs/core/testing/unit-testing-with-dotnet-test.md index 7335dfc070b2c..64505d8d07fcf 100644 --- a/docs/core/testing/unit-testing-with-dotnet-test.md +++ b/docs/core/testing/unit-testing-with-dotnet-test.md @@ -26,18 +26,16 @@ The process involves invoking the `VSTest` MSBuild target, which triggers other ### Run MTP projects with VSTest mode -`dotnet test` is typically designed to run VSTest projects in VSTest mode, as that was its original purpose. However, to run MTP projects in `dotnet test` VSTest mode, you can use the [Microsoft.Testing.Platform.MSBuild](https://www.nuget.org/packages/Microsoft.Testing.Platform.MSBuild). From the user's perspective, this support is enabled by setting the `TestingPlatformDotnetTestSupport` MSBuild property to true (it is false by default for backward compatibility reasons). In simple terms, setting this property to true will cause Microsoft.Testing.Platform.MSBuild to change the `VSTest` target behavior, redirecting it to call `InvokeTestingPlatform`. This is an MSBuild target included in Microsoft.Testing.Platform.MSBuild, responsible for correctly running MTP test applications as executables. This means that VSTest-specific command-line options are silently ignored in this mode, such as `--logger`. This implies that there should be a way to pass MTP-specific command-line options, such as `--report-trx`, which is equivalent to using `--logger trx` in VSTest. Given the current limitations of the `dotnet test` CLI, the only way to include MTP-specific arguments is by appending them after an additional `--`. For instance, `dotnet test -- --report-trx`. +`dotnet test` was designed to run VSTest projects in VSTest mode. However, you can run MTP projects in `dotnet test` VSTest mode by using the [Microsoft.Testing.Platform.MSBuild](https://www.nuget.org/packages/Microsoft.Testing.Platform.MSBuild) package. From the user's perspective, this support is enabled by setting the `TestingPlatformDotnetTestSupport` MSBuild property to `true` (it's `false` by default for backward-compatibility reasons). When this property is set to `true`, Microsoft.Testing.Platform.MSBuild changes the `VSTest` target behavior, redirecting it to call `InvokeTestingPlatform`. `InvokeTestingPlatform` is an MSBuild target included in Microsoft.Testing.Platform.MSBuild that's responsible for correctly running MTP test applications as executables. VSTest-specific command-line options, such as `--logger`, are silently ignored in this mode. To include MTP-specific arguments, such as `--report-trx`, you must append them after an additional `--`. For example, `dotnet test -- --report-trx`. > [!NOTE] -> MSTest and NUnit use [Microsoft.Testing.Extensions.VSTestBridge](https://www.nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge). When you set `EnableMSTestRunner` or `EnableNUnitRunner` (the properties used to enable MTP), your test project become supporting both VSTest and Microsoft.Testing.Platform. -> In that case, if you are using VSTest mode of `dotnet test` and not setting `TestingPlatformDotnetTestSupport` to true, you are actually running completely with VSTest, as if `EnableMSTestRunner` and `EnableNUnitRunner` are not there. +> MSTest and NUnit use the [Microsoft.Testing.Extensions.VSTestBridge](https://www.nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge) package. By setting `EnableMSTestRunner` or `EnableNUnitRunner` (which enables Microsoft.Testing.Platform), your test project will support both VSTest and Microsoft.Testing.Platform. +> In that scenario, if you use the VSTest mode of `dotnet test` and do not set `TestingPlatformDotnetTestSupport` to true, you are essentially running entirely with VSTest, as if `EnableMSTestRunner` and `EnableNUnitRunner` are not set to true. > > [!NOTE] -> It's highly recommended that you set the `TestingPlatformDotnetTestSupport` property in `Directory.Build.props`. That way, you don't have to add it to every test project file, and you don't risk introducing a new project that doesn't set this property and end up with a solution where some projects are VSTest while others are Microsoft.Testing.Platform, which may not work correctly and is unsupported scenario. +> It is highly recommended to set the `TestingPlatformDotnetTestSupport` property in `Directory.Build.props`. This ensures that you don't need to add it to every test project file individually. Additionally, it prevents the risk of introducing a new test project that doesn't set this property, which could result in a solution where some projects use VSTest while others use Microsoft.Testing.Platform. This mixed configuration might not work correctly and is an unsupported scenario. -The following command-line options of `dotnet test` command in VSTest mode are supported by Microsoft.Testing.Platform. These options are build-specific and not passed down to VSTest, which is why they work well with MTP. - -The list below described all `dotnet test` command line options that are supported by `Microsoft.Testing.Platform`: +The following list outlines the command-line options of `dotnet test` command in VSTest mode that are supported by Microsoft.Testing.Platform. These options are specific to the build process and not passed down to VSTest, which is why they work with MTP. - `-a|--arch ` - `--artifacts-path `