Add WebSocket transport for the dotnettestcli protocol (browser-wasm support)

[Amaury Levé (Evangelink)]

Summary

Decouples the dotnet test pipe protocol (a.k.a. dotnettestcli) from System.IO.Pipes so it can also bootstrap over a WebSocket transport — needed for runtimes without named-pipe support (browser-wasm) — while keeping the existing --server dotnettestcli --dotnet-test-pipe <name> behavior and framing/serializer contract unchanged.

Protocol and transport are decoupled: DotnetTestConnection now depends on a small IClient abstraction (implemented identically in shape by NamedPipeClient and the new DotnetTestWebSocketClient), and the shared framing in NamedPipeConnectionBase operates on a plain Stream instead of PipeStream specifically.

What's new

• Core refactor: NamedPipeConnectionBase.WriteMessageAsync/ReadNextMessageAsync widened from PipeStream to Stream (pipe-drain behavior isolated behind an is PipeStream check, so named-pipe behavior is unaffected).
• New WebSocket transport (ServerMode/DotnetTest/Transport/):
  • DotnetTestWebSocketClient — IClient implementation, handles connect/auth/request-reply.
  • ClientWebSocketDuplexStream — adapts System.Net.WebSockets.WebSocket to a Stream on non-browser runtimes.
  • BrowserWebSocketDuplexStream — talks to the host's native WebSocket via [JSImport]/[JSExport] JS interop. Real browsers supply WebSocket directly; Node 20 hosts use its built-in implementation via --experimental-websocket, with no npm dependency.
• CLI: new hidden options --dotnet-test-transport {pipe|websocket}, --dotnet-test-websocket-endpoint, --dotnet-test-websocket-token, with validation that rejects conflicting/incomplete option combinations, malformed/non-WebSocket endpoints, empty tokens, and the named-pipe transport on browser-wasm/wasi-wasm early with actionable errors.
• Handshake: additive Transport property (id 16, NamedPipe/WebSocket) for diagnostics; ProtocolConstants.SupportedVersions bumped to 1.5.0. Framing and serializer formats are unchanged; older peers ignore the additive property.
• Auth: per-run token passed as a query-string parameter (browsers can't set custom headers on the WebSocket upgrade handshake — same approach ASP.NET Core SignalR uses); never logged (enforced by a dedicated command-line redactor).
• Docs: docs/mstest-runner-protocol/004-protocol-dotnet-test-pipe.md updated — the intro now states protocol vs. transport, and §15 documents the WebSocket transport, its security model, validation, Node/browser bootstrap, target-runtime coverage, and known gaps.

Known gaps (documented in doc §15.6, not silently degraded)

• The reverse server-control channel (session cancellation) stays named-pipe-only; disabled on browser/wasi (same graceful fallback as an old SDK never advertising it).
• wasi-wasm has no transport implemented yet (no ClientWebSocket, no JS host to interop with) — command-line validation rejects it outright with an actionable error.
• stdio transport was considered and deliberately not implemented (risk of corrupting user/extension console output by multiplexing frames onto it).

Review process

This PR went through multiple automated and independent review rounds. Findings fixed include browser connect/read/write cancellation, legal zero-length WebSocket messages, abrupt connection loss, diagnostic token/endpoint redaction, CLI endpoint/token validation, immutable InternalAPI baseline tracking, transport handshake assertions, and browser-wasm target-runtime coverage.

The latest CI follow-up fixed Node 20 hosting: Node 20.20 does not expose WebSocket globally unless launched with --experimental-websocket. The browser-wasm WebSocket acceptance bootstrap now passes that built-in runtime flag rather than adding an external npm polyfill. Real-browser bootstrap is unchanged.

Testing

• Full solution build and pack (.\build.cmd -pack -bl) green.
• Microsoft.Testing.Platform.UnitTests: 1485 tests passing.
• Browser-wasm WebSocket acceptance tests under Node: 3/3 passing, including authenticated protocol traffic, stalled-connect cancellation, pending-read cancellation/message ordering, zero-length messages, and pre-cancelled writes.
• Microsoft.Testing.Platform.DotnetTestProtocolContract.UnitTests: 24 tests passing (protocol contract unaffected).
• DotnetTestPipe acceptance tests: 19 passing (named-pipe transport behavior unaffected).
• HelpInfoTests/HelpInfoAllExtensionsTests: 30 passing (new CLI options reflected correctly).
• MSTest DotnetTestCliTests: 6 passing.
• DotnetTestWebSocketClientTests: real loopback WebSocket round-trip, auth URI, large-message, connection-loss, cancellation, and zero-length-message-before-reply coverage.
• CommandLineArgumentsRedactorTests: token and endpoint sanitization, missing values, repeated options, option-shaped secrets, and inline forms.

Follow-up work (out of scope, not part of this repo)

The SDK-side loopback WebSocket gateway/listener (accepting the outbound connection, validating the token, speaking the existing binary frame format) needs to be implemented in dotnet/sdk. When launching a browser-wasm bundle under Node 20, the SDK must pass --experimental-websocket to Node. Vendoring the updated Constants.cs/ObjectFieldIds.cs there is optional since the new Transport handshake property is additive/ignorable.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com
Copilot-Session: 282499c0-c68f-41eb-890a-ad47bb78ce54

[Copilot]

Pull request overview

Adds WebSocket transport support for the dotnettestcli protocol, primarily enabling browser-wasm while retaining named-pipe compatibility.

Changes:

• Adds browser and non-browser WebSocket stream adapters.
• Adds transport selection, validation, authentication, and handshake metadata.
• Updates protocol documentation, resources, API baselines, and tests.

Show a summary per file

File	Description
test/UnitTests/Microsoft.Testing.Platform.UnitTests/IPC/ProtocolTests.cs	Updates protocol-version expectation.
test/UnitTests/Microsoft.Testing.Platform.UnitTests/IPC/DotnetTestWebSocketClientTests.cs	Adds non-browser WebSocket transport tests.
test/UnitTests/Microsoft.Testing.Platform.UnitTests/CommandLine/PlatformCommandLineProviderTests.cs	Tests transport-option validation.
test/UnitTests/Microsoft.Testing.Platform.DotnetTestProtocolContract.UnitTests/DotnetTestProtocolContractTests.cs	Pins transport contract constants.
test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/HelpInfoTests.cs	Updates core help expectations.
test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/HelpInfoAllExtensionsTests.cs	Updates extended help expectations.
test/IntegrationTests/Microsoft.Testing.Platform.Acceptance.IntegrationTests/DotnetTestPipe/DotnetTestPipeBaselineTests.cs	Updates named-pipe protocol baseline.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/DotnetTestWebSocketClient.cs	Implements the WebSocket protocol client.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/ClientWebSocketDuplexStream.cs	Adapts .NET WebSockets to Stream.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/BrowserWebSocketDuplexStream.cs	Adds browser JavaScript WebSocket interop.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/IPC/DotnetTestDataConsumer.cs	Enables browser use of the consumer.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/IPC/Constants.cs	Adds transport constants and protocol 1.5.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/DotnetTestHelper.cs	Resolves the selected transport.
src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/DotnetTestConnection.cs	Dispatches protocol traffic by transport.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.zh-Hant.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.zh-Hans.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.tr.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.ru.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.pt-BR.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.pl.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.ko.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.ja.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.it.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.fr.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.es.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.de.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.cs.xlf	Adds localized resource entries.
src/Platform/Microsoft.Testing.Platform/Resources/PlatformResources.resx	Defines transport messages and descriptions.
src/Platform/Microsoft.Testing.Platform/Resources/PlatformResources.cs	Exposes validation resources to tests.
src/Platform/Microsoft.Testing.Platform/IPC/NamedPipeConnectionBase.cs	Generalizes framing from pipes to streams.
src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Unshipped.txt	Records new internal APIs.
src/Platform/Microsoft.Testing.Platform/InternalAPI/InternalAPI.Shipped.txt	Removes prior framing signatures.
src/Platform/Microsoft.Testing.Platform/CommandLine/PlatformCommandLineProvider.cs	Adds transport CLI options and validation.
src/Platform/Microsoft.Testing.Extensions.TrxReport/InternalAPI/InternalAPI.Unshipped.txt	Records generalized framing APIs.
src/Platform/Microsoft.Testing.Extensions.TrxReport/InternalAPI/InternalAPI.Shipped.txt	Removes prior framing signatures.
src/Platform/Microsoft.Testing.Extensions.Retry/InternalAPI/InternalAPI.Unshipped.txt	Records generalized framing APIs.
src/Platform/Microsoft.Testing.Extensions.Retry/InternalAPI/InternalAPI.Shipped.txt	Removes prior framing signatures.
src/Platform/Microsoft.Testing.Extensions.MSBuild/InternalAPI.Unshipped.txt	Records generalized framing APIs.
src/Platform/Microsoft.Testing.Extensions.MSBuild/InternalAPI.Shipped.txt	Removes prior framing signatures.
src/Platform/Microsoft.Testing.Extensions.HangDump/InternalAPI/InternalAPI.Unshipped.txt	Records generalized framing APIs.
src/Platform/Microsoft.Testing.Extensions.HangDump/InternalAPI/InternalAPI.Shipped.txt	Removes prior framing signatures.
docs/mstest-runner-protocol/004-protocol-dotnet-test-pipe.md	Documents transport-neutral framing and WebSockets.

Review details

• Files reviewed: 42/42 changed files
• Comments generated: 10
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (2)

src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/BrowserWebSocketDuplexStream.cs:172

• The browser connection attempt does not observe cancellationToken: after the module import completes, OpenAsync has no token and can remain pending until the browser's network timeout. This can hang startup/shutdown indefinitely for an unreachable endpoint, unlike the non-browser ClientWebSocket.ConnectAsync path. Please make the JS open operation abortable (closing the connecting socket on cancellation) and propagate OperationCanceledException.
  src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/BrowserWebSocketDuplexStream.cs:37
• This new NET-only internal type and its accessible members are missing from InternalAPI/net/InternalAPI.Unshipped.txt. The project includes that baseline for non-netstandard targets (Microsoft.Testing.Platform.csproj:90-91), and existing browser-only internals are tracked there (for example BrowserOutputDevice in InternalAPI/net/InternalAPI.Shipped.txt:16-17), so RS0016 will fail those builds.

• Files reviewed: 45/45 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (4)

src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/BrowserWebSocketDuplexStream.cs:37

• This framework-specific internal type is compiled for the net targets, but none of its type or override signatures are listed in InternalAPI/net/InternalAPI.Unshipped.txt. This project explicitly includes that API baseline for non-netstandard targets (Microsoft.Testing.Platform.csproj:90-91), and the analogous BrowserOutputDevice is tracked in InternalAPI/net/InternalAPI.Shipped.txt:16-17; therefore RS0016 will fail under warnings-as-errors. Add all tracked BrowserWebSocketDuplexStream members to the net-specific unshipped file.
  src/Platform/Microsoft.Testing.Platform/ServerMode/DotnetTest/Transport/BrowserWebSocketDuplexStream.cs:172
• The cancellation token is no longer observed once OpenAsync starts. If the browser WebSocket handshake stalls, IClient.ConnectAsync and platform startup can remain pending after shutdown cancellation. Make the JS-side open operation cancellable, or race it against the token and ensure any socket that opens after cancellation is closed.
  src/Platform/Microsoft.Testing.Platform/CommandLine/PlatformCommandLineProvider.cs:278
• The endpoint is only checked for option presence, so values such as not-a-uri, https://..., or an empty string pass validation and later fail in CreateWebSocketClient/ClientWebSocket.ConnectAsync with an unhandled URI or scheme exception. Validate that the argument is an absolute ws:// or wss:// URI here so this CLI surface fails early with an actionable message.

            bool hasTransportOption = commandLineOptions.TryGetOptionArgumentList(DotNetTestTransportOptionKey, out string[]? transportArgs)
                && transportArgs is { Length: 1 };
            bool isWebSocketTransport = hasTransportOption && DotNetTestTransportWebSocketArgument.Equals(transportArgs![0], StringComparison.OrdinalIgnoreCase);
            bool hasEndpoint = commandLineOptions.IsOptionSet(DotNetTestWebSocketEndpointOptionKey);
            bool hasToken = commandLineOptions.IsOptionSet(DotNetTestWebSocketTokenOptionKey);

src/Platform/Microsoft.Testing.Platform/CommandLine/PlatformCommandLineProvider.cs:300

• This fallback error still says --dotnet-test-pipe is required, but the command now also supports WebSocket and on browser-wasm the suggested pipe option is explicitly unsupported. Report that either a pipe name or the complete WebSocket option set is required; otherwise the new valid transport is omitted and browser users are directed toward an impossible configuration.

            // 3. Nothing selects a transport at all (covers: no options given, or --dotnet-test-transport pipe
            // given explicitly without the required --dotnet-test-pipe name).
            if (!hasPipe && !isWebSocketTransport)
            {
                return ValidationResult.InvalidTask(string.Format(CultureInfo.InvariantCulture, PlatformResources.PlatformCommandLineDotnetTestCliRequiresPipe, DotnetTestCliProtocolName, DotNetTestPipeOptionKey));
            }

• Files reviewed: 45/45 changed files
• Comments generated: 8
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 43/43 changed files
• Comments generated: 3
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 43/43 changed files
• Comments generated: 3
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 48/48 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 48/48 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/Platform/Microsoft.Testing.Platform/CommandLine/CommandLineArgumentsRedactor.cs:61

• string.Replace treats the raw argument as an unrestricted substring, so short invalid endpoint/token values corrupt unrelated validation text. For example, an endpoint value of a replaces every a in the “requires an absolute…” diagnostic with the redaction marker. Redaction should target only the exact argument occurrence emitted by the parser/validator (ideally before formatting), rather than globally replacing arbitrary substrings in the completed message.

                error = error.Replace(original, RedactedPlaceholder);

• Files reviewed: 48/48 changed files
• Comments generated: 0 new
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 48/48 changed files
• Comments generated: 0 new
• Review effort level: Medium

[github-actions]

🧪 Test quality grade — PR #10118

Grade	Test	Notes
B (80–89)	new CommandLineHandlerTests. ParseAndValidateAsync_ ShortInvalidEndpoint_ DoesNotCorruptValidationError	Good regression guard with three meaningful assertions; the DoesNotContain("***REDACTED***bsolute", ...) assertion is cryptic without a comment — consider adding an inline note explaining that the single-char endpoint "a" was previously redacted, corrupting the word "absolute" in the error message.

_{This advisory comment was generated automatically. Grades are heuristic
and informational — they do not block merging. Re-run with
/grade-tests.}

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🤖 Automated content by GitHub Copilot. Generated by the Grade Tests on PR (on open / sync) workflow. · 27.2 AIC · ⌖ 6.06 AIC · ⊞ 8.9K · [◷]( · ◷)