Document dotnet test (MTP) argument forwarding caveat (#54192)

* Document dotnet test (MTP) argument forwarding caveat

When dotnet test consumes a recognized option that appears between an unrecognized option name and a value, the leftover tokens passed to the test application can change meaning. Document this behavior and recommend -- as a separator to mark test application arguments explicitly.

Addresses dotnet/sdk#51990.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Move argument-forwarding caveat to dotnet run docs

Address review feedback:

- @Youssef1313: move the detailed explanation of the parser caveat to `dotnet run` (where the behavior originates) and have `dotnet test` (MTP mode) link to it. This avoids giving the impression that the issue is specific to MTP.

- Copilot: split the TIP in unit-testing-with-dotnet-test.md into shorter sentences and remove the repeated `it`.

- Copilot: add `ai-usage: ai-assisted` to the unit-testing-with-dotnet-test.md frontmatter.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Evangelink

docs/core/testing/unit-testing-with-dotnet-test.md

@@ -3,7 +3,8 @@ title: Testing with 'dotnet test'
 description: Learn more about how 'dotnet test' works and its support for VSTest and Microsoft.Testing.Platform (MTP)
 author: Youssef1313
 ms.author: ygerges
-ms.date: 03/26/2025
+ms.date: 06/05/2026
+ai-usage: ai-assisted
 ---
 
 # Testing with 'dotnet test'
@@ -158,6 +159,9 @@ For users of MTP that are using the VSTest mode of `dotnet test`, there are few
 1. If passing a specific project (or directory containing project), for example, `dotnet test MyProject.csproj`, this should become `dotnet test --project MyProject.csproj`.
 1. If passing a specific dll, for example, `dotnet test path/to/UnitTests.dll`, this should become `dotnet test --test-modules path/to/UnitTests.dll`. Note that `--test-modules` also supports globbing.
 
+> [!TIP]
+> Even though `--` is no longer required in MTP mode, you can still use it to mark where test application arguments begin. The separator avoids a parser quirk where unrecognized arguments change meaning when interleaved with options that `dotnet test` understands. The separator also protects your scripts if `dotnet test` later starts recognizing one of those tokens. For more information, see [Forward arguments to the test application](../tools/dotnet-test-mtp.md#forward-arguments-to-the-test-application).
+
 ## Solutions with mixed test frameworks or extensions
 
 When a solution contains test projects that use different test frameworks (for example, MSTest and xUnit.net) or different sets of extensions, running `dotnet test` with framework-specific or extension-specific command-line options can fail. Options that are valid for one project are unrecognized by another, causing exit code 5 (invalid command-line arguments). For example:

docs/core/tools/dotnet-run.md

@@ -1,7 +1,7 @@
 ---
 title: dotnet run command
 description: The dotnet run command provides a convenient option to run your application from the source code.
-ms.date: 09/29/2025
+ms.date: 06/05/2026
 ---
 # dotnet run
 
@@ -61,6 +61,29 @@ To run the application, the `dotnet run` command resolves the dependencies of th
 
   Any arguments that aren't recognized by `dotnet run` are passed to the application. To separate arguments for `dotnet run` from arguments for the application, use the `--` option.
 
+## Forward arguments to the application
+
+`dotnet run` forwards any token it doesn't recognize to the application. The forwarded tokens keep their original order, but `dotnet run` first removes the options it understands. When a recognized option appears between an unrecognized option name and its value, removing the recognized option can change the meaning of the leftover tokens.
+
+For example, the following command interleaves the recognized option `--project` between tokens the application is meant to receive:
+
+```dotnetcli
+dotnet run --app-flag --app-name --project ConsoleApp.csproj A.txt
+```
+
+After `dotnet run` consumes `--project ConsoleApp.csproj`, the application receives `--app-flag --app-name A.txt`. The application then treats `A.txt` as the value of `--app-name`, which doesn't match the original command line.
+
+To avoid this ambiguity, place application arguments after a literal `--`:
+
+```dotnetcli
+dotnet run --project ConsoleApp.csproj -- --app-flag --app-name A.txt
+```
+
+The `--` separator marks every following token as an application argument, so `dotnet run` doesn't reorder or reinterpret them. The separator also future-proofs scripts against new `dotnet run` options that might later match a token previously forwarded to the application.
+
+> [!NOTE]
+> The same behavior applies to `dotnet build` and to `dotnet test` in Microsoft.Testing.Platform (MTP) mode, which forward unrecognized tokens to MSBuild or to the test application respectively. For more information about `dotnet test`, see [Forward arguments to the test application](dotnet-test-mtp.md#forward-arguments-to-the-test-application).
+
 ## Options
 
 - **`--`**

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

@@ -1,7 +1,7 @@
 ---
 title: dotnet test command with Microsoft.Testing.Platform (MTP)
 description: The dotnet test command is used to execute unit tests in a given project using MTP.
-ms.date: 02/03/2026
+ms.date: 06/05/2026
 ai-usage: ai-assisted
 ---
 # dotnet test with Microsoft.Testing.Platform (MTP)
@@ -168,6 +168,16 @@ With MTP, `dotnet test` operates faster than with VSTest. The test-related argum
 > [!NOTE]
 > To enable trace logging to a file, use the environment variable `DOTNET_CLI_TEST_TRACEFILE` to provide the path to the trace file.
 
+## Forward arguments to the test application
+
+`dotnet test` forwards any token it doesn't recognize to the test application. When a recognized option appears between an unrecognized option name and its value, removing the recognized option can change how the leftover tokens bind to options in the test application. To avoid this ambiguity, place test application arguments after a literal `--`:
+
+```dotnetcli
+dotnet test --results-directory TestResults -- --report-trx --report-trx-filename A.trx
+```
+
+The same parser behavior applies to `dotnet run` and `dotnet build`. For a detailed example, see [Forward arguments to the application](dotnet-run.md#forward-arguments-to-the-application) in the `dotnet run` reference.
+
 ## Examples
 
 - Run the tests in the project or solution in the current directory: