Enrich VSTest CLI docs: exit codes, filter/shell escaping, blame dumps, option gaps + archived-link cleanup by azat-msft · Pull Request #11401 · MicrosoftDocs/visualstudio-docs

azat-msft · 2026-07-17T10:32:56Z

Enrichment of the VSTest documentation on Microsoft Learn (VS docs test area), reconciled against the maintained microsoft/vstest repository. This PR supersedes and expands #11396 (kept as a draft, to be closed in favor of this one) so all the related VSTest doc work lands as one coherent change.

What changed

docs/test/vstest-console-options.md

New: Exit codes section — documents the 0/1 exit-code contract and the "no tests found is a warning, still returns 0 unless TreatNoTestsAsError" behavior. Not covered anywhere in VS docs today.
New: shell escaping for /TestCaseFilter — PowerShell (,/;), and bash/zsh (! in !~, generic-type <,> args).
Expanded /Blame — crash/hang dump options (CollectDump, CollectHangDump, DumpType, TestTimeout) and the dotnet test equivalents (--blame-crash, --blame-hang); full option matrix left linked to the maintained repo.
Filled option gaps — /Environment (+ short form /e), @ response files, short forms (/lt), modern /Framework monikers (net8.0, net10.0), /Diag;tracelevel=, and /Logger LogFilePrefix vs LogFileName.
Plus the archived-link fixes and logger-catalog pointer originally in Update VSTest docs: fix archived cross-links, add runsettings CLI override and logger catalog #11396.

docs/test/configure-unit-tests-by-using-a-dot-runsettings-file.md

"Override run settings from the command line" section (inline -- name=value overrides, TestRunParameters, and shell quoting incl. zsh), from Update VSTest docs: fix archived cross-links, add runsettings CLI override and logger catalog #11396.
Repointed the last archived microsoft/vstest-docs link to microsoft/vstest.

docs/test/migrate-testsettings-to-runsettings.md

Repointed the archived microsoft/vstest-docs RFC link to microsoft/vstest (matching its docs/ path layout).

Propagation approach

Content was chosen by reviewing the actual upstream doc changes (not commit titles): high-value, stable, user-facing material (exit codes, filter escaping, blame dumps, option gaps) is copied; large or volatile upstream material (full logger catalog, code-coverage guide, env-var internals, extensibility walkthroughs) is linked to the maintained repo to keep one source of truth.

Opened from a fork; happy to adjust to match the docs team's conventions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e840b63-ad95-40c2-9ef8-5f2fcc4cfdaa

Cross-reference microsoft/vstest report.md for the full list of built-in and community test loggers and instructions for authoring a logger. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e840b63-ad95-40c2-9ef8-5f2fcc4cfdaa

The command-line override section is introduced with vstest.console.exe but used dotnet test examples. vstest.console.exe supports the same -- name=value inline runsettings override natively (CliRunSettingsArgumentProcessor), so show the vstest.console.exe form to match the page's context, and note dotnet test uses the same syntax. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e840b63-ad95-40c2-9ef8-5f2fcc4cfdaa

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Address PR review feedback: document unix shell (zsh) escaping rules for the `TestRunParameters.Parameter(...)` override syntax, using zsh as the macOS default-shell example. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0cc38362-9c3b-46eb-8142-9c49c63dc4a0

…stest repo The microsoft/vstest-docs repository is archived. Repoint the last two cross-references (configure.md and RFC 0023) to the maintained microsoft/vstest repository, matching its docs/ path layout. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0cc38362-9c3b-46eb-8142-9c49c63dc4a0

…me dumps, option gaps Reconciled against the maintained microsoft/vstest repo docs: - Add an Exit codes section (0/1 semantics, no-tests-found warning + TreatNoTestsAsError). - Add shell escaping guidance for /TestCaseFilter (PowerShell comma/semicolon, bash/zsh ! and generic-type args). - Expand /Blame with crash/hang dump options and dotnet test equivalents. - Fill option gaps: /Environment (+/e), @response file, short forms (/lt), modern /Framework monikers, /Diag tracelevel, /Logger LogFilePrefix. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0cc38362-9c3b-46eb-8142-9c49c63dc4a0

