@specific.dev/spectest 0.102.0 → 0.103.0

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,10 @@ export interface BrowserOptions {
   frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: 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 +412,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 +448,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 +510,46 @@ async function newViewContext(
   width: number,
   height: number,
   device: DevicePreset | null,
+  microphone?: MicrophoneFixture,
 ): 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 = microphone === undefined ? undefined : await prepareMicrophoneFixture(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",
+          },
+    );
+    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?.();
+  }
 }
 
 /**
@@ -1315,7 +1349,7 @@ export async function openMobileBackend(
   // views (in the shared desktop context), and a mobile view needs its own
   // emulated context anyway.
   const pooled =
-    !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    !device && opts.microphone === undefined && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
   let holder: ViewHolder;
   if (pooled) {
     holder = {
@@ -1331,7 +1365,7 @@ export async function openMobileBackend(
       initScripts: [],
     };
   } else {
-    holder = await newHolder(wantW, wantH, device);
+    holder = await newHolder(wantW, wantH, device, opts.microphone);
   }
 
   const { backend } = buildBackend(holder, opts.recorder ?? null, {
@@ -1341,11 +1375,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 +1437,14 @@ async function newHolder(
   width: number,
   height: number,
   device: DevicePreset | null,
+  microphone?: MicrophoneFixture,
 ): Promise<ViewHolder> {
-  const context = await newViewContext(width, height, device);
-  const spawned = await spawnPage(context);
+  const context = await newViewContext(width, height, device, microphone);
+  let spawned: SpawnedPage;
+  try { spawned = await spawnPage(context); } catch (err) {
+    await closeViewContext(context);
+    throw err;
+  }
   const holder: ViewHolder = {
     context,
     page: spawned.page,
@@ -1497,6 +1539,7 @@ export async function acquirePersistentBrowser(
       device ? device.viewport.width : opts.width ?? 1280,
       device ? device.viewport.height : opts.height ?? 720,
       device,
+      opts.microphone,
     );
     SHARED_BROWSERS.set(name, holder);
   }
@@ -2163,7 +2206,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" },
+    });
+  }
+}

package/src/harness/ingress-server.ts

@@ -5,6 +5,8 @@ import type { Socket } from "node:net";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { WS_BRIDGE_HANDLERS, type WsBridgeData } from "./ws-bridge.js";
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+import { attachFakeWebSocket } from "./fake-websocket-connection.js";
 
 // Load the installed implementation, not Bun's built-in `ws` replacement.
 // On Bun 1.4.0 that replacement cannot upgrade node:http sockets after the
@@ -16,7 +18,7 @@ export interface IngressServer {
   port: number;
   stop(force?: boolean): void;
   requestIP(req: Request): { address: string; port: number } | undefined;
-  upgrade(req: Request, options: { data: WsBridgeData; headers?: Record<string, string> }): boolean;
+  upgrade(req: Request, options: ({ data: WsBridgeData } | { handlers: FakeWebSocketHandlers }) & { headers?: Record<string, string> }): boolean;
 }
 
 /**
@@ -42,6 +44,10 @@ export async function startIngressServer(options: {
     // the client's first offer on its behalf.
     handleProtocols: (_offered, req) => protocols.get(req) || false,
   });
+  const fakeWebsockets = new WebSocketServer({
+    noServer: true, maxPayload: 16 * 1024 * 1024,
+    handleProtocols: (_offered, req) => protocols.get(req) || false,
+  });
   const server = http.createServer({ requestTimeout: 0 }, (req, res) => {
     void dispatch(req, res);
   });
@@ -58,10 +64,12 @@ export async function startIngressServer(options: {
     stop(force = false) {
       if (force) {
         for (const ws of websockets.clients) ws.terminate();
+        for (const ws of fakeWebsockets.clients) ws.terminate();
         for (const socket of sockets) socket.destroy();
         server.closeAllConnections();
       }
       websockets.close();
+      fakeWebsockets.close();
       server.close();
     },
     requestIP(req) {
@@ -73,8 +81,13 @@ export async function startIngressServer(options: {
       const pending = upgrades.get(req);
       if (!pending || pending.upgraded || pending.socket.destroyed) return false;
       protocols.set(pending.req, opts.headers?.["sec-websocket-protocol"]);
-      websockets.handleUpgrade(pending.req, pending.socket, pending.head, ws => {
+      const target = "handlers" in opts ? fakeWebsockets : websockets;
+      target.handleUpgrade(pending.req, pending.socket, pending.head, ws => {
         pending.upgraded = true;
+        if ("handlers" in opts) {
+          attachFakeWebSocket(ws, opts.handlers);
+          return;
+        }
         const client = {
           data: opts.data,
           send: (data: string | ArrayBuffer | Uint8Array) => ws.send(data),

package/src/harness/microphone-fixture.ts

@@ -0,0 +1,71 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveExistingProjectPath } from "../project-files.js";
+
+export interface MicrophoneFixture {
+  /** WAV file relative to the repository root (absolute paths also work).
+   * Use 16-bit PCM mono or stereo audio. */
+  path: string;
+  /** Repeat the recording. Default false: play once, then supply silence. */
+  loop?: boolean;
+}
+
+/** Stage immutable bytes under a safe filename: Chromium interprets a `%`
+ * suffix as playback options, so a project filename cannot be passed verbatim. */
+export async function prepareMicrophoneFixture(fixture: MicrophoneFixture): Promise<{
+  arg: string;
+  cleanup(): Promise<void>;
+}> {
+  if (!fixture || typeof fixture.path !== "string" || !fixture.path.trim()) {
+    throw new Error("microphone.path must name a WAV fixture");
+  }
+  if (fixture.loop !== undefined && typeof fixture.loop !== "boolean") throw new Error("microphone.loop must be a boolean");
+  const source = resolveExistingProjectPath(fixture.path, "microphone fixture");
+  const bytes = await readFile(source);
+  let pcm = false;
+  let audio = false;
+  let dataAt = 0;
+  let dataSize = 0;
+  let bytesPerFrame = 0;
+  let sampleRate = 0;
+  if (bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WAVE") {
+    for (let at = 12; at + 8 <= bytes.length;) {
+      const size = bytes.readUInt32LE(at + 4);
+      const end = at + 8 + size;
+      if (end > bytes.length) break;
+      const chunk = bytes.toString("ascii", at, at + 4);
+      if (chunk === "fmt " && size >= 16) {
+        sampleRate = bytes.readUInt32LE(at + 12);
+        bytesPerFrame = bytes.readUInt16LE(at + 10) * 2;
+        pcm = bytes.readUInt16LE(at + 8) === 1 && [1, 2].includes(bytes.readUInt16LE(at + 10)) &&
+          sampleRate >= 8000 && sampleRate <= 192000 && bytes.readUInt16LE(at + 22) === 16 &&
+          bytes.readUInt16LE(at + 20) === bytesPerFrame;
+      }
+      if (chunk === "data" && size > 0) { audio = true; dataAt = at; dataSize = size; }
+      at = end + (size % 2);
+    }
+  }
+  if (!pcm || !audio || dataSize % bytesPerFrame !== 0) throw new Error(`microphone fixture "${fixture.path}" must be a non-empty 16-bit PCM mono or stereo WAV (8–192 kHz)`);
+  // Chromium's FileSource returns zero at EOF without clearing the previous
+  // capture buffer. Finish with silence so single playback cannot repeat the
+  // final speech fragment indefinitely. Leave looping recordings untouched.
+  let staged = bytes;
+  if (!fixture.loop) {
+    const silence = Buffer.alloc(Math.ceil(sampleRate / 4) * bytesPerFrame);
+    const end = dataAt + 8 + dataSize;
+    staged = Buffer.concat([bytes.subarray(0, end), silence, bytes.subarray(end)]);
+    staged.writeUInt32LE(staged.length - 8, 4);
+    staged.writeUInt32LE(dataSize + silence.length, dataAt + 4);
+  }
+  const dir = await mkdtemp(join(tmpdir(), "spectest-microphone-"));
+  const cleanup = () => rm(dir, { recursive: true, force: true });
+  try {
+    const file = join(dir, "audio.wav");
+    await writeFile(file, staged);
+    return { arg: `--use-file-for-fake-audio-capture=${file}${fixture.loop ? "" : "%noloop"}`, cleanup };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}