@specific.dev/spectest 0.102.0 → 0.104.0

package/README.md

@@ -20,6 +20,52 @@ Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+
+## Microphone fixtures and WebSocket fakes (0.103.0)
+
+Supply a 16-bit PCM mono/stereo WAV when creating a browser session:
+
+```ts
+const browser = await ctx.browser({
+  microphone: { path: "spectest/tests/fixtures/speech.wav" },
+});
+```
+
+The microphone uses Chromium's native capture pipeline. It plays once and then
+supplies silence; add `loop: true` to repeat. Paths are relative to the repository
+root. Set the fixture on the first call for that browser session; reattaching
+preserves its source. Fixture sessions use a dedicated Chromium process to keep
+named browsers' audio isolated.
+
+A fake can serve HTTP and WebSockets on the same hostname, sharing state and
+helpers:
+
+```ts
+const speech = defineFake({
+  name: "speech",
+  hostnames: ["speech.example.com"],
+  state: () => ({ messages: [] as string[] }),
+  handler: () => Response.json({ ready: true }),
+  websocket(req, state) {
+    if (new URL(req.url).pathname !== "/realtime") {
+      return new Response("Not found", { status: 404 });
+    }
+    return {
+      message(socket, message) {
+        if (typeof message === "string") state.messages.push(message);
+        socket.send(message);
+      },
+    };
+  },
+  helpers: ({ state }) => ({ messages: () => [...state.messages] }),
+});
+```
+
+The handshake returns a rejection `Response` or callbacks (`open`, `message`,
+`close`), with an optional selected `protocol`. Callbacks may be async and run
+in order per connection. WS and trusted WSS support text/binary messages;
+observe traffic through the fake's helpers.
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and

package/dist/browser.d.ts

@@ -1,3 +1,5 @@
+import { type MicrophoneFixture } from "./harness/microphone-fixture.js";
+export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
 import type { DesktopChrome } from "./desktop.js";
 import type { Wrapped } from "./inspect.js";
 import type { UrlPattern } from "./url-match.js";