prmerger-automator · 2026-07-17T10:33:14Z

@azat-msft : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. @Mikejo5000

prmerger-automator · 2026-07-17T10:33:28Z

@azat-msft : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. @Mikejo5000

learn-build-service-prod · 2026-07-17T10:36:08Z

Learn Build status updates of commit d13df7f:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/test/configure-unit-tests-by-using-a-dot-runsettings-file.md	✅Succeeded
docs/test/migrate-testsettings-to-runsettings.md	✅Succeeded
docs/test/vstest-console-options.md	✅Succeeded

For more details, please refer to the build report.

…witches reference Link to the maintained microsoft/vstest quickstart guide and the full command-line reference (including internal/legacy switches deliberately omitted from this article), keeping that volatile material in one upstream source of truth. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0cc38362-9c3b-46eb-8142-9c49c63dc4a0

…ctor links - /Platform: list the full set of accepted architecture values (ARM64, S390x, Ppc64le, RiscV64, LoongArch64) while keeping the Windows x86/x64 caveat. - Add Related content links to the maintained environment-variables and data collector authoring docs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0cc38362-9c3b-46eb-8142-9c49c63dc4a0

learn-build-service-prod · 2026-07-17T10:48:26Z

Learn Build status updates of commit bbf5b1a:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/test/configure-unit-tests-by-using-a-dot-runsettings-file.md	✅Succeeded
docs/test/migrate-testsettings-to-runsettings.md	✅Succeeded
docs/test/vstest-console-options.md	✅Succeeded

For more details, please refer to the build report.

prmerger-automator · 2026-07-17T10:48:32Z

PRMerger Results

Issue	Description
File Change Percent	This PR contains file(s) with more than 30% file change.

learn-build-service-prod · 2026-07-17T10:51:34Z

Learn Build status updates of commit 216bd8d:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/test/configure-unit-tests-by-using-a-dot-runsettings-file.md	✅Succeeded
docs/test/migrate-testsettings-to-runsettings.md	✅Succeeded
docs/test/vstest-console-options.md	✅Succeeded

For more details, please refer to the build report.

prmerger-automator · 2026-07-17T10:51:41Z

PRMerger Results

Issue	Description
File Change Percent	This PR contains file(s) with more than 30% file change.

…d content - Remove switches that microsoft/vstest reclassified as internal/omitted from the main options table (/Enablecodecoverage, /UseVsixExtensions, /ListDiscoverers, /ListExecutors, /ListLoggers, /ListSettingsProviders); the full reference (incl. omitted switches) is now linked from the options intro. - Add an Environment variables section with a partial copy of the most user-facing variables, linking to the full upstream list. - Related content: quickstart first; move the full command-line reference to the options intro and the env-vars link into the new section. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0cc38362-9c3b-46eb-8142-9c49c63dc4a0

learn-build-service-prod · 2026-07-17T11:01:00Z

Learn Build status updates of commit 0eebe72:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/test/configure-unit-tests-by-using-a-dot-runsettings-file.md	✅Succeeded
docs/test/migrate-testsettings-to-runsettings.md	✅Succeeded
docs/test/vstest-console-options.md	✅Succeeded

For more details, please refer to the build report.

prmerger-automator · 2026-07-17T11:01:05Z

PRMerger Results

Issue	Description
File Change Percent	This PR contains file(s) with more than 30% file change.

Copilot

Pull request overview

This PR enriches the Visual Studio VSTest documentation by expanding the vstest.console.exe reference with practical guidance (exit codes, shell escaping, blame dump options, response files, and option clarifications) and by updating related .runsettings and migration pages to include command-line override guidance and to replace archived microsoft/vstest-docs links with the maintained microsoft/vstest repo.

Changes:

Expanded vstest.console.exe option documentation (exit codes, /TestCaseFilter shell escaping, /Blame dump options, /Environment, response files, and updated upstream links).
Added a new section describing command-line runsettings overrides (including shell quoting notes, including zsh).
Updated remaining archived cross-repo links to point to microsoft/vstest.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/test/vstest-console-options.md	Adds new operational guidance (exit codes, filter escaping, blame dump options, env vars, response files) and updates upstream references.
docs/test/configure-unit-tests-by-using-a-dot-runsettings-file.md	Documents command-line runsettings overrides and links to maintained upstream guidance.
docs/test/migrate-testsettings-to-runsettings.md	Updates archived RFC link to the maintained `microsoft/vstest` location.

-|**/Blame**|Runs the tests in blame mode. This option is helpful in isolating problematic tests that cause the test host to crash. When a crash is detected, it creates a sequence file in `TestResults/<Guid>/<Guid>_Sequence.xml` that captures the order of tests that were run before the crash. For more information, see [Blame data collector](https://github.com/Microsoft/vstest-docs/blob/main/docs/extensions/blame-datacollector.md).|
-|**/Diag:[*file name*]**|Writes diagnostic trace logs to the specified file.|
+|**/Logger:[*uri/friendlyname*]**|Specify a logger for test results. Specify the parameter multiple times to enable multiple loggers.<br />Example: To log results into a Visual Studio Test Results File (TRX), use<br />**/Logger:trx**<br />**[;LogFileName=\<Defaults to unique file name>]**<br />Use `LogFilePrefix=<prefix>` instead of `LogFileName` to keep a separate, timestamped file per run. `LogFileName` sets an explicit name and overwrites the previous file, whereas `LogFilePrefix` doesn't.<br />For more information, see [Logging example](#logging-example).|
+|**/ListTests:[*file name*]**|Lists discovered tests from the given test container. Short form: **/lt**.<br />Note: The `/TestCaseFilters` option has no effect when listing tests; it only controls which tests get run.|


 ```

-If you're interested in reading more on how the *.testsettings* options convert to *.runsettings* you can find more implementation details in the [open source test platform repository](https://github.com/microsoft/vstest-docs/blob/main/RFCs/0023-TestSettings-Deprecation.md#migration) on GitHub.
+If you're interested in reading more on how the *.testsettings* options convert to *.runsettings* you can find more implementation details in the [open source test platform repository](https://github.com/microsoft/vstest/blob/main/docs/RFCs/0023-TestSettings-Deprecation.md#migration) on GitHub.


Court72 · 2026-07-17T14:58:35Z

@BillWagner, @RoseHJM

Can you review the proposed changes?

Important: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

azat-msft and others added 7 commits July 13, 2026 16:29

Fix vstest docs links and runsettings CLI guidance

bc9407e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e840b63-ad95-40c2-9ef8-5f2fcc4cfdaa

Apply suggestions from code review

bc282e7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

prmerger-automator Bot added the do-not-merge label Jul 17, 2026

azat-msft mentioned this pull request Jul 17, 2026

Update VSTest docs: fix archived cross-links, add runsettings CLI override and logger catalog #11396

Closed

prmerger-automator Bot added change sent to author test-tools/subsvc visual-studio-windows/svc labels Jul 17, 2026

azat-msft added 2 commits July 17, 2026 12:45

prmerger-automator Bot added the needs-human-review label Jul 17, 2026

Court72 requested a review from Copilot July 17, 2026 14:43

Copilot started reviewing on behalf of Court72 July 17, 2026 14:44 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

prmerger-automator Bot added the aq-pr-triaged tracking label for the PR review team label Jul 17, 2026

Court72 requested review from BillWagner and RoseHJM July 17, 2026 14:58

Court72 assigned BillWagner and RoseHJM Jul 17, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Enrich VSTest CLI docs: exit codes, filter/shell escaping, blame dumps, option gaps + archived-link cleanup#11401

Enrich VSTest CLI docs: exit codes, filter/shell escaping, blame dumps, option gaps + archived-link cleanup#11401
azat-msft wants to merge 10 commits into
MicrosoftDocs:mainfrom
azat-msft:vstest-docs-cli-enrichment

azat-msft commented Jul 17, 2026

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Court72 commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

azat-msft commented Jul 17, 2026

What changed

Propagation approach

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

✅ Validation status: passed

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

PRMerger Results

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

✅ Validation status: passed

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

PRMerger Results

Uh oh!

learn-build-service-prod Bot commented Jul 17, 2026

✅ Validation status: passed

Uh oh!

prmerger-automator Bot commented Jul 17, 2026

PRMerger Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Court72 commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants