Clarify XML docs for TestContext result/deployment directories

[Amaury Levé (Evangelink)]

Clarifies the XML documentation for the TestContext test-run deployment directory properties, addressing the confusion reported in #7698.

Problem

The docs for TestRunResultsDirectory and TestResultsDirectory were ambiguous and counter-intuitive. As reported in #7698, on a real run the values are:

• TestResultsDirectory: <TestRunDirectory>\In
• TestRunResultsDirectory: <TestRunDirectory>\In\<MachineName>

i.e. TestRunResultsDirectory is actually a child of TestResultsDirectory, despite the name suggesting the opposite.

Changes

Reworked the <summary> text (and added <remarks>/<code> examples) for the five related properties in TestContext:

• TestRunDirectory — documents the full layout with a concrete example.
• DeploymentDirectory — clarified it is the Out subdirectory.
• ResultsDirectory — clarified it is the In subdirectory; noted it currently equals TestResultsDirectory.
• TestRunResultsDirectory — explicitly documents it is a child of TestResultsDirectory (In\<MachineName>) with a worked example.
• TestResultsDirectory — clarified it is the In directory, equal to ResultsDirectory and the parent of TestRunResultsDirectory.

These triple-slash comments are the source for the learn.microsoft.com API reference pages, so the published docs get the clarification automatically.

Doc-only change; behavior is unchanged and identical under VSTest and MTP (the mapping lives in the shared MSTestAdapter.PlatformServices layer).

Fixes #7698

[Copilot]

Pull request overview

This PR updates the XML documentation on TestContext’s deployment/results directory properties in MSTest (TestFramework.Extensions) to clarify the on-disk layout and resolve confusion reported in #7698 (notably the TestResultsDirectory vs TestRunResultsDirectory relationship).

Changes:

• Expanded TestRunDirectory docs with a concrete directory-layout example.
• Clarified the intended meanings/relationships of DeploymentDirectory, ResultsDirectory, TestRunResultsDirectory, and TestResultsDirectory (including worked examples and remarks).

Show a summary per file

File	Description
src/TestFramework/TestFramework.Extensions/TestContext.cs	Reworks XML docs and adds remarks/examples for TestContext directory properties to reduce ambiguity.

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 4

[Amaury Levé (Evangelink)]

Note

🤖 Automated review by GitHub Copilot. Posted via a maintainer's GitHub token, so it appears under their account — the account owner did not write or approve this content personally. Generated by the Expert Code Review workflow. To request a follow-up action, reply by tagging @copilot directly.

✅ 22/22 dimensions clean — no findings.

---

Scope: Single .cs file, XML doc comments only. No logic, API, or behavioral changes.

Accuracy verified against the implementation:

TestRunDirectories.cs constructs the values exactly as the new docs describe:

• RootDeploymentDirectory → TestRunDirectory
• InDirectory = Path.Combine(root, "In") → ResultsDirectory and TestResultsDirectory (same value — confirmed by TestDeployment.cs which assigns InDirectory to both labels)
• InMachineNameDirectory = Path.Combine(InDirectory, Environment.MachineName) → TestRunResultsDirectory
• OutDirectory = Path.Combine(root, "Out") → DeploymentDirectory

The key clarification — that TestRunResultsDirectory is a child of TestResultsDirectory, despite the longer name — is factually correct and directly addresses #7698. The <code> example in the TestRunResultsDirectory remarks is an effective way to make this non-obvious relationship immediately obvious.

The choice to reference ResultsDirectory in the <summary> of TestRunResultsDirectory (the direct parent) while referencing TestResultsDirectory in the <remarks> (the confusing sibling) is intentional and correct — the remarks exist precisely to defuse the naming confusion between TestResultsDirectory and TestRunResultsDirectory.

🤖 Automated content by GitHub Copilot. Posted via a maintainer's GitHub token, so it appears under their account — the account owner did not write or approve this content personally. Generated by the Expert Code Review (on PR ready) workflow. · 396.7 AIC · ⌖ 12.3 AIC · ◷