@@ -20,6 +22,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
@@ -290,7 +303,7 @@ export interface SafeAreaInsets {
  * 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 declare function prewarmViewPool(n?: number): Promise<void>;
 /**

package/dist/browser.js

@@ -33,6 +33,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { rawFetch } from "./harness/raw-fetch.js";
+import { prepareMicrophoneFixture } from "./harness/microphone-fixture.js";
 import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
@@ -74,8 +75,8 @@ function base64ByteLength(b64) {
 // 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.
@@ -106,14 +107,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 = null;
+const VIEW_CLEANUPS = new WeakMap();
 // 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
@@ -157,18 +160,60 @@ function deviceContextOptions(d) {
 }
 /** Create the context one view lives in — device emulation when the view is
  *  phone-emulated, a plain viewport otherwise. */
-async function newViewContext(width, height, device) {
-    const browser = await ensurePlaywrightBrowser();
-    const context = await browser.newContext(device
-        ? deviceContextOptions(device)
-        : {
-            viewport: { width, height },
-            // Reduced-motion for replay fidelity — see deviceContextOptions.
-            reducedMotion: "reduce",
+async function newViewContext(width, height, device, opts = {}) {
+    const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
+    let browser;
+    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);
-    return context;
+        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) {
+    try {
+        await context.close();
+    }
+    finally {
+        const cleanup = VIEW_CLEANUPS.get(context);
+        VIEW_CLEANUPS.delete(context);
+        await cleanup?.();
+    }
 }
 /**
  * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
@@ -838,7 +883,7 @@ async function createView(width, height) {
  * 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) {
     for (let i = 0; i < n; i++) {
@@ -869,10 +914,11 @@ export async function openMobileBackend(opts = {}) {
     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.
-    const pooled = !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    // The pool holds only default-desktop contexts. Context creation options
+    // such as timezone and locale require a fresh context.
+    const pooled = !device && opts.microphone === undefined && opts.timezone === undefined &&
+        opts.locale === undefined && wantW === 1280 && wantH === 720
+        ? VIEW_POOL.pop() : undefined;
     let holder;
     if (pooled) {
         holder = {
@@ -889,7 +935,7 @@ export async function openMobileBackend(opts = {}) {
         };
     }
     else {
-        holder = await newHolder(wantW, wantH, device);
+        holder = await newHolder(wantW, wantH, device, opts);
     }
     const { backend } = buildBackend(holder, opts.recorder ?? null, {
         persistent: false,
@@ -897,12 +943,17 @@ export async function openMobileBackend(opts = {}) {
     // 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;
 }
 // ────────────────────────────────────────────────────────────────────────
 // Persistent sessions (the default behind ctx.browser / ctx.mobile)
@@ -946,9 +997,16 @@ function checkSessionCap(kind, live, name) {
         `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
         `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`);
 }
-async function newHolder(width, height, device) {
-    const context = await newViewContext(width, height, device);
-    const spawned = await spawnPage(context);
+async function newHolder(width, height, device, opts = {}) {
+    const context = await newViewContext(width, height, device, opts);
+    let spawned;
+    try {
+        spawned = await spawnPage(context);
+    }
+    catch (err) {
+        await closeViewContext(context);
+        throw err;
+    }
     const holder = {
         context,
         page: spawned.page,
@@ -1020,7 +1078,7 @@ export async function acquirePersistentBrowser(name = "", opts = {}) {
     }
     else {
         checkSessionCap("browser", SHARED_BROWSERS.size, name);
-        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device);
+        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device, opts);
         SHARED_BROWSERS.set(name, holder);
     }
     const view = holder;
@@ -1617,7 +1675,7 @@ function buildBackend(holder, recorder, buildOpts) {
             // only the page would leave the next session signed in as this one.
             try {
                 if (buildOpts.ownsContext !== false)
-                    await holder.context.close();
+                    await closeViewContext(holder.context);
             }
             catch {
                 /* context already gone (browser died) */

package/dist/daemon.js

@@ -41,6 +41,7 @@ import { isDesktopApp } from "./desktop.js";
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, 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, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
@@ -2000,13 +2001,7 @@ server, byHost, listenerLabel, proto) {
     // The real answer — a fake handled in-process, or the proxied container.
     const upstream = async (current) => {
         if (route.kind === "fake") {
-            try {
-                return await runUninstrumented(() => route.fake.def.handler(current, route.fake.state, FAKE_CTX));
-            }
-            catch (err) {
-                const e = err;
-                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/dist/fake-websocket.d.ts

@@ -0,0 +1,16 @@
+/** 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/dist/fake-websocket.js

@@ -0,0 +1 @@
+export {};

package/dist/harness/fake-websocket-connection.d.ts

@@ -0,0 +1,5 @@
+import type WebSocket from "ws";
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+/** Serialize async fake callbacks without allowing a slow handler or peer to
+ * retain unbounded audio. A handler failure closes just this connection. */
+export declare function attachFakeWebSocket(ws: WebSocket, handlers: FakeWebSocketHandlers): void;

package/dist/harness/fake-websocket-connection.js

@@ -0,0 +1,58 @@
+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, handlers) {
+    let tail = Promise.resolve();
+    let pending = 0;
+    let bytes = 0;
+    let failed = false;
+    const socket = {
+        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) => {
+        failed = true;
+        console.error("[spectest] fake WebSocket callback failed:", err);
+        try {
+            ws.close(1011, "fake handler failed");
+        }
+        catch {
+            ws.terminate();
+        }
+    };
+    const enqueue = (fn, 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);
+        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/dist/harness/fake-websocket.d.ts

@@ -0,0 +1,4 @@
+import type { FakeContext, FakeDefinition } from "../index.js";
+import type { IngressServer } from "./ingress-server.js";
+/** HTTP and WebSocket dispatch share fake state, helpers, and execution scope. */
+export declare function dispatchFake<S>(req: Request, server: IngressServer, def: FakeDefinition<S, any>, state: S, ctx: FakeContext): Promise<Response>;

package/dist/harness/fake-websocket.js

@@ -0,0 +1,32 @@
+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(req, server, def, state, ctx) {
+    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 = {
+            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/dist/harness/ingress-server.d.ts

@@ -1,4 +1,5 @@
 import { type WsBridgeData } from "./ws-bridge.js";
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
 export interface IngressServer {
     port: number;
     stop(force?: boolean): void;
@@ -6,8 +7,11 @@ export interface IngressServer {
         address: string;
         port: number;
     } | undefined;
-    upgrade(req: Request, options: {
+    upgrade(req: Request, options: ({
         data: WsBridgeData;
+    } | {
+        handlers: FakeWebSocketHandlers;
+    }) & {
         headers?: Record<string, string>;
     }): boolean;
 }

package/dist/harness/ingress-server.js

@@ -4,6 +4,7 @@ import { pipeline } from "node:stream/promises";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { WS_BRIDGE_HANDLERS } from "./ws-bridge.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
 // asynchronous upstream handshake. The package uses the ordinary socket API.
@@ -27,6 +28,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);
     });
@@ -43,11 +48,14 @@ export async function startIngressServer(options) {
             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) {
@@ -60,8 +68,13 @@ export async function startIngressServer(options) {
             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) => ws.send(data),

package/dist/harness/microphone-fixture.d.ts

@@ -0,0 +1,13 @@
+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 declare function prepareMicrophoneFixture(fixture: MicrophoneFixture): Promise<{
+    arg: string;
+    cleanup(): Promise<void>;
+}>;

package/dist/harness/microphone-fixture.js

@@ -0,0 +1,67 @@
+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";
+/** 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) {
+    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;
+    }
+}

package/dist/index.d.ts

@@ -11,6 +11,9 @@ export { SQL, type SqlClient, type SqlOptions } from "./sql.js";
 export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js";
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
+export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
+export type { FakeWebSocket, FakeWebSocketHandlers } from "./fake-websocket.js";
+import type { FakeWebSocketHandlers } from "./fake-websocket.js";
 import type { Browser, BrowserOptions } from "./browser.js";
 export { McpHttpError, McpRpcError, McpAuthDeniedError, type Mcp, type McpOptions, type McpAuthorization, type McpChallenge, type McpIdentity, type McpToolResult, type McpToolInfo, type McpResourceInfo, type McpResourceContents, type McpPromptInfo, type McpPromptResult, type McpContent, type McpNotification, type McpSamplingRequest, type McpSamplingResult, type AuthorizeOptions, type AuthorizationServerInfo, } from "./mcp.js";
 import type { Mcp, McpOptions } from "./mcp.js";
@@ -1483,6 +1486,10 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * also applies to state/helper factories and helper implementations.
      */
     handler: (req: Request, state: S, ctx: FakeContext) => Response | Promise<Response>;
+    /** Optional WebSocket handshake on the same hostnames as HTTP. Return a
+     * Response to reject, or connection callbacks to accept. Callbacks share
+     * this fake's state and run uninstrumented, in order per connection. */
+    websocket?: (req: Request, state: S, ctx: FakeContext) => FakeWebSocketHandlers | Response | Promise<FakeWebSocketHandlers | Response>;
     /**
      * Build the helpers exposed at `ctx.fakes.<name>` — a record of
      * **functions** that read or mutate the fake's `state` (received here)

package/dist/index.js

@@ -414,6 +414,9 @@ export function defineFake(opts) {
     if (typeof opts.handler !== "function") {
         throw new Error(`defineFake(${opts.name}): \`handler\` is required`);
     }
+    if (opts.websocket !== undefined && typeof opts.websocket !== "function") {
+        throw new Error(`defineFake(${opts.name}): \`websocket\` must be a function`);
+    }
     return opts;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",