diff --git a/docs/core/testing/order-unit-tests.md b/docs/core/testing/order-unit-tests.md index 007e95a18c0c7..3d8ac9ce9ea61 100644 --- a/docs/core/testing/order-unit-tests.md +++ b/docs/core/testing/order-unit-tests.md @@ -1,7 +1,7 @@ --- title: Order unit tests description: Learn how to order unit tests with .NET Core. -ms.date: 07/08/2026 +ms.date: 09/14/2026 ai-usage: ai-assisted zone_pivot_groups: unit-testing-framework-set-one --- @@ -23,7 +23,7 @@ If you prefer to browse the source code, see the [order .NET Core unit tests](/s ## Order alphabetically > [!NOTE] -> MSTest runs tests sequentially within a class by default. If you configure parallelism using the `` setting in a `.runsettings` file, tests across classes can run concurrently, and ordering affects only the sequence within each class. +> MSTest runs tests sequentially within a class by default. If you configure parallelism using the `` setting in a `.runsettings` file, tests across classes can run concurrently, and ordering affects only the sequence within each class. For all ways to enable or disable MSTest parallelization, see [Configure parallelization](unit-testing-mstest-writing-tests-controlling-execution.md#configure-parallelization). MSTest discovers tests in the same order in which they are defined in the test class. diff --git a/docs/core/testing/unit-testing-mstest-configure.md b/docs/core/testing/unit-testing-mstest-configure.md index 54bbff847a1c7..b90f69e0197a8 100644 --- a/docs/core/testing/unit-testing-mstest-configure.md +++ b/docs/core/testing/unit-testing-mstest-configure.md @@ -3,7 +3,7 @@ title: Configure MSTest description: Learn how to configure MSTest. author: Evangelink ms.author: amauryleve -ms.date: 09/02/2026 +ms.date: 09/14/2026 ai-usage: ai-assisted --- @@ -17,6 +17,12 @@ MSTest is a fully supported, open-source and a cross-platform test framework tha A *.runsettings* file can be used to configure how unit tests are being run. To learn more about the runsettings and the configurations related to the platform, you can check out [VSTest runsettings documentation](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file) or [MSTest runner runsettings documentation](microsoft-testing-platform-extensions-vstest-bridge.md#runsettings-support). +### Parallelization settings + +To enable MSTest in-assembly parallelization, configure the `Parallelize` entry under `MSTest`, including its `Workers` and `Scope` values, as described in the table in the next section. To force parallelization off for the run, set `true`. The `DisableParallelization` setting overrides an `[assembly: Parallelize]` attribute. + +For the behavior of the parallelization attributes and a comparison of every configuration mechanism, see [Configure parallelization](unit-testing-mstest-writing-tests-controlling-execution.md#configure-parallelization). + ### MSTest element The following runsettings entries let you configure how MSTest behaves. @@ -194,6 +200,8 @@ Example: All the settings in this section belong to the `parallelism` element. +For the behavior of the parallelization attributes and a comparison of every configuration mechanism, see [Configure parallelization](unit-testing-mstest-writing-tests-controlling-execution.md#configure-parallelization). + | Entry | Default | Description | |-------|---------|-------------| | enabled | false | Enable test parallelization. | @@ -311,6 +319,8 @@ Each element of the file is optional because it has a default value. Starting with MSTest 4.3, opt in to assembly-level parallelization from your project file or `Directory.Build.props` without authoring an `[assembly: Parallelize]` attribute. These properties emit the corresponding assembly attribute during build, so they require `GenerateAssemblyInfo` to be `true` (the default for SDK-style projects). +For the behavior of the generated attributes and a comparison of every configuration mechanism, see [Configure parallelization](unit-testing-mstest-writing-tests-controlling-execution.md#configure-parallelization). + | Property | Default | Description | |----------|---------|-------------| | `MSTestParallelizeScope` | | The parallelization scope. Set it to `MethodLevel` or `ClassLevel` to emit `[assembly: Parallelize(Scope = ExecutionScope.MethodLevel)]` (or `ExecutionScope.ClassLevel`), or to `None` to emit `[assembly: DoNotParallelize]`. | diff --git a/docs/core/testing/unit-testing-mstest-writing-tests-controlling-execution.md b/docs/core/testing/unit-testing-mstest-writing-tests-controlling-execution.md index f030eb959b62d..a97eb326c1b23 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests-controlling-execution.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests-controlling-execution.md @@ -3,7 +3,7 @@ title: Test execution and control in MSTest description: Learn how to control test execution in MSTest with parallelization, threading, timeouts, retries, and conditional execution. author: Evangelink ms.author: amauryleve -ms.date: 09/02/2026 +ms.date: 09/14/2026 ai-usage: ai-assisted --- @@ -113,6 +113,17 @@ public class WinUITests Parallelization attributes control whether and how tests run concurrently, improving test execution time. +### Configure parallelization + +MSTest runs tests sequentially within each test assembly by default. Use one of the following mechanisms to explicitly enable or disable in-assembly parallelization: + +| Mechanism | Enable parallelization | Disable parallelization | +|-----------|------------------------|-------------------------| +| Source attributes | Apply [`[assembly: Parallelize]`](#parallelizeattribute), and optionally set its scope and worker count. | Apply [`[assembly: DoNotParallelize]`](#donotparallelizeattribute) to disable parallelization for the assembly. Apply `[DoNotParallelize]` to a class or method to opt only those tests out after you enable assembly parallelization. | +| *.runsettings* | Configure the MSTest [`Parallelize` entry](unit-testing-mstest-configure.md#parallelization-settings). | Set [`RunConfiguration.DisableParallelization`](unit-testing-mstest-configure.md#parallelization-settings) to `true`. This setting forces parallelization off even when the assembly has a `[Parallelize]` attribute. | +| *testconfig.json* | Set [`mstest.parallelism.enabled`](unit-testing-mstest-configure.md#parallelism-settings) to `true`, and optionally configure `scope` and `workers`. | Set `mstest.parallelism.enabled` to `false`. | +| MSBuild properties | Set [`MSTestParallelizeScope`](unit-testing-mstest-configure.md#msbuild-properties) to `ClassLevel` or `MethodLevel`, and optionally set `MSTestParallelizeWorkers`. | Set `MSTestParallelizeScope` to `None`. These properties generate the corresponding assembly attribute, so don't also declare the attribute in source. | + ### `ParallelizeAttribute` By default, MSTest runs tests sequentially. The assembly-level attribute enables parallel test execution. @@ -143,7 +154,7 @@ The `Workers` property specifies the maximum number of threads for parallel exec ``` > [!TIP] -> You can configure parallelization without modifying code through [runsettings](unit-testing-mstest-configure.md#mstest-element), [testconfig.json](unit-testing-mstest-configure.md#testconfigjson), or the [`MSTestParallelizeScope` and `MSTestParallelizeWorkers` MSBuild properties](unit-testing-mstest-configure.md#msbuild-properties). +> To choose a configuration mechanism, see [Configure parallelization](#configure-parallelization). > [!TIP] > Enable parallelization at the assembly level by default, even if many tests currently require sequential execution. This approach encourages writing new tests that support parallel execution from the start. Use the [MSTEST0001](mstest-analyzers/mstest0001.md) analyzer to ensure that the assembly explicitly declares its parallelization intent with `[assembly: Parallelize]` or `[assembly: DoNotParallelize]`. Once parallelization is enabled, review each test class to determine whether it safely supports concurrent execution. Often, excluding just a few classes or methods with `DoNotParallelize` is sufficient, allowing the majority of your tests to run in parallel for significantly faster test execution. @@ -152,6 +163,10 @@ The `Workers` property specifies the maximum number of threads for parallel exec The prevents parallel execution for specific assemblies, classes, or methods. Use this attribute when tests share state or resources that can't be safely accessed concurrently. +When you enable in-assembly parallelization, MSTest partitions each test source (assembly) into parallelizable and nonparallelizable tests. MSTest runs the parallelizable set first, then runs the `DoNotParallelize` set one test at a time at the end of that source's run. In runs that include multiple test sources, each source has its own deferred tail. Because deferred tests can't overlap with other tests in the same source, a slow deferred test usually increases that source's critical path by about its own duration. + +Because MSTest runs deferred tests only after the parallelizable phase finishes, a canceled or aborted run can end before MSTest executes deferred tests. The execution order described here is an internal implementation detail and isn't a public contract. It might change in a future version of MSTest. + ```csharp [assembly: Parallelize(Scope = ExecutionScope.MethodLevel)] @@ -195,7 +210,7 @@ public class MixedTests ``` > [!NOTE] -> You only need `DoNotParallelize` when you've enabled parallel execution with the `Parallelize` attribute. +> You only need `DoNotParallelize` when you've enabled in-assembly parallelization. When parallelization is disabled (the default), `DoNotParallelize` has no effect. ### `ResourceLockAttribute`