Document dotnet test (MTP) argument forwarding caveat

[Evangelink]

Documents the parser caveat from dotnet/sdk#51990 for dotnet test in Microsoft.Testing.Platform (MTP) mode.

When dotnet test consumes an option it recognizes (for example, --results-directory TestResults), the remaining tokens are forwarded to the test application. If a recognized option appears between an unrecognized option name and its value, removing the recognized option can change the meaning of the leftover arguments. For example:

dotnet test --report-trx --report-trx-filename --results-directory TestResults A.trx

becomes --report-trx --report-trx-filename A.trx for the test app, which then treats A.trx as the value of --report-trx-filename.

The same behavior exists in dotnet run and dotnet build (any unrecognized token is forwarded). The recommendation, as discussed in the issue, is to use a literal -- to mark where test application arguments begin so that dotnet test doesn't reorder or reinterpret them.

Changes

• docs/core/tools/dotnet-test-mtp.md: adds a new Pass arguments to the test application section that explains the behavior, shows a concrete repro, and recommends using --.
• docs/core/testing/unit-testing-with-dotnet-test.md: adds a tip in the Migrate to MTP mode section noting that even though -- is no longer required, it's still useful to avoid this parser quirk and future-proof scripts.

Internal previews

• dotnet test with Microsoft.Testing.Platform (MTP)
• Testing with 'dotnet test'

Closes dotnet/sdk#51990.

---

🤖 Generated with the assistance of GitHub Copilot CLI.

---

Internal previews

📄 File	🔗 Preview link
docs/core/testing/unit-testing-with-dotnet-test.md	Testing with 'dotnet test'
docs/core/tools/dotnet-run.md	dotnet run command
docs/core/tools/dotnet-test-mtp.md	dotnet test with Microsoft.Testing.Platform (MTP)

[Youssef1313]

I would document this in dotnet run instead, and link the dotnet run docs from dotnet test.

As is, this gives impression that it's MTP Test command problem.

[Copilot]

Pull request overview

This PR documents a dotnet test (Microsoft.Testing.Platform mode) argument-forwarding caveat where dotnet test consumes recognized options first, which can change how the remaining (forwarded) arguments bind to test-application options. It adds guidance to use a literal -- separator to prevent ambiguity and make scripts more resilient to future CLI option changes.

Changes:

• Adds a new “Pass arguments to the test application” section to explain the forwarding behavior, provide a repro, and recommend --.
• Adds a TIP in the MTP migration section to encourage continued use of -- for safer scripting, even though MTP mode no longer requires it.

Show a summary per file

File	Description
docs/core/tools/dotnet-test-mtp.md	Adds a new section documenting the forwarding caveat and recommending -- to avoid ambiguous argument binding.
docs/core/testing/unit-testing-with-dotnet-test.md	Adds a TIP in the MTP migration guidance linking to the new caveat section and recommending -- for robustness.

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 2

[Evangelink]

Good point — restructured in b245dd2 so the detailed explanation now lives in docs/core/tools/dotnet-run.md (new Forward arguments to the application section). dotnet test (MTP mode) keeps a short summary plus a link back to dotnet run to make clear the behavior is shared, not MTP-specific.

[BillWagner]

This LGTM @Evangelink

I'll now.