dev-test: JSDOM's WebSocket in the browser environment

The browser environment replaces Node's Event with JSDOM's. Node's WebSocket
dispatches through Node's EventTarget, which rejects that Event, so no open,
message or error reached a listener and no connection ever came up: an
ApiPromise against a live node never became ready. JSDOM's WebSocket now
replaces Node's, as Event and CustomEvent already do. A spec completes a
handshake with a local server and receives a frame.

packages/dev-test/src/env/browser.spec.ts

@@ -1,6 +1,9 @@
 // Copyright 2017-2026 @pezkuwi/dev-test authors & contributors
 // SPDX-License-Identifier: Apache-2.0
 
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
+
 import { browser } from './browser.js';
 
 const all = browser();
@@ -61,4 +64,49 @@ describe('browser', () => {
     expect(() => window.dispatchEvent(new CustomEvent('custom', { detail: 1 }))).not.toThrow();
     expect(() => window.dispatchEvent(new Event('plain'))).not.toThrow();
   });
+
+  it('opens a WebSocket and exchanges a message', async () => {
+    // the smallest server that completes the RFC 6455 handshake and sends one text frame
+    const server = createServer();
+    // an upgraded socket leaves the server's tracking, so it is closed here
+    const sockets: { destroy: () => void }[] = [];
+
+    server.on('upgrade', (req, socket) => {
+      sockets.push(socket);
+
+      const accept = createHash('sha1')
+        .update(`${String(req.headers['sec-websocket-key'])}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+        .digest('base64');
+
+      socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+      socket.write(Buffer.from([0x81, 0x02, 0x68, 0x69]));
+    });
+
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+
+    const { port } = server.address() as { port: number };
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+
+    try {
+      const received = await new Promise<string>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('no message within 5s')), 5_000);
+
+        ws.onmessage = (event) => {
+          clearTimeout(timer);
+          resolve(String(event.data));
+        };
+
+        ws.onerror = () => {
+          clearTimeout(timer);
+          reject(new Error('WebSocket error'));
+        };
+      });
+
+      expect(received).toBe('hi');
+    } finally {
+      ws.close();
+      sockets.forEach((socket) => socket.destroy());
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
 });

packages/dev-test/src/env/browser.ts

@@ -9,8 +9,13 @@ import { JSDOM } from 'jsdom';
  * Constructors that Node defines as well. A DOM node only accepts an event
  * created in its own realm, so in the browser environment the JSDOM ones
  * replace Node's, as they do under jest-environment-jsdom.
+ *
+ * WebSocket follows from that: Node's own dispatches its events through
+ * Node's EventTarget, which rejects the JSDOM Event that replaced Node's, so
+ * no open, message or error ever reaches a listener and a connection never
+ * comes up. JSDOM's WebSocket dispatches events from its own realm.
  */
-export const BROWSER_OVERRIDES: readonly string[] = ['CustomEvent', 'Event'];
+export const BROWSER_OVERRIDES: readonly string[] = ['CustomEvent', 'Event', 'WebSocket'];
 
 /**
  * JSDOM does no layout, so no element ever changes size and the callback
@@ -62,6 +67,13 @@ function events (window: DOMWindow) {
   };
 }
 
+/** Network, see BROWSER_OVERRIDES for why WebSocket is JSDOM's */
+function network (window: DOMWindow) {
+  return {
+    WebSocket: window.WebSocket
+  };
+}
+
 /** Styles, geometry and the observers */
 function layout (window: DOMWindow) {
   return {
@@ -90,6 +102,7 @@ export function browser () {
     ...nodes(window),
     ...events(window),
     ...layout(window),
+    ...network(window),
     // All HTML Elements that are defined on the JSDOM window object.
     // (we copied as-is from the types definition). We cannot get this
     // via Object.keys(window).filter(...) so we have to specify explicitly