diff --git a/pkgs/test/lib/src/runner/browser/compilers/dart2js.dart b/pkgs/test/lib/src/runner/browser/compilers/dart2js.dart
index 99ff31e3c..3cd67453b 100644
--- a/pkgs/test/lib/src/runner/browser/compilers/dart2js.dart
+++ b/pkgs/test/lib/src/runner/browser/compilers/dart2js.dart
@@ -174,6 +174,8 @@ class Dart2JsSupport extends CompilerSupport with JsHtmlWrapper {
   @override
   (Uri, Future<WebSocketChannel>) get webSocket {
     var completer = Completer<WebSocketChannel>.sync();
+    // Note: the WebSocketChannel type below is needed for compatibility with
+    // package:shelf_web_socket v2.
     var path =
         _webSocketHandler.create(webSocketHandler((WebSocketChannel ws, _) {
       completer.complete(ws);
diff --git a/pkgs/test/lib/src/runner/browser/compilers/dart2wasm.dart b/pkgs/test/lib/src/runner/browser/compilers/dart2wasm.dart
index 825011bfd..31ad66152 100644
--- a/pkgs/test/lib/src/runner/browser/compilers/dart2wasm.dart
+++ b/pkgs/test/lib/src/runner/browser/compilers/dart2wasm.dart
@@ -180,6 +180,8 @@ class Dart2WasmSupport extends CompilerSupport with WasmHtmlWrapper {
   @override
   (Uri, Future<WebSocketChannel>) get webSocket {
     var completer = Completer<WebSocketChannel>.sync();
+    // Note: the WebSocketChannel type below is needed for compatibility with
+    // package:shelf_web_socket v2.
     var path =
         _webSocketHandler.create(webSocketHandler((WebSocketChannel ws, _) {
       completer.complete(ws);
diff --git a/pkgs/test/lib/src/runner/browser/compilers/precompiled.dart b/pkgs/test/lib/src/runner/browser/compilers/precompiled.dart
index bff16d68d..9cf44aaf4 100644
--- a/pkgs/test/lib/src/runner/browser/compilers/precompiled.dart
+++ b/pkgs/test/lib/src/runner/browser/compilers/precompiled.dart
@@ -137,6 +137,8 @@ abstract class PrecompiledSupport extends CompilerSupport {
   @override
   (Uri, Future<WebSocketChannel>) get webSocket {
     var completer = Completer<WebSocketChannel>.sync();
+    // Note: the WebSocketChannel type below is needed for compatibility with
+    // package:shelf_web_socket v2.
     var path =
         _webSocketHandler.create(webSocketHandler((WebSocketChannel ws, _) {
       completer.complete(ws);
diff --git a/pkgs/test/test/runner/browser/code_server.dart b/pkgs/test/test/runner/browser/code_server.dart
index 916f7647c..1aba5dea5 100644
--- a/pkgs/test/test/runner/browser/code_server.dart
+++ b/pkgs/test/test/runner/browser/code_server.dart
@@ -59,6 +59,8 @@ class CodeServer {
   /// future that will complete to the WebSocket.
   Future<WebSocketChannel> handleWebSocket() {
     var completer = Completer<WebSocketChannel>();
+    // Note: the WebSocketChannel type below is needed for compatibility with
+    // package:shelf_web_socket v2.
     _handler.expect('GET', '/', webSocketHandler((WebSocketChannel ws, _) {
       completer.complete(ws);
     }));