Skip to content

Commit

Permalink
Add MSBuild test-related properties (dotnet#42404)
Browse files Browse the repository at this point in the history
  • Loading branch information
@gewarren
gewarren authored Sep 9, 2024
1 parent ca94fa1 commit ca821ac
Show file tree
Hide file tree
Showing 7 changed files with 188 additions and 51 deletions.
124 changes: 123 additions & 1 deletion docs/core/project-sdk/msbuild-props.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1400,7 +1400,7 @@ The following properties are used for launching an app with the [`dotnet run`](.

### RunArguments

The `RunArguments` property defines the arguments that are passed to the app when it is run.
The `RunArguments` property defines the arguments that are passed to the app when it's run.

```xml
<PropertyGroup>
Expand All @@ -1421,6 +1421,128 @@ The `RunWorkingDirectory` property defines the working directory for the applica
</PropertyGroup>
```

## Test project&ndash;related properties

The following MSBuild properties are documented in this section:

- [IsTestProject](#istestproject)
- [IsTestingPlatformApplication](#istestingplatformapplication)
- [Enable\[NugetPackageNameWithoutDots\]](#enablenugetpackagenamewithoutdots)
- [EnableAspireTesting](#enableaspiretesting)
- [EnablePlaywright](#enableplaywright)
- [EnableMSTestRunner](#enablemstestrunner)
- [EnableNUnitRunner](#enablenunitrunner)
- [GenerateTestingPlatformEntryPoint](#generatetestingplatformentrypoint)
- [TestingPlatformCaptureOutput](#testingplatformcaptureoutput)
- [TestingPlatformCommandLineArguments](#testingplatformcommandlinearguments)
- [TestingPlatformDotnetTestSupport](#testingplatformdotnettestsupport)
- [TestingPlatformShowTestsFailure](#testingplatformshowtestsfailure)
- [TestingExtensionsProfile](#testingextensionsprofile)
- [UseVSTest](#usevstest)

### IsTestProject

The `IsTestProject` property signifies that a project is a test project. When this property is set to `true`, validation to check if the project references a self-contained executable is disabled. That's because test projects have an `OutputType` of `Exe` but usually call APIs in a referenced executable rather than trying to run. In addition, if a project references a project where `IsTestProject` is set to `true`, the test project isn't validated as an executable reference.

This property is mainly needed for the `dotnet test` scenario and has no impact when using *vstest.console.exe*.

> [!NOTE]
> If your project specifies the [MSTest SDK](../testing/unit-testing-mstest-sdk.md), you don't need to set this property. It's set automatically. Similarly, this property is set automatically for projects that reference the Microsoft.NET.Test.Sdk NuGet package linked to VSTest.
### IsTestingPlatformApplication

When your project references the [Microsoft.Testing.Platform.MSBuild](https://www.nuget.org/packages/Microsoft.Testing.Platform.MSBuild) package, setting `IsTestingPlatformApplication` to `true` (which is also the default value if not specified) does the following:

- Generates the entry point to the test project.
- Generates the configuration file.
- Detects the extensions.

Setting the property to `false` disables the transitive dependency to the package. A *transitive dependency* is when a project that references another project that references a given package behaves as if *it* references the package. You'd typically set this property to `false` in a non-test project that references a test project. For more information, see [error CS8892](../testing/unit-testing-platform-faq.md#error-cs8892-method-testingplatformentrypointmainstring-will-not-be-used-as-an-entry-point-because-a-synchronous-entry-point-programmainstring-was-found).

If your test project references MSTest, NUnit, or xUnit, this property is set to the same value as [EnableMSTestRunner](#enablemstestrunner), [EnableNUnitRunner](#enablenunitrunner), or `UseMicrosoftTestingPlatformRunner` (for xUnit).

### Enable\[NugetPackageNameWithoutDots\]

Use a property with the pattern `Enable[NugetPackageNameWithoutDots]` to enable or disable Microsoft.Testing.Platform extensions.

For example, to enable the crash dump extension (NuGet package [Microsoft.Testing.Extensions.CrashDump](https://www.nuget.org/packages/Microsoft.Testing.Extensions.CrashDump)), set the `EnableMicrosoftTestingExtensionsCrashDump` to `true`.

For more information, see [Enable or disable extensions](../testing/unit-testing-mstest-sdk.md#enable-or-disable-extensions).

### EnableAspireTesting

When you use the [MSTest project SDK](../testing/unit-testing-mstest-sdk.md), you can use the `EnableAspireTesting` property to bring in all the dependencies and default `using` directives you need for testing with `Aspire` and `MSTest`. This property is available in MSTest 3.4 and later versions.

For more information, see [Test with .NET Aspire](../testing/unit-testing-mstest-sdk.md#test-with-net-aspire).

### EnablePlaywright

When you use the [MSTest project SDK](../testing/unit-testing-mstest-sdk.md), you can use the `EnablePlaywright` property to bring in all the dependencies and default `using` directives you need for testing with `Playwright` and `MSTest`.This property is available in MSTest 3.4 and later versions.

For more information, see [Playwright](../testing/unit-testing-mstest-sdk.md#test-with-playwright).

### EnableMSTestRunner

The `EnableMSTestRunner` property enables or disables the use of the [MSTest runner](../testing/unit-testing-mstest-runner-intro.md). The MSTest runner is a lightweight and portable alternative to VSTest. This property is available in MSTest 3.2 and later versions.

> [!NOTE]
> If your project specifies the [MSTest SDK](../testing/unit-testing-mstest-sdk.md), you don't need to set this property. It's set automatically.
### EnableNUnitRunner

The `EnableNUnitRunner` property enables or disables the use of the [NUnit runner](../testing/unit-testing-nunit-runner-intro.md). The NUnit runner is a lightweight and portable alternative to VSTest. This property is available in [NUnit3TestAdapter](https://www.nuget.org/packages/NUnit3TestAdapter) in version 5.0 and later.

### GenerateTestingPlatformEntryPoint

Setting the `GenerateTestingPlatformEntryPoint` property to `false` disables the automatic generation of the program entry point in an MSTest, NUnit, or xUnit test project. You might want to set this property to `false` when you manually define an entry point, or when you reference a test project from an executable that also has an entry point.

For more information, see [error CS8892](../testing/unit-testing-platform-faq.md#error-cs8892-method-testingplatformentrypointmainstring-will-not-be-used-as-an-entry-point-because-a-synchronous-entry-point-programmainstring-was-found).

To control the generation of the entry point in a VSTest project, use the `GenerateProgramFile` property.

### TestingPlatformCaptureOutput

The `TestingPlatformCaptureOutput` property controls whether all console output that a test executable writes is captured and hidden from the user when you use `dotnet test` to run `Microsoft.Testing.Platform` tests. By default, the console output is hidden. This output includes the banner, version information, and formatted test information. Set this property to `false` to show this information together with MSBuild output.

For more information, see [Show complete platform output](../testing/unit-testing-platform-integration-dotnet-test.md#show-complete-platform-output).

### TestingPlatformCommandLineArguments

The `TestingPlatformCaptureOutput` property lets you specify command-line arguments to the test app when you use `dotnet test` to run `Microsoft.Testing.Platform` tests. The following project file snippet shows an example.

```xml
<PropertyGroup>
...
<TestingPlatformCommandLineArguments>--minimum-expected-tests 10</TestingPlatformCommandLineArguments>
</PropertyGroup>
```

### TestingPlatformDotnetTestSupport

The `TestingPlatformDotnetTestSupport` property lets you specify whether VSTest is used when you use `dotnet test` to run tests. If you set this property to `true`, VSTest is disabled and all `Microsoft.Testing.Platform` tests are run directly.

If you have a solution that contains VSTest test projects as well as MSTest, NUnit, or XUnit projects, you should make one call per mode (that is, `dotnet test` won't run tests from both VSTest and the newer platforms in one call).

### TestingPlatformShowTestsFailure

The `TestingPlatformShowTestsFailure` property lets you control whether a single failure or all errors in a failed test are reported when you use `dotnet test` to run tests. By default, test failures are summarized into a _.log_ file, and a single failure per test project is reported to MSBuild. To show errors per failed test, set this property to `true` in your project file.

### TestingExtensionsProfile

When you use the [MSTest project SDK](../testing/unit-testing-mstest-sdk.md), the `TestingExtensionsProfile` property lets you select a profile to use. The following table shows the allowable values.

| Value | Description |
|----------------|-----------------------------------------------------------------------------------------------|
| `Default` | Enables the recommended extensions for this version of MSTest.SDK. |
| `None` | No extensions are enabled. |
| `AllMicrosoft` | Enable all extensions shipped by Microsoft (including extensions with a restrictive license). |

For more information, see [MSTest runner profile](../testing/unit-testing-mstest-sdk.md#mstest-runner-profile).

### UseVSTest

Set the `UseVSTest` property to `true` to switch from the MSTest runner to the [VSTest](/visualstudio/test/vstest-console-options) runner when using the [MSTest project SDK](../testing/unit-testing-mstest-sdk.md).

## Hosting-related properties

The following MSBuild properties are documented in this section:
Expand Down
15 changes: 8 additions & 7 deletions docs/core/project-sdk/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,20 @@ no-loc: ["EmbeddedResource", "Compile", "None", "Blazor"]
---
# .NET project SDKs

Modern .NET projects are associated with a software development kit (SDK). Each *project SDK* is a set of MSBuild [targets](/visualstudio/msbuild/msbuild-targets) and associated [tasks](/visualstudio/msbuild/msbuild-tasks) that are responsible for compiling, packing, and publishing code. A project that references a project SDK is sometimes referred to as an *SDK-style project*.
Modern .NET projects are associated with a project software development kit (SDK). Each *project SDK* is a set of MSBuild [targets](/visualstudio/msbuild/msbuild-targets) and associated [tasks](/visualstudio/msbuild/msbuild-tasks) that are responsible for compiling, packing, and publishing code. A project that references a project SDK is sometimes referred to as an *SDK-style project*.

## Available SDKs

The following SDKs are available:

| ID | Description | Repo |
|-------------------------|------------------------------------------------------|---------------------------------|
| `Microsoft.NET.Sdk` | The .NET SDK | <https://github.com/dotnet/sdk> |
| `Microsoft.NET.Sdk.Web` | The .NET [Web SDK](/aspnet/core/razor-pages/web-sdk) | <https://github.com/dotnet/sdk> |
| ID | Description | Repo |
|----------------------------|---------------------------------------------------------|----------------------------------------|
| `Microsoft.NET.Sdk` | The .NET SDK | <https://github.com/dotnet/sdk> |
| `Microsoft.NET.Sdk.Web` | The .NET [Web SDK](/aspnet/core/razor-pages/web-sdk) | <https://github.com/dotnet/sdk> |
| `Microsoft.NET.Sdk.Razor` | The .NET [Razor SDK](/aspnet/core/razor-pages/sdk) | <https://github.com/dotnet/aspnetcore> |
| `Microsoft.NET.Sdk.BlazorWebAssembly` | The .NET [Blazor WebAssembly SDK](/aspnet/core/blazor#blazor-webassembly) | <https://github.com/dotnet/aspnetcore> |
| `Microsoft.NET.Sdk.Razor` | The .NET [Razor SDK](/aspnet/core/razor-pages/sdk) | <https://github.com/dotnet/aspnetcore> |
| `Microsoft.NET.Sdk.Worker` | The .NET [Worker Service](../extensions/workers.md) SDK | |
| `Microsoft.NET.Sdk.Worker` | The .NET [Worker Service](../extensions/workers.md) SDK | |
| `MSTest.Sdk` | The [MSTest SDK](../testing/unit-testing-mstest-sdk.md) | <https://github.com/microsoft/testfx> |

The .NET SDK is the base SDK for .NET. The other SDKs reference the .NET SDK, and projects that are associated with the other SDKs have all the .NET SDK properties available to them. The Web SDK, for example, depends on both the .NET SDK and the Razor SDK.

Expand Down
4 changes: 2 additions & 2 deletions docs/core/testing/unit-testing-mstest-runner-intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ The MSTest runner is a lightweight and portable alternative to [VSTest](https://

The MSTest runner is open source, and builds on a [`Microsoft.Testing.Platform`](./unit-testing-platform-intro.md) library. You can find `Microsoft.Testing.Platform` code in [microsoft/testfx](https://github.com/microsoft/testfx/tree/main/src/Platform/Microsoft.Testing.Platform) GitHub repository. The MSTest runner comes bundled with `MSTest in 3.2.0-preview.23623.1` or newer.

## Enable MSTest runner in a MSTest project
## Enable MSTest runner in an MSTest project

It's recommended to use [MSTest SDK](./unit-testing-mstest-sdk.md) as it greatly simplifies your project configuration, the updating of the project and ensures a proper alignment of the versions of the platform (MSTest runner) and its extensions.
It's recommended to use [MSTest SDK](./unit-testing-mstest-sdk.md) as it greatly simplifies your project configuration and updating the project, and it ensures a proper alignment of the versions of the platform (MSTest runner) and its extensions.

When you use `MSTest SDK`, by default you're opted in to using MSTest runner.

Expand Down
Loading

0 comments on commit ca821ac

Please sign in to comment.