Merged
Conversation
Youssef1313
reviewed
Feb 25, 2026
docs/core/testing/microsoft-testing-platform-troubleshooting.md
Outdated
Show resolved
Hide resolved
Youssef1313
reviewed
Feb 25, 2026
Evangelink
requested review from
a team,
gewarren and
meaghanlewis
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors the Microsoft.Testing.Platform (MTP) documentation to improve navigation and organization. It shifts from an extension-centric structure to a feature-centric structure, making it easier for users to find the information they need based on their goals rather than navigating through generic "extensions" categories.
Changes:
- Adds new test platforms overview page to help users choose between VSTest and MTP
- Reorganizes MTP documentation from extension categories to feature-specific pages (terminal output, test reports, code coverage, crash/hang dumps, retry, hot reload, fakes, OpenTelemetry, telemetry)
- Creates consolidated CLI options reference page
- Merges exit codes and FAQ content into unified troubleshooting page
- Splits architecture documentation into separate pages for test frameworks vs extensions
- Updates TOC for better navigation hierarchy
- Establishes comprehensive redirects for all renamed/deleted pages
Reviewed changes
Copilot reviewed 40 out of 40 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/core/testing/test-platforms-overview.md | New overview page to help users choose between VSTest and MTP platforms |
| docs/core/testing/microsoft-testing-platform-features.md | New feature overview page replacing generic extensions page |
| docs/core/testing/microsoft-testing-platform-cli-options.md | New consolidated CLI reference replacing scattered option documentation |
| docs/core/testing/microsoft-testing-platform-troubleshooting.md | New troubleshooting page consolidating exit codes and FAQ |
| docs/core/testing/microsoft-testing-platform-terminal-output.md | Feature-specific page extracted from extensions-output.md |
| docs/core/testing/microsoft-testing-platform-test-reports.md | Feature-specific page extracted from extensions-test-reports.md |
| docs/core/testing/microsoft-testing-platform-code-coverage.md | Feature-specific page extracted from extensions-code-coverage.md |
| docs/core/testing/microsoft-testing-platform-crash-hang-dumps.md | Feature-specific page extracted from extensions-diagnostics.md |
| docs/core/testing/microsoft-testing-platform-retry.md | Feature-specific page extracted from extensions-policy.md |
| docs/core/testing/microsoft-testing-platform-hot-reload.md | Feature-specific page extracted from extensions-hosting.md |
| docs/core/testing/microsoft-testing-platform-fakes.md | Feature-specific page from extensions-fakes.md |
| docs/core/testing/microsoft-testing-platform-open-telemetry.md | New OpenTelemetry feature page |
| docs/core/testing/microsoft-testing-platform-telemetry.md | Updated telemetry page with auto-registration info |
| docs/core/testing/microsoft-testing-platform-run-and-debug.md | Extracted run/debug content from intro page |
| docs/core/testing/microsoft-testing-platform-architecture-test-framework.md | Separated test framework architecture from extensions |
| docs/core/testing/microsoft-testing-platform-architecture-extensions.md | Refocused on extensions architecture only |
| docs/core/testing/microsoft-testing-platform-intro.md | Streamlined overview with navigation to other pages |
| docs/core/testing/migrating-vstest-microsoft-testing-platform.md | Updated links and fixed missing quote |
| docs/navigate/devops-testing/toc.yml | Reorganized TOC structure to match new organization |
| .openpublishing.redirection.core.json | Added comprehensive redirects for all moved/renamed pages |
| Various other files | Updated internal links to point to renamed pages |
meaghanlewis
approved these changes
Feb 27, 2026
Contributor
meaghanlewis
left a comment
meaghanlewis
left a comment
There was a problem hiding this comment.
These changes LGTM. Left a handful of suggestions for you to consider.
docs/core/testing/microsoft-testing-platform-crash-hang-dumps.md
Outdated
Show resolved
Hide resolved
Youssef1313
reviewed
Feb 28, 2026
Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
…-bridge.md Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
Co-authored-by: Meaghan Osagie (Lewis) <mosagie@microsoft.com>
Youssef1313
reviewed
Mar 2, 2026
|
|
||
| ## How to choose your platform | ||
|
|
||
| Use the following scenarios to choose quickly. |
Member
There was a problem hiding this comment.
We should probably have also packaged WinUI and UWP, which don't work under MTP today.
Youssef1313
reviewed
Mar 2, 2026
| | Use case | Choose | Why | | ||
| |---|---|---| | ||
| | You need Native AOT or trimming test execution scenarios. | Microsoft.Testing.Platform | MTP supports these modern deployment scenarios, while VSTest doesn't. | | ||
| | You need to mix .NET tests and non-.NET test adapters (for example JavaScript or C++ adapters). | VSTest | VSTest supports mixed-language adapter scenarios, while MTP is .NET-specific. | |
Member
There was a problem hiding this comment.
It's still possible to do that mix if you know what you're doing.
For example, I can have my global.json set to MTP, run all .NET tests with dotnet test normally. And then use vstest.console for C++ or JS
Youssef1313
reviewed
Mar 2, 2026
| | You need Native AOT or trimming test execution scenarios. | Microsoft.Testing.Platform | MTP supports these modern deployment scenarios, while VSTest doesn't. | | ||
| | You need to mix .NET tests and non-.NET test adapters (for example JavaScript or C++ adapters). | VSTest | VSTest supports mixed-language adapter scenarios, while MTP is .NET-specific. | | ||
| | You want test projects to behave like regular executables (`dotnet run`, direct executable run, `dotnet watch`, and startup-project F5 flows). | Microsoft.Testing.Platform | MTP is executable-first, so test apps run like standard .NET apps in local and CI workflows. | | ||
| | You rely on long-established integrations across Microsoft and non-Microsoft tooling. | VSTest | VSTest has the longest compatibility track record across existing products, tasks, and pipelines. | |
Member
There was a problem hiding this comment.
Lots of non-MS tooling is having MTP support, or at least there are ongoing efforts on that space. I'm not sure if we should be mentioning this.
Youssef1313
reviewed
Mar 2, 2026
| | You prioritize reproducibility and tighter control of extension loading across machines. | Microsoft.Testing.Platform | MTP favors explicit, build-time extension registration, which reduces machine-dependent behavior from dynamically discovered components and can simplify security review. | | ||
| | You need a minimal core with optional features that you can disable per environment. | Microsoft.Testing.Platform | MTP uses a lightweight core with opt-in extensions. If an extension introduces unsupported dependencies or version conflicts in a specific environment, you can remove or disable that extension. | | ||
| | You prefer strict defaults and explicit behavior. | Microsoft.Testing.Platform | MTP favors deterministic execution with explicit checks. For example, it can fail when no tests run, reduce environment-dependent variability, and avoid implicit discovery and execution heuristics. | | ||
| | You prefer softer, broad backward-compatible defaults. | VSTest | VSTest prioritizes compatibility-oriented defaults for diverse, existing toolchains. | |
Member
There was a problem hiding this comment.
This might give wrong impression that we don't care about backcompat for MTP.
Youssef1313
reviewed
Mar 2, 2026
| |---|---|---| | ||
| | IDE integration | Mature integration across Visual Studio and other tools that depend on VSTest protocol and adapters. | Supported in Visual Studio and Visual Studio Code scenarios, with ongoing integration work in parts of the ecosystem. | | ||
| | CI and external tools | Broad support across long-established Microsoft and non-Microsoft tools and tasks. In Azure DevOps, you can use either the VSTest task (`VSTest@3`, `vstest.console`) or the .NET task (`DotNetCoreCLI@2`, `dotnet test`). | Works in CI and modern .NET workflows, but some third-party integrations might still lag behind VSTest. In Azure DevOps, use the .NET task (`DotNetCoreCLI@2`, `dotnet test`). | | ||
| | `dotnet test` behavior | Default VSTest mode. VSTest arguments and behavior apply. | Native MTP mode is available in .NET 10 SDK and later. Before .NET 10 SDK, MTP ran through VSTest mode with limitations (`TestingPlatformDotnetTestSupport`, plus the extra `--` argument separator). | |
Member
There was a problem hiding this comment.
I wouldn't care about mentioning TestingPlatformDotnetTestSupport and older SDKs. It's going to die anyway.
Youssef1313
reviewed
Mar 2, 2026
| --- | ||
|
|
||
| # Microsoft.Testing.Platform extensibility | ||
| # Build extensions |
Member
There was a problem hiding this comment.
I think we should keep the header mentioning the product name. For example, Build extensions for Microsoft.Testing.Platform.
Youssef1313
reviewed
Mar 2, 2026
| `CancelledTestNodeStateProperty` informs the testing platform that this `TestNode` has failed due to cancellation. | ||
| For the full extension point summary and in-process/out-of-process concepts, see [Create custom extensions](./microsoft-testing-platform-architecture.md). | ||
|
|
||
| ## Other extensibility points |
Member
There was a problem hiding this comment.
Very weird the first H2 is "Other extensibility points". I would say ## Extensibility points and it's already clear that ITestFramework isn't covered by this article.
Youssef1313
reviewed
Mar 2, 2026
|
|
||
| For the full extension point summary and in-process/out-of-process concepts, see [Create custom extensions](./microsoft-testing-platform-architecture.md). | ||
|
|
||
| If you're migrating an existing VSTest-based test framework to Microsoft.Testing.Platform, use the [VSTest Bridge](./microsoft-testing-platform-extensions-vstest-bridge.md) extension to simplify the transition. |
Member
There was a problem hiding this comment.
We should encourage being fully MTP rather than going the bridge way.
Youssef1313
reviewed
Mar 2, 2026
| public sealed class CreateTestSessionContext : TestSessionContext | ||
| { | ||
| public SessionUid SessionUid { get; } | ||
| public ClientInfo Client { get; } |
Youssef1313
reviewed
Mar 2, 2026
Comment on lines
+121
to
+125
| public sealed class ClientInfo | ||
| { | ||
| public string Id { get; } | ||
| public string Version { get; } | ||
| } |
Youssef1313
reviewed
Mar 2, 2026
| ``` | ||
|
|
||
| The `SessionUid` serves as the unique identifier for the current test session, providing a logical connection to the session's results. | ||
| The `ClientInfo` provides details about the entity invoking the test framework. This information can be utilized by the test framework to modify its behavior. For example, as of the time this document was written, a console execution would report a client name such as "testingplatform-console". |
Member
There was a problem hiding this comment.
This should be removed as well.
Youssef1313
reviewed
Mar 2, 2026
| The return object is a `CloseTestSessionResult`: | ||
|
|
||
| ```csharp | ||
| public sealed class CreateTestSessionResult |
Member
There was a problem hiding this comment.
Typo? It should be CloseTestSessionResult
Youssef1313
reviewed
Mar 2, 2026
| public class TestSessionContext | ||
| { | ||
| public SessionUid SessionUid { get; } | ||
| public ClientInfo Client { get; } |
Youssef1313
reviewed
Mar 2, 2026
Comment on lines
+232
to
+233
| // This is experimental and intended for future use, please disregard for now. | ||
| public ITestExecutionFilter Filter { get; } |
Member
There was a problem hiding this comment.
It's no longer marked as experimental
Youssef1313
reviewed
Mar 2, 2026
Comment on lines
+267
to
+268
| // This is experimental and intended for future use, please disregard for now. | ||
| public ITestExecutionFilter Filter { get; } |
Youssef1313
reviewed
Mar 2, 2026
| public PropertyBag Properties { get; init; } = new(); | ||
| } | ||
|
|
||
| public sealed class TestNodeUid(string value) |
Youssef1313
reviewed
Mar 2, 2026
Comment on lines
+502
to
+505
| `TestMethodIdentifierProperty` is a unique identifier for a test method, adhering to the ECMA-335 standard. | ||
|
|
||
| > [!NOTE] | ||
| > The data needed to create this property can be conveniently obtained using the .NET reflection feature, using types from the `System.Reflection` namespace. |
Member
There was a problem hiding this comment.
There is nothing well defined in that space. And I don't think reflection is following ECMA-335
Youssef1313
reviewed
Mar 2, 2026
| # VSTest Bridge extension | ||
|
|
||
| This extension provides a compatibility layer with VSTest allowing the test frameworks depending on it to continue supporting running in VSTest mode (`vstest.console.exe`, usual `dotnet test`, `VSTest task` on AzDo, Test Explorers of Visual Studio and Visual Studio Code...). This extension is shipped as part of [Microsoft.Testing.Extensions.VSTestBridge](https://www.nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge) package. | ||
| This extension provides a compatibility layer with VSTest allowing the test frameworks depending on it to continue supporting running in VSTest mode (`vstest.console.exe`, `dotnet test`, `VSTest task` on Azure DevOps, Test Explorers of Visual Studio and Visual Studio Code). This extension is shipped as part of [Microsoft.Testing.Extensions.VSTestBridge](https://nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge) NuGet package. |
Member
There was a problem hiding this comment.
As we have dotnet test supporting both MTP and VSTEst, and also TE supporting both, I think it's confusing and might be understood as MTP doesn't support those. IMO the following is much more clear.
Suggested change
| This extension provides a compatibility layer with VSTest allowing the test frameworks depending on it to continue supporting running in VSTest mode (`vstest.console.exe`, `dotnet test`, `VSTest task` on Azure DevOps, Test Explorers of Visual Studio and Visual Studio Code). This extension is shipped as part of [Microsoft.Testing.Extensions.VSTestBridge](https://nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge) NuGet package. | |
| This extension provides a compatibility layer with VSTest allowing test frameworks that are already implemented with VSTest to: | |
| 1. run easily with Microsoft.Testing.Platform without a major rewrite. | |
| 2. support both VSTest and Microsoft.Testing.Platform with the same test framework implementation. | |
| This extension is shipped as part of [Microsoft.Testing.Extensions.VSTestBridge](https://nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge) NuGet package. |
Youssef1313
reviewed
Mar 2, 2026
| --- | ||
| title: Microsoft.Testing.Platform Fakes extension | ||
| description: Learn about the various Microsoft.Testing.Platform Fakes extension capabilities and how to use it. | ||
| title: Microsoft.Testing.Platform Microsoft Fakes |
Member
There was a problem hiding this comment.
Microsoft Fakes support for Microsoft.Testing.Platform is more clear IMO
Youssef1313
reviewed
Mar 2, 2026
| - Need hot reload support: [Hot Reload](./microsoft-testing-platform-hot-reload.md) (extension) | ||
| - Need Microsoft Fakes support: [Microsoft Fakes](./microsoft-testing-platform-fakes.md) (extension) | ||
| - Need OpenTelemetry traces and metrics: [OpenTelemetry](./microsoft-testing-platform-open-telemetry.md) (extension) | ||
| - Need telemetry opt-out information: [Telemetry](./microsoft-testing-platform-telemetry.md) (extension) |
Member
There was a problem hiding this comment.
I'm having hard time understanding what you mean by "Need telemetry opt-out information"
Youssef1313
reviewed
Mar 2, 2026
|
|
||
| ```csharp | ||
| var builder = await TestApplication.CreateBuilderAsync(args); | ||
| builder.TestHost.AddRetryProvider(); |
Member
There was a problem hiding this comment.
Suggested change
| builder.TestHost.AddRetryProvider(); | |
| builder.AddRetryProvider(); |
Youssef1313
reviewed
Mar 2, 2026
|
|
||
| ```csharp | ||
| var builder = await TestApplication.CreateBuilderAsync(args); | ||
| builder.AddTrxReportProvider(); |
Member
There was a problem hiding this comment.
It should be noted that with manual registration, it's best to register it last, until we implement a better way that doesn't depend on registration order.
Youssef1313
reviewed
Mar 2, 2026
| | Option | Description | | ||
| |---|---| | ||
| | `--report-trx` | Generates the TRX report. | | ||
| | `--report-trx-filename` | The name of the generated TRX report. The default name matches the following format `<UserName>_<MachineName>_<yyyy-MM-dd HH:mm:ss>.trx`. | |
Member
There was a problem hiding this comment.
It's ss.fffffff not ss. We try to get high precision datetime to avoid conflicts when using the default file name.
Youssef1313
reviewed
Mar 2, 2026
| | Option | Description | | ||
| |---|---| | ||
| | `--report-trx` | Generates the TRX report. | | ||
| | `--report-trx-filename` | The name of the generated TRX report. The default name matches the following format `<UserName>_<MachineName>_<yyyy-MM-dd HH:mm:ss>.trx`. | |
Member
There was a problem hiding this comment.
The file name doesn't contain spaces or colons. That space and the colons are underscores.
Youssef1313
reviewed
Mar 2, 2026
| | `3` | The exit code `3` indicates that the test session was aborted. A session can be aborted using <kbd>Ctrl</kbd>+<kbd>C</kbd>, as an example. | | ||
| | `4` | The exit code `4` indicates that the setup of used extensions is invalid and the tests session cannot run. | | ||
| | `5` | The exit code `5` indicates that the command line arguments passed to the test app are invalid. | | ||
| | `6` | The exit code `6` indicates that the test session is using a non-implemented feature. | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Explain what are test platforms and how to choose the one to use. Add links to the test frameworks, because that's what people know and will use.
Also refactor MTP doc so that it's easier to browse and look for the info.
Internal previews
Toggle expand/collapse