@specific.dev/spectest 0.102.0 → 0.104.0

package/src/browser-timezone.test.ts

@@ -0,0 +1,105 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { readRaw } from "./inspect.js";
+import {
+  acquirePersistentBrowser,
+  openBrowser,
+  prewarmViewPool,
+  type Browser,
+} from "./browser.js";
+
+interface Settings {
+  timezone: string;
+  locale: string;
+  language: string;
+  acceptLanguage: string;
+  winterOffset: number;
+  summerOffset: number;
+  number: string;
+}
+
+async function settings(browser: Browser): Promise<Settings> {
+  return readRaw(await browser.evaluate<Settings>("read initial regional settings", "window.settings")) as unknown as Settings;
+}
+
+describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("browser timezone and locale", () => {
+  let server: ReturnType<typeof Bun.serve>;
+  beforeAll(() => {
+    server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: request => new Response(`<script>
+        window.settings = {
+          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+          locale: Intl.DateTimeFormat().resolvedOptions().locale,
+          language: navigator.language,
+          acceptLanguage: ${JSON.stringify(request.headers.get("accept-language"))},
+          winterOffset: new Date("2026-01-15T12:00:00Z").getTimezoneOffset(),
+          summerOffset: new Date("2026-07-15T12:00:00Z").getTimezoneOffset(),
+          number: new Intl.NumberFormat().format(1234.5),
+        };
+      </script>`, { headers: { "content-type": "text/html" } }),
+    });
+  });
+  afterAll(() => server.stop(true));
+
+  test("applies both options before initial navigation and retains them after reload", async () => {
+    const browser = await openBrowser({ timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      const initial = await settings(browser);
+      expect(initial).toMatchObject({
+        timezone: "Europe/Stockholm", locale: "sv-SE", language: "sv-SE",
+        winterOffset: -60, summerOffset: -120, number: "1\u00a0234,5",
+      });
+      expect(initial.acceptLanguage.split(",")[0]).toBe("sv-SE");
+      await browser.reload();
+      expect(await settings(browser)).toEqual(initial);
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test.each([
+    { timezone: "Europe/Stockholm" },
+    { locale: "sv-SE" },
+  ])("bypasses the default view pool for %j without changing defaults", async options => {
+    const baseline = await openBrowser({ url: server.url.href });
+    let defaults: Settings;
+    try { defaults = await settings(baseline); } finally { await baseline.close(); }
+    await prewarmViewPool();
+    const browser = await openBrowser({ ...options, url: server.url.href });
+    try {
+      const actual = await settings(browser);
+      expect(actual.timezone).toBe(options.timezone ?? defaults.timezone);
+      expect(actual.language).toBe(options.locale ?? defaults.language);
+    } finally { await browser.close(); }
+    const pooled = await openBrowser({ url: server.url.href });
+    try { expect(await settings(pooled)).toEqual(defaults); } finally { await pooled.close(); }
+  }, 20000);
+
+  test("named sessions are isolated and reattachment keeps first-call settings", async () => {
+    const a = await acquirePersistentBrowser("regional-a", { timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      const b = await acquirePersistentBrowser("regional-b", { timezone: "America/New_York", locale: "en-US", url: server.url.href });
+      try {
+        expect(await settings(b.browser)).toMatchObject({ timezone: "America/New_York", language: "en-US", winterOffset: 300, summerOffset: 240 });
+        const original = await settings(a.browser);
+        expect(original).toMatchObject({ timezone: "Europe/Stockholm", language: "sv-SE" });
+        await a.detach();
+        const attached = await acquirePersistentBrowser("regional-a", { timezone: "UTC", locale: "en-US" });
+        expect(attached.attached).toBe(true);
+        await attached.browser.reload();
+        expect(await settings(attached.browser)).toEqual(original);
+        await attached.detach();
+      } finally { await b.browser.close(); }
+    } finally { await a.browser.close(); }
+  }, 20000);
+
+  test("mobile framing retains regional settings", async () => {
+    const browser = await openBrowser({ frame: "mobile", timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      expect(await settings(browser)).toMatchObject({ timezone: "Europe/Stockholm", language: "sv-SE", winterOffset: -60 });
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test("rejects an invalid timezone", async () => {
+    await expect(openBrowser({ timezone: "Invalid/Timezone" })).rejects.toThrow(/timezone/i);
+  }, 20000);
+});

package/src/browser.ts

@@ -35,6 +35,8 @@ import { fileURLToPath } from "node:url";
 
 import { generateId } from "./ids.js";
 import { rawFetch } from "./harness/raw-fetch.js";
+import { prepareMicrophoneFixture, type MicrophoneFixture } from "./harness/microphone-fixture.js";
+export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
 import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
 import type { DesktopChrome } from "./desktop.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
@@ -91,6 +93,17 @@ export interface BrowserOptions {
   frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: string;
+  /** IANA timezone, e.g. "Europe/Stockholm". Defaults to the host timezone.
+   * Set on first creation; inherited sessions keep their original timezone. */
+  timezone?: string;
+  /** Locale, e.g. "sv-SE", for navigator.language, Accept-Language and
+   * date/number formatting. Omit to use the browser's default locale.
+   * Set on first creation; inherited sessions keep their original locale. */
+  locale?: string;
+  /** Feed a WAV fixture through Chromium's native microphone capture.
+   * Set on the session's first creation; inherited sessions keep their source.
+   * Fixture sessions use a dedicated Chromium process for audio isolation. */
+  microphone?: MicrophoneFixture;
   /**
    * Script installed (before the session's first navigation) to run in every
    * document loaded from now on, BEFORE the document's own scripts — the
@@ -406,8 +419,8 @@ export interface MobileBackend extends Browser {
 // What the app gets is Chromium's own synthetic devices: the microphone is a
 // generated beep pattern (a live, real MediaStreamTrack — MediaRecorder,
 // WebRTC and AudioContext analysis all work on it), the camera a rolling
-// test pattern at 640x480. There is deliberately NO way to feed a recording
-// in; this is device availability, not audio fixtures.
+// test pattern at 640x480. A microphone fixture adds Chromium's file-capture
+// flag in a dedicated process; getUserMedia and track behavior stay native.
 //
 // --use-fake-device-for-media-stream: the synthetic camera + microphone.
 //   Also what makes `enumerateDevices()` return anything at all.
@@ -442,14 +455,16 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
 
-// One Chromium per daemon, launched lazily on first view creation and kept
-// for the daemon's lifetime. It rides snapshots: the process, playwright's
+// Default sessions share one Chromium per daemon, launched lazily and kept
+// for the daemon's lifetime. Fixture sessions own a process because the audio
+// source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
 // and resume in each fork (like dockerd and the daemon itself). Profile
 // state — cookies, localStorage — is per-Chromium, and the in-VM CA trust
 // comes from the HOME-scoped NSS user DB, so neither cares that playwright
 // runs a temp --user-data-dir.
 let PW_BROWSER: PlaywrightBrowser | null = null;
+const VIEW_CLEANUPS = new WeakMap<BrowserContext, () => Promise<void>>();
 // Every view gets its OWN context, desktop included. A context is the cookie
 // jar + storage, so one-context-per-view is what makes `close()` mean what
 // the docs promise: the browsing session is destroyed and the next
@@ -502,20 +517,48 @@ async function newViewContext(
   width: number,
   height: number,
   device: DevicePreset | null,
+  opts: Pick<BrowserOptions, "microphone" | "timezone" | "locale"> = {},
 ): Promise<BrowserContext> {
-  const browser = await ensurePlaywrightBrowser();
-  const context = await browser.newContext(
-    device
-      ? deviceContextOptions(device)
-      : {
-          viewport: { width, height },
-          // Reduced-motion for replay fidelity — see deviceContextOptions.
-          reducedMotion: "reduce",
-        },
-  );
-  context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-  context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-  return context;
+  const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
+  let browser: PlaywrightBrowser | undefined;
+  try {
+    browser = fixture ? await chromium.launch({
+      executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+    }) : await ensurePlaywrightBrowser();
+    const context = await browser.newContext({
+      ...(device
+        ? deviceContextOptions(device)
+        : {
+            viewport: { width, height },
+            // Reduced-motion for replay fidelity — see deviceContextOptions.
+            reducedMotion: "reduce",
+          }),
+      timezoneId: opts.timezone,
+      locale: opts.locale,
+    });
+    context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+    context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+    if (fixture) {
+      const owned = browser;
+      VIEW_CLEANUPS.set(context, async () => {
+        try { await owned.close(); } finally { await fixture.cleanup(); }
+      });
+    }
+    return context;
+  } catch (err) {
+    if (fixture) {
+      try { await browser?.close(); } finally { await fixture.cleanup(); }
+    }
+    throw err;
+  }
+}
+
+async function closeViewContext(context: BrowserContext): Promise<void> {
+  try { await context.close(); } finally {
+    const cleanup = VIEW_CLEANUPS.get(context);
+    VIEW_CLEANUPS.delete(context);
+    await cleanup?.();
+  }
 }
 
 /**
@@ -1276,7 +1319,7 @@ async function createView(width: number, height: number): Promise<PooledView> {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export async function prewarmViewPool(n = 1): Promise<void> {
   for (let i = 0; i < n; i++) {
@@ -1311,11 +1354,12 @@ export async function openMobileBackend(
   const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
   const wantW = device ? device.viewport.width : opts.width ?? 1280;
   const wantH = device ? device.viewport.height : opts.height ?? 720;
-  // Mobile views are never pooled — the pool holds only default-desktop
-  // views (in the shared desktop context), and a mobile view needs its own
-  // emulated context anyway.
+  // The pool holds only default-desktop contexts. Context creation options
+  // such as timezone and locale require a fresh context.
   const pooled =
-    !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    !device && opts.microphone === undefined && opts.timezone === undefined &&
+    opts.locale === undefined && wantW === 1280 && wantH === 720
+      ? VIEW_POOL.pop() : undefined;
   let holder: ViewHolder;
   if (pooled) {
     holder = {
@@ -1331,7 +1375,7 @@ export async function openMobileBackend(
       initScripts: [],
     };
   } else {
-    holder = await newHolder(wantW, wantH, device);
+    holder = await newHolder(wantW, wantH, device, opts);
   }
 
   const { backend } = buildBackend(holder, opts.recorder ?? null, {
@@ -1341,11 +1385,14 @@ export async function openMobileBackend(
   // We deliberately don't forward `opts.url` to the constructor — going
   // through our own `navigate()` keeps the recorder log uniform (one
   // event per navigation, with timing) and drains rrweb after the load.
-  if (opts.initScript !== undefined) await installInitScript(holder, opts.initScript);
-  if (opts.url !== undefined) {
-    await backend.goto(opts.url);
+  try {
+    if (opts.initScript !== undefined) await installInitScript(holder, opts.initScript);
+    if (opts.url !== undefined) await backend.goto(opts.url);
+    return backend;
+  } catch (err) {
+    await backend.close();
+    throw err;
   }
-  return backend;
 }
 
 // ────────────────────────────────────────────────────────────────────────
@@ -1400,9 +1447,14 @@ async function newHolder(
   width: number,
   height: number,
   device: DevicePreset | null,
+  opts: Pick<BrowserOptions, "microphone" | "timezone" | "locale"> = {},
 ): Promise<ViewHolder> {
-  const context = await newViewContext(width, height, device);
-  const spawned = await spawnPage(context);
+  const context = await newViewContext(width, height, device, opts);
+  let spawned: SpawnedPage;
+  try { spawned = await spawnPage(context); } catch (err) {
+    await closeViewContext(context);
+    throw err;
+  }
   const holder: ViewHolder = {
     context,
     page: spawned.page,
@@ -1497,6 +1549,7 @@ export async function acquirePersistentBrowser(
       device ? device.viewport.width : opts.width ?? 1280,
       device ? device.viewport.height : opts.height ?? 720,
       device,
+      opts,
     );
     SHARED_BROWSERS.set(name, holder);
   }
@@ -2163,7 +2216,7 @@ function buildBackend(
       // The context, not the page, holds the cookies and storage — closing
       // only the page would leave the next session signed in as this one.
       try {
-        if (buildOpts.ownsContext !== false) await holder.context.close();
+        if (buildOpts.ownsContext !== false) await closeViewContext(holder.context);
       } catch {
         /* context already gone (browser died) */
       }

package/src/daemon.ts

@@ -91,6 +91,7 @@ import {
   unionDockerignore,
 } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { dispatchFake } from "./harness/fake-websocket.js";
 import {
   casesMetadata as catalogueCases,
   groupsMetadata as catalogueGroups,
@@ -2458,17 +2459,7 @@ async function dispatchIngress(
   // The real answer — a fake handled in-process, or the proxied container.
   const upstream = async (current: Request): Promise<Response> => {
     if (route.kind === "fake") {
-      try {
-        return await runUninstrumented(() =>
-          route.fake.def.handler(current, route.fake.state, FAKE_CTX),
-        );
-      } catch (err) {
-        const e = err as Error;
-        return new Response(
-          `spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`,
-          { status: 500, headers: { "content-type": "text/plain" } },
-        );
-      }
+      return dispatchFake(current, server, route.fake.def, route.fake.state, FAKE_CTX);
     }
     return proxyToService(current, server, route.service, route.port, listenerLabel, proto);
   };

package/src/fake-websocket.ts

@@ -0,0 +1,17 @@
+/** A connection accepted by a fake. Text and binary messages retain their type. */
+export interface FakeWebSocket {
+  readonly readyState: number;
+  send(message: string | Uint8Array | ArrayBuffer): void;
+  close(code?: number, reason?: string): void;
+}
+
+/** Returned by a fake's websocket handshake callback to accept a connection.
+ * Callbacks run in order per connection, including async callbacks. Capture
+ * fake state and connection-local state in the handshake callback's closure. */
+export interface FakeWebSocketHandlers {
+  /** An offered Sec-WebSocket-Protocol to select, if the client requires one. */
+  protocol?: string;
+  open?(socket: FakeWebSocket): void | Promise<void>;
+  message?(socket: FakeWebSocket, message: string | Uint8Array): void | Promise<void>;
+  close?(socket: FakeWebSocket, code: number, reason: string): void | Promise<void>;
+}

package/src/harness/fake-websocket-connection.ts

@@ -0,0 +1,54 @@
+import type WebSocket from "ws";
+import type { FakeWebSocket, FakeWebSocketHandlers } from "../fake-websocket.js";
+
+const MAX_BUFFER = 16 * 1024 * 1024;
+const MAX_PENDING = 1024;
+
+/** Serialize async fake callbacks without allowing a slow handler or peer to
+ * retain unbounded audio. A handler failure closes just this connection. */
+export function attachFakeWebSocket(ws: WebSocket, handlers: FakeWebSocketHandlers): void {
+  let tail = Promise.resolve();
+  let pending = 0;
+  let bytes = 0;
+  let failed = false;
+  const socket: FakeWebSocket = {
+    get readyState() { return ws.readyState; },
+    send(message) {
+      if (ws.readyState !== 1) throw new Error("WebSocket is not open");
+      const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
+      if (ws.bufferedAmount + size > MAX_BUFFER) {
+        failed = true;
+        ws.close(1009, "fake output buffer exceeded");
+        throw new Error("fake WebSocket output buffer exceeded");
+      }
+      ws.send(message);
+    },
+    close: (code, reason) => ws.close(code, reason),
+  };
+  const fail = (err: unknown) => {
+    failed = true;
+    console.error("[spectest] fake WebSocket callback failed:", err);
+    try { ws.close(1011, "fake handler failed"); } catch { ws.terminate(); }
+  };
+  const enqueue = (fn: () => void | Promise<void>, size = 0, closing = false) => {
+    if (failed && !closing) return;
+    if (!closing && (pending >= MAX_PENDING || bytes + size > MAX_BUFFER)) {
+      failed = true;
+      ws.close(1009, "fake input buffer exceeded");
+      return;
+    }
+    pending++;
+    bytes += size;
+    tail = tail.then(async () => {
+      if (!failed || closing) await fn();
+    }).catch(fail).finally(() => { pending--; bytes -= size; });
+  };
+  ws.on("message", (data, binary) => {
+    const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data as ArrayBuffer);
+    const message = binary ? new Uint8Array(buffer) : buffer.toString();
+    enqueue(() => handlers.message?.(socket, message), buffer.length);
+  });
+  ws.on("close", (code, reason) => enqueue(() => handlers.close?.(socket, code, reason.toString()), 0, true));
+  ws.on("error", fail);
+  enqueue(() => handlers.open?.(socket));
+}

package/src/harness/fake-websocket.test.ts

@@ -0,0 +1,219 @@
+import { afterEach, expect, test, spyOn } from "bun:test";
+import { once } from "node:events";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { defineFake, type FakeContext, type FakeDefinition } from "../index.js";
+import { dispatchFake } from "./fake-websocket.js";
+import { startIngressServer, type IngressServer } from "./ingress-server.js";
+import { currentInstrumentationScope } from "./instrumentation-scope.js";
+import { startTlsTerminator } from "./tls-terminator.js";
+
+const require = createRequire(import.meta.url);
+const WS = require(join(dirname(require.resolve("ws/package.json")), "index.js")) as typeof import("ws");
+const servers: IngressServer[] = [];
+afterEach(() => { for (const s of servers.splice(0)) s.stop(true); });
+
+async function serve<S>(def: FakeDefinition<S, any>, state: S) {
+  const server = await startIngressServer({ port: 0, hostname: "127.0.0.1",
+    fetch: (req, server) => dispatchFake(req, server, def, state, {} as FakeContext),
+  });
+  servers.push(server);
+  return `127.0.0.1:${server.port}`;
+}
+
+function client(url: string, protocols?: string[], options?: import("ws").ClientOptions) {
+  const ws = new WS(url.startsWith("wss://") ? url : `ws://${url}`, protocols, options);
+  const messages: { data: Buffer; binary: boolean }[] = [];
+  const waiting: ((value: { data: Buffer; binary: boolean }) => void)[] = [];
+  ws.on("message", (data, binary) => {
+    const value = { data: Buffer.from(data as Buffer), binary };
+    const next = waiting.shift();
+    if (next) next(value); else messages.push(value);
+  });
+  const open = once(ws, "open");
+  const closed = once(ws, "close");
+  return { ws, open, closed, next: () => messages.length ? Promise.resolve(messages.shift()!) :
+    new Promise<{ data: Buffer; binary: boolean }>(resolve => waiting.push(resolve)) };
+}
+
+test("HTTP and WebSocket share state, helpers, ordered async callbacks and binary frames", async () => {
+  const state = { events: [] as string[], closed: "" };
+  const def = defineFake({
+    name: "speech", hostnames: ["speech.test"],
+    state: () => state,
+    handler: (_req, state) => Response.json(state.events),
+    helpers: ({ state }) => ({ events: () => [...state.events] }),
+    websocket: async (req, state) => {
+      expect(new URL(req.url).pathname).toBe("/realtime");
+      expect(currentInstrumentationScope()).toBeNull();
+      return {
+        protocol: "audio",
+        async open(ws) {
+          await Bun.sleep(10);
+          state.events.push("open");
+          ws.send("ready");
+        },
+        async message(ws, message) {
+          await Bun.sleep(5);
+          expect(currentInstrumentationScope()).toBeNull();
+          state.events.push(typeof message === "string" ? message : "binary");
+          ws.send(message);
+        },
+        close(_ws, code, reason) { state.closed = `${code}:${reason}`; },
+      };
+    },
+  });
+  const addr = await serve(def, state);
+  const c = client(`${addr}/realtime`, ["other", "audio"]);
+  await c.open;
+  expect(c.ws.protocol).toBe("audio");
+  c.ws.send("first");
+  c.ws.send(new Uint8Array([0, 128, 255]));
+  expect((await c.next()).data.toString()).toBe("ready");
+  expect((await c.next()).data.toString()).toBe("first");
+  expect(await c.next()).toEqual({ data: Buffer.from([0, 128, 255]), binary: true });
+  expect(await (await fetch(`http://${addr}/events`)).json()).toEqual(["open", "first", "binary"]);
+  const helpers = await def.helpers!({ name: "speech", state, ctx: {} as FakeContext });
+  expect(helpers.events()).toEqual(["open", "first", "binary"]);
+  c.ws.close(4001, "finished");
+  await c.closed;
+  for (let i = 0; !state.closed && i < 50; i++) await Bun.sleep(2);
+  expect(state.closed).toBe("4001:finished");
+});
+
+test("handshake can reject before upgrade with an HTTP status and body", async () => {
+  const addr = await serve(defineFake({ name: "auth", hostnames: ["auth.test"],
+    handler: () => new Response("http"),
+    websocket: req => req.headers.get("authorization") === "Bearer valid"
+      ? {} : new Response("token required", { status: 401 }),
+  }), undefined);
+  const ws = new WS(`ws://${addr}/realtime`);
+  const [req, response] = await once(ws, "unexpected-response");
+  const chunks: Buffer[] = [];
+  for await (const chunk of response) chunks.push(Buffer.from(chunk));
+  expect(response.statusCode).toBe(401);
+  expect(Buffer.concat(chunks).toString()).toBe("token required");
+  req.destroy();
+});
+
+test("an unoffered protocol fails the handshake", async () => {
+  const addr = await serve(defineFake({ name: "bad", hostnames: ["bad.test"],
+    handler: () => new Response("http"), websocket: () => ({ protocol: "unoffered" }),
+  }), undefined);
+  const ws = new WS(`ws://${addr}`, ["offered"]);
+  const [req, response] = await once(ws, "unexpected-response");
+  expect(response.statusCode).toBe(500);
+  response.resume();
+  req.destroy();
+});
+
+test("a throwing async callback closes its connection and later connections still work", async () => {
+  const errors = spyOn(console, "error").mockImplementation(() => {});
+  try {
+  const addr = await serve(defineFake({ name: "errors", hostnames: ["errors.test"],
+    handler: () => new Response("healthy"),
+    websocket: () => ({ async message(ws, message) {
+      if (message === "fail") throw new Error("intentional failure");
+      ws.send(message);
+    } }),
+  }), undefined);
+  const c = client(addr);
+  await c.open;
+  c.ws.send("fail");
+  const [code] = await c.closed;
+  expect(code).toBe(1011);
+  const next = client(addr);
+  await next.open;
+  next.ws.send("works");
+  expect((await next.next()).data.toString()).toBe("works");
+  next.ws.close();
+  await next.closed;
+  expect(errors).toHaveBeenCalled();
+  } finally { errors.mockRestore(); }
+});
+
+test("HTTP-only fakes retain their existing handling of upgrade requests", async () => {
+  const addr = await serve(defineFake({ name: "http", hostnames: ["http.test"],
+    handler: () => new Response("no realtime", { status: 404 }),
+  }), undefined);
+  const ws = new WS(`ws://${addr}`);
+  const [req, response] = await once(ws, "unexpected-response");
+  expect(response.statusCode).toBe(404);
+  response.resume();
+  req.destroy();
+});
+
+test("WSS uses the shared TLS terminator with real certificate verification", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-fake-wss-"));
+  let tls: Awaited<ReturnType<typeof startTlsTerminator>> | undefined;
+  try {
+    execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1",
+      "-subj", "/CN=speech.test", "-addext", "subjectAltName=DNS:speech.test",
+      "-keyout", join(dir, "key.pem"), "-out", join(dir, "cert.pem")], { stdio: "ignore" });
+    const leaf = { key: readFileSync(join(dir, "key.pem"), "utf8"), cert: readFileSync(join(dir, "cert.pem"), "utf8") };
+    const addr = await serve(defineFake({ name: "tls", hostnames: ["speech.test"],
+      handler: () => new Response("http"),
+      websocket: req => {
+        expect(req.headers.get("host")).toBe("speech.test");
+        expect(req.headers.get("cookie")).toBe("session=valid");
+        return { open(ws) { ws.send("secure"); }, message(ws, message) { ws.send(message); } };
+      },
+    }), undefined);
+    tls = await startTlsTerminator({ port: 0, hostname: "127.0.0.1", upstreamPort: Number(addr.split(":")[1]), certFor: () => leaf });
+    const c = client(`wss://127.0.0.1:${tls.port}`, undefined, {
+      servername: "speech.test", ca: leaf.cert, headers: { host: "speech.test", cookie: "session=valid" },
+    });
+    await c.open;
+    expect((await c.next()).data.toString()).toBe("secure");
+    c.ws.send(new Uint8Array([1, 2, 3]));
+    expect(await c.next()).toEqual({ data: Buffer.from([1, 2, 3]), binary: true });
+    c.ws.close(); await c.closed;
+  } finally { tls?.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("each handshake owns separate connection-local state", async () => {
+  const addr = await serve(defineFake({ name: "sessions", hostnames: ["speech.test"],
+    handler: () => new Response("http"), websocket: () => {
+      let sequence = 0;
+      return { message(ws) { ws.send(String(++sequence)); } };
+    },
+  }), undefined);
+  const a = client(addr), b = client(addr);
+  await Promise.all([a.open, b.open]);
+  a.ws.send("next"); a.ws.send("next"); b.ws.send("next");
+  expect((await a.next()).data.toString()).toBe("1");
+  expect((await a.next()).data.toString()).toBe("2");
+  expect((await b.next()).data.toString()).toBe("1");
+  a.ws.close(); b.ws.close(); await Promise.all([a.closed, b.closed]);
+});
+
+test("oversized fake output closes with 1009 instead of buffering it", async () => {
+  const errors = spyOn(console, "error").mockImplementation(() => {});
+  try {
+    const addr = await serve(defineFake({ name: "bounded", hostnames: ["bounded.test"],
+      handler: () => new Response("http"),
+      websocket: () => ({ message(ws) { ws.send(new Uint8Array(16 * 1024 * 1024 + 1)); } }),
+    }), undefined);
+    const c = client(addr);
+    await c.open;
+    c.ws.send("start");
+    expect((await c.closed)[0]).toBe(1009);
+  } finally { errors.mockRestore(); }
+});
+
+test("a slow callback cannot accumulate unlimited pending messages", async () => {
+  let release!: () => void;
+  const blocked = new Promise<void>(resolve => { release = resolve; });
+  try {
+    const addr = await serve(defineFake({ name: "slow", hostnames: ["slow.test"],
+      handler: () => new Response("http"), websocket: () => ({ open: () => blocked }),
+    }), undefined);
+    const c = client(addr);
+    await c.open;
+    for (let i = 0; i < 1100; i++) c.ws.send("queued");
+    expect((await c.closed)[0]).toBe(1009);
+  } finally { release(); }
+});

package/src/harness/fake-websocket.ts

@@ -0,0 +1,39 @@
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+import type { FakeContext, FakeDefinition } from "../index.js";
+import type { IngressServer } from "./ingress-server.js";
+import { runUninstrumented } from "./instrumentation-scope.js";
+import { parseSubprotocols } from "./ws-bridge.js";
+
+/** HTTP and WebSocket dispatch share fake state, helpers, and execution scope. */
+export async function dispatchFake<S>(
+  req: Request,
+  server: IngressServer,
+  def: FakeDefinition<S, any>,
+  state: S,
+  ctx: FakeContext,
+): Promise<Response> {
+  try {
+    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !def.websocket) {
+      return await runUninstrumented(() => def.handler(req, state, ctx));
+    }
+    const accepted = await runUninstrumented(() => def.websocket!(req, state, ctx));
+    if (accepted instanceof Response) return accepted;
+    if (!accepted || typeof accepted !== "object") throw new Error("websocket must return handlers or a Response");
+    if (accepted.protocol !== undefined && !parseSubprotocols(req.headers.get("sec-websocket-protocol")).includes(accepted.protocol)) {
+      throw new Error("websocket selected a protocol the client did not offer");
+    }
+    const handlers: FakeWebSocketHandlers = {
+      open: socket => runUninstrumented(() => accepted.open?.(socket)),
+      message: (socket, message) => runUninstrumented(() => accepted.message?.(socket, message)),
+      close: (socket, code, reason) => runUninstrumented(() => accepted.close?.(socket, code, reason)),
+    };
+    return server.upgrade(req, {
+      handlers,
+      headers: accepted.protocol ? { "sec-websocket-protocol": accepted.protocol } : undefined,
+    }) ? new Response(null, { status: 101 }) : new Response("WebSocket upgrade refused", { status: 426 });
+  } catch (err) {
+    return new Response(`spectest-daemon: fake ${def.name} threw: ${err instanceof Error ? err.message : String(err)}\n`, {
+      status: 500, headers: { "content-type": "text/plain" },
+    });
+  }
+}