Sync dotnet test (VSTest) docs with microsoft/vstest July 2026 updates

docs/core/testing/selective-unit-tests.md

@@ -32,7 +32,7 @@ dotnet test --filter <Expression>
   | -------------- | -------------------- |
   | MSTest         | `FullyQualifiedName`<br>`Name`<br>`ClassName`<br>`Priority`<br>`TestCategory`<br>`Id` |
   | xUnit          | `FullyQualifiedName`<br>`DisplayName`<br>`Traits` |
-  | Nunit          | `FullyQualifiedName`<br>`Name`<br>`Priority`<br>`TestCategory` |
+  | NUnit          | `FullyQualifiedName`<br>`Name`<br>`Priority`<br>`TestCategory`<br>`Category`<br>`Property` |
 
 * **Operators**
 
@@ -45,6 +45,21 @@ dotnet test --filter <Expression>
 
 ## Character escaping
 
+Use escape sequences to represent filter operator characters in a filter value. These escape sequences are separate from any escaping your shell requires.
+
+| Escape sequence | Represents           |
+| --------------- | -------------------- |
+| `\\`          | `\`                  |
+| `\(`           | `(`                  |
+| `\)`           | `)`                  |
+| `\&`           | `&`                  |
+| `\|`           | <code>&#124;</code> |
+| `\=`           | `=`                  |
+| `\!`           | `!`                  |
+| `\~`           | `~`                  |
+
+To escape filter values programmatically, use the `Microsoft.VisualStudio.TestPlatform.ObjectModel.Utilities.FilterHelper.Escape` API from the `Microsoft.VisualStudio.TestPlatform.ObjectModel` NuGet package.
+
 To use an exclamation mark (`!`) in a filter expression, you have to escape it in some Linux or macOS shells by putting a backslash in front of it (`\!`). For example, the following filter skips all tests in a namespace that contains `IntegrationTests`:
 
 ```dotnetcli
@@ -57,6 +72,8 @@ For `FullyQualifiedName` values that include a comma for generic type parameters
 dotnet test --filter "FullyQualifiedName=MyNamespace.MyTestsClass<ParameterType1%2CParameterType2>.MyTestMethod"
 ```
 
+Because your shell also parses the filter expression, quote the entire `--filter` value whenever it contains characters your shell treats specially, such as `<`, `>`, or `,`. Quoting is required in PowerShell, where the comma is the array operator.
+
 For `Name` or `DisplayName`, use the URL encoding for the special characters. For example, to run a test with the name `MyTestMethod` and a string value `"text"`, use the following filter:
 
 ```dotnetcli
@@ -232,7 +249,7 @@ To run tests that have either a <xref:System.Reflection.Module.FullyQualifiedNam
 dotnet test --filter "(FullyQualifiedName~UnitTest1&TestCategory=CategoryA)|Priority=1"
 ```
 
-For more information, see [TestCase filter](https://github.com/Microsoft/vstest-docs/blob/main/docs/filter.md).
+For more information, see [TestCase filter](https://github.com/microsoft/vstest/blob/main/docs/filter.md).
 
 :::zone-end
 

docs/core/tools/dotnet-test-vstest.md

@@ -1,7 +1,7 @@
 ---
 title: dotnet test command with VSTest
 description: The dotnet test command is used to execute unit tests in a given project using VSTest.
-ms.date: 12/29/2024
+ms.date: 07/19/2026
 ai-usage: ai-assisted
 ---
 # dotnet test with VSTest
@@ -119,6 +119,8 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 
   To collect a crash dump from a native application running on .NET 5.0 or later, the usage of Procdump can be forced by setting the `VSTEST_DUMP_FORCEPROCDUMP` environment variable to `1`.
 
+  For the full list of test platform environment variables, see [Environment variables](https://github.com/microsoft/vstest/blob/main/docs/environment-variables.md).
+
 - **`--blame-crash-dump-type <DUMP_TYPE>`** (Available since .NET 5.0 SDK)
 
   The type of crash dump to be collected. Supported dump types are `full` (default), and `mini`. Implies `--blame-crash`.
@@ -146,11 +148,49 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 
   When no unit is used (for example, 5400000), the value is assumed to be in milliseconds. When used together with data driven tests, the timeout behavior depends on the test adapter used. For xUnit, NUnit, and MSTest 2.2.4+, the timeout is renewed after every test case. For MSTest before version 2.2.4, the timeout is used for all test cases. This option is supported on Windows with `netcoreapp2.1` and later, on Linux with `netcoreapp3.1` and later, and on macOS with `net5.0` or later. Implies `--blame` and `--blame-hang`.
 
+  You can also configure blame in a `.runsettings` file and pass it with `--settings`. The `.runsettings` file supports the same blame behavior and additional keys that aren't exposed as top-level `dotnet test` switches, such as `CollectDumpOnTestSessionHang` and `MonitorPostmortemDebugger`. For more information, see [Blame data collector](https://github.com/microsoft/vstest/blob/main/docs/extensions/blame-datacollector.md).
+
+  ```xml
+  <RunSettings>
+    <DataCollectionRunSettings>
+      <DataCollectors>
+        <DataCollector friendlyName="blame" enabled="true">
+          <Configuration>
+            <CollectDump CollectAlways="true" DumpType="full" />
+            <CollectDumpOnTestSessionHang TestTimeout="30min" HangDumpType="full" />
+            <MonitorPostmortemDebugger DumpDirectoryPath="C:\Dumps" />
+          </Configuration>
+        </DataCollector>
+      </DataCollectors>
+    </DataCollectionRunSettings>
+  </RunSettings>
+  ```
+
+  The following tables map the blame options to their `dotnet test` switches and `.runsettings` elements. For the complete blame collector reference, see [Blame data collector](https://github.com/microsoft/vstest/blob/main/docs/extensions/blame-datacollector.md).
+
+  Crash dump options:
+
+  | Behavior | `dotnet test` switch | `.runsettings` element |
+  | --- | --- | --- |
+  | Collect a crash dump | `--blame-crash` | `<CollectDump />` |
+  | Collect even on a clean exit | `--blame-crash-collect-always` | `<CollectDump CollectAlways="true" />` |
+  | Dump type (`mini`, `full`; default `full`) | `--blame-crash-dump-type` | `<CollectDump DumpType="full" />` |
+
+  Hang dump options:
+
+  | Behavior | `dotnet test` switch | `.runsettings` element |
+  | --- | --- | --- |
+  | Collect a hang dump | `--blame-hang` | `<CollectDumpOnTestSessionHang />` |
+  | Timeout before the hang dump (default `1h`) | `--blame-hang-timeout` | `<CollectDumpOnTestSessionHang TestTimeout="90m" />` |
+  | Hang dump type (`mini`, `full`, `none`) | `--blame-hang-dump-type` | `<CollectDumpOnTestSessionHang HangDumpType="mini" />` |
+
+  For Microsoft.Testing.Platform (MTP) test apps, the `--blame-*` switches and the blame data collector don't apply. MTP uses `--crashdump`, `--hangdump`, and `--hangdump-timeout` from the `Microsoft.Testing.Extensions.CrashDump` and `Microsoft.Testing.Extensions.HangDump` packages. For more information, see [dotnet test with MTP](dotnet-test-mtp.md).
+
 - [!INCLUDE [configuration](includes/cli-configuration.md)]
 
 - **`--collect <DATA_COLLECTOR_NAME>`**
 
-  Enables data collector for the test run. For more information, see [Monitor and analyze test run](https://aka.ms/vstest-collect).
+  Enables a data collector for the test run. For more information, including the Event Log data collector and guidance for authoring your own data collector, see [Monitor and analyze test run](https://aka.ms/vstest-collect).
 
   For example you can collect code coverage by using the `--collect "Code Coverage"` option. For more information, see [Use code coverage](/visualstudio/test/using-code-coverage-to-determine-how-much-code-is-being-tested), [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis), and [GitHub issue dotnet/docs#34479](https://github.com/dotnet/docs/issues/34479).
 
@@ -160,6 +200,8 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 
   Enables diagnostic mode for the test platform and writes diagnostic messages to the specified file and to files next to it. The process that is logging the messages determines which files are created, such as `*.host_<date>.txt` for test host log, and `*.datacollector_<date>.txt` for data collector log.
 
+  To set the trace level, append `;tracelevel=<LEVEL>` to the log file name, for example `--diag log.txt;tracelevel=verbose`. The allowed values for `tracelevel` are `off`, `error`, `warning`, `info`, and `verbose`. The default value is `verbose`.
+
 - [!INCLUDE [disable-build-servers](includes/cli-disable-build-servers.md)]
 
 - **`-e|--environment <NAME="VALUE">`**
@@ -254,7 +296,9 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 
   Example: `dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True`
 
-  For more information, see [Passing RunSettings arguments through command line](https://github.com/Microsoft/vstest-docs/blob/main/docs/RunSettingsArguments.md).
+  Starting with the .NET 5 SDK, you can also set `TestRunParameters` from the command line, for example: `dotnet test -- TestRunParameters.Parameter(name="myParam", value="value")`. `RunSettings` arguments take precedence over values from a `.runsettings` file.
+
+  For more information, see [Passing RunSettings arguments through command line](https://github.com/microsoft/vstest/blob/main/docs/RunSettingsArguments.md).
 
 ## Examples
 
@@ -357,8 +401,10 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 | Test Framework | Supported properties                                                                                      |
 | -------------- | --------------------------------------------------------------------------------------------------------- |
 | MSTest         | <ul><li>FullyQualifiedName</li><li>Name</li><li>ClassName</li><li>Priority</li><li>TestCategory</li></ul> |
-| xUnit          | <ul><li>FullyQualifiedName</li><li>DisplayName</li><li>Category</li></ul>                                 |
-| NUnit          | <ul><li>FullyQualifiedName</li><li>Name</li><li>Category</li><li>Priority</li></ul>                                   |
+| xUnit          | <ul><li>FullyQualifiedName</li><li>DisplayName</li><li>Traits</li></ul>                                   |
+| NUnit          | <ul><li>FullyQualifiedName</li><li>Name</li><li>Priority</li><li>TestCategory</li><li>Category</li><li>Property</li></ul> |
+
+For xUnit, a trait defined with `[Trait("key", "value")]` is filtered by its key (for example, `[Trait("Category", "bvt")]` is matched with `--filter Category=bvt`). For NUnit, `TestCategory` and `Category` are equivalent, and a property defined with `[Property("key", "value")]` is filtered by its key.
 
 The `<operator>` describes the relationship between the property and the value:
 
@@ -384,10 +430,24 @@ You can enclose expressions in parenthesis when using conditional operators (for
 
 For more information and examples on how to use selective unit test filtering, see [Running selective unit tests](../testing/selective-unit-tests.md).
 
+## Exit codes
+
+When you run tests through the VSTest path, `dotnet test` reports the outcome with one of two exit codes:
+
+| Exit code | Meaning |
+| --------- | ------- |
+| `0` | Success. The requested operation completed and, for a test run, all executed tests passed. |
+| `1` | Failure. For example, one or more tests failed, a run error was reported, the command line was invalid, a test source couldn't be loaded, or the run was aborted or canceled. |
+
+The underlying `vstest.console` process never returns any other value.
+
+When discovery finds no matching tests, the run prints a warning rather than an error and still returns `0` by default. To make a run that discovers or selects zero tests return `1` instead, set `RunConfiguration.TreatNoTestsAsError` to `true` in a `.runsettings` file.
+
 ## See also
 
 - [Frameworks and Targets](../../standard/frameworks.md)
 - [.NET Runtime Identifier (RID) catalog](../rid-catalog.md)
 - [Passing runsettings arguments through commandline](https://github.com/microsoft/vstest/blob/main/docs/RunSettingsArguments.md)
+- [VSTest environment variables (microsoft/vstest)](https://github.com/microsoft/vstest/blob/main/docs/environment-variables.md)
 - [dotnet test](dotnet-test.md)
 - [dotnet test with MTP](dotnet-test-mtp.md)

docs/core/tools/dotnet-vstest.md

@@ -1,7 +1,8 @@
 ---
 title: dotnet vstest command
 description: The dotnet vstest command builds a project and all of its dependencies.
-ms.date: 10/28/2025
+ms.date: 07/19/2026
+ai-usage: ai-assisted
 ---
 # dotnet vstest
 
@@ -17,20 +18,20 @@ ms.date: 10/28/2025
 ## Synopsis
 
 ```dotnetcli
-dotnet vstest [<TEST_FILE_NAMES>] [--Blame] [--Diag <PATH_TO_LOG_FILE>]
-    [--Framework <FRAMEWORK>] [--InIsolation] [-lt|--ListTests <FILE_NAME>]
-    [--logger <LOGGER_URI/FRIENDLY_NAME>] [--Parallel]
-    [--ParentProcessId <PROCESS_ID>] [--Platform] <PLATFORM_TYPE>
-    [--Port <PORT>] [--ResultsDirectory<PATH>] [--Settings <SETTINGS_FILE>]
-    [--TestAdapterPath <PATH>] [--TestCaseFilter <EXPRESSION>]
-    [--Tests <TEST_NAMES>] [[--] <args>...]
+dotnet vstest [<TEST_FILE_NAMES>] [--Blame] [--Collect:<DATA_COLLECTOR_NAME>]
+    [--Diag:<PATH_TO_LOG_FILE>] [-e|--Environment:<NAME="VALUE">]
+    [--Framework:<FRAMEWORK>] [--InIsolation] [-lt|--ListTests:<FILE_NAME>]
+    [--logger:<LOGGER_URI/FRIENDLY_NAME>] [--Parallel]
+    [--Platform:<PLATFORM_TYPE>] [--ResultsDirectory:<PATH>]
+    [--Settings:<SETTINGS_FILE>] [--TestAdapterPath:<PATH>]
+    [--TestCaseFilter:<EXPRESSION>] [--Tests:<TEST_NAMES>] [[--] <args>...]
 
 dotnet vstest -?|--Help
 ```
 
 ## Description
 
-The `dotnet vstest` command runs the `VSTest.Console` command-line application to run automated unit tests.
+The `dotnet vstest` command runs the `VSTest.Console` command-line application to run automated unit tests. The options in this article are forwarded to `vstest.console`. For the complete list of command-line options, see [vstest.console.exe command line options](https://github.com/microsoft/vstest/blob/main/docs/commandline.md).
 
 ## Arguments
 
@@ -44,23 +45,31 @@ The `dotnet vstest` command runs the `VSTest.Console` command-line application t
 
   Runs the tests in blame mode. This option is helpful in isolating the problematic tests causing test host to crash. It creates an output file in the current directory as *Sequence.xml* that captures the order of tests execution before the crash.
 
-- **`--Diag <PATH_TO_LOG_FILE>`**
+- **`--Collect:<DATA_COLLECTOR_NAME>`**
+
+  Enables a data collector for the test run. For example, `--Collect:"Code Coverage"` collects code coverage with the built-in Visual Studio collector, and `--Collect:"XPlat Code Coverage"` uses the cross-platform Coverlet collector. For more information, see [Monitor and analyze test run](https://aka.ms/vstest-collect).
+
+- **`--Diag:<PATH_TO_LOG_FILE>`**
 
   Enables verbose logs for the test platform. Logs are written to the provided file.
 
-- **`--Framework <FRAMEWORK>`**
+- **`-e|--Environment:<NAME="VALUE">`**
+
+  Sets the value of an environment variable for the test host process. Creates the variable if it doesn't exist, overrides it if it does. Using this option forces the tests to run in an isolated process. Specify the option multiple times to set multiple variables.
+
+- **`--Framework:<FRAMEWORK>`**
 
   Target .NET Framework version used for test execution. An example of a valid value is `.NETFramework,Version=v7.0`. Other supported values are `Framework40`, `Framework45`, `FrameworkCore10`, and `FrameworkUap10`.
 
 - **`--InIsolation`**
 
   Runs the tests in an isolated process. This makes *vstest.console.exe* process less likely to be stopped on an error in the tests, but tests may run slower.
 
-- **`-lt|--ListTests <FILE_NAME>`**
+- **`-lt|--ListTests:<FILE_NAME>`**
 
   Lists all discovered tests from the given test container.
 
-- **`--logger <LOGGER_URI/FRIENDLY_NAME>`**
+- **`--logger:<LOGGER_URI/FRIENDLY_NAME>`**
 
   Specify a logger for test results.
 
@@ -86,35 +95,27 @@ The `dotnet vstest` command runs the `VSTest.Console` command-line application t
 
   Run tests in parallel. By default, all available cores on the machine are available for use. Specify an explicit number of cores by setting the `MaxCpuCount` property under the `RunConfiguration` node in the *runsettings* file.
 
-- **`--ParentProcessId <PROCESS_ID>`**
-
-  Process ID of the parent process responsible for launching the current process.
-
-- **`--Platform <PLATFORM_TYPE>`**
-
-  Target platform architecture used for test execution. Valid values are `x86`, `x64`, and `ARM`.
-
-- **`--Port <PORT>`**
+- **`--Platform:<PLATFORM_TYPE>`**
 
-  Specifies the port for the socket connection and receiving the event messages.
+  Target platform architecture used for test execution. Valid values are `x86`, `x64`, `ARM`, `ARM64`, `S390x`, `Ppc64le`, `RiscV64`, and `LoongArch64`.
 
 - **`--ResultsDirectory:<PATH>`**
 
   Test results directory will be created in specified path if not exists.
 
-- **`--Settings <SETTINGS_FILE>`**
+- **`--Settings:<SETTINGS_FILE>`**
 
   Settings to use when running tests.
 
-- **`--TestAdapterPath <PATH>`**
+- **`--TestAdapterPath:<PATH>`**
 
   Use custom test adapters from a given path (if any) in the test run.
 
-- **`--TestCaseFilter <EXPRESSION>`**
+- **`--TestCaseFilter:<EXPRESSION>`**
 
-  Run tests that match the given expression. `<EXPRESSION>` is of the format `<property>Operator<value>[|&<EXPRESSION>]`, where Operator is one of `=`, `!=`, or `~`. Operator `~` has 'contains' semantics and is applicable for string properties like `DisplayName`. Parentheses `()` are used to group subexpressions. For more information, see [TestCase filter](https://github.com/Microsoft/vstest-docs/blob/main/docs/filter.md).
+  Run tests that match the given expression. `<EXPRESSION>` is of the format `<property>Operator<value>[|&<EXPRESSION>]`, where Operator is one of `=`, `!=`, or `~`. Operator `~` has 'contains' semantics and is applicable for string properties like `DisplayName`. Parentheses `()` are used to group subexpressions. For more information, see [TestCase filter](https://github.com/microsoft/vstest/blob/main/docs/filter.md).
 
-- **`--Tests <TEST_NAMES>`**
+- **`--Tests:<TEST_NAMES>`**
 
   Run tests with names that match the provided values. Separate multiple values with commas.
 
@@ -164,4 +165,6 @@ dotnet vstest /Tests:TestMethod1,TestMethod2
 
 ## See also
 
-- [VSTest.Console.exe command-line options](/visualstudio/test/vstest-console-options)
+- [VSTest.Console.exe command-line options](/visualstudio/test/vstest-console-options) - the official Microsoft Learn reference for the `VSTest.Console.exe` tool, including options that `dotnet vstest` doesn't expose. Start here for stable, curated documentation.
+- [vstest.console.exe command line options (microsoft/vstest)](https://github.com/microsoft/vstest/blob/main/docs/commandline.md) - the source-derived reference in the `microsoft/vstest` repo. Use it for the most up-to-date option details and internal switches, plus links to related runsettings, filtering, and diagnostics docs.
+- [VSTest environment variables (microsoft/vstest)](https://github.com/microsoft/vstest/blob/main/docs/environment-variables.md) - environment variables that VSTest and the test host recognize, such as `VSTEST_DUMP_FORCEPROCDUMP` and the `VSTEST_DOTNET_ROOT_*` variables the .NET SDK sets when it launches `vstest.console`.