@specific.dev/spectest 0.102.0 → 0.104.0

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;
+  }
+}

package/src/index.ts

@@ -78,6 +78,9 @@ 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";
 
@@ -2171,6 +2174,11 @@ export interface FakeDefinition<
    * 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)
@@ -2239,6 +2247,9 @@ export function defineFake<
   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/src/microphone-fixture.test.ts

@@ -0,0 +1,143 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { prepareMicrophoneFixture } from "./harness/microphone-fixture.js";
+import { acquirePersistentBrowser, openMobileBackend, type MobileBackend } from "./browser.js";
+
+let dir: string;
+function wav(frequency: number, seconds = 1): Buffer {
+  const rate = 48000;
+  const size = Math.floor(rate * seconds) * 2;
+  const out = Buffer.alloc(44 + size);
+  out.write("RIFF"); out.writeUInt32LE(36 + size, 4); out.write("WAVEfmt ", 8);
+  out.writeUInt32LE(16, 16); out.writeUInt16LE(1, 20); out.writeUInt16LE(1, 22);
+  out.writeUInt32LE(rate, 24); out.writeUInt32LE(rate * 2, 28);
+  out.writeUInt16LE(2, 32); out.writeUInt16LE(16, 34);
+  out.write("data", 36); out.writeUInt32LE(size, 40);
+  for (let i = 0; i < size / 2; i++) out.writeInt16LE(Math.round(16000 * Math.sin(2 * Math.PI * frequency * i / rate)), 44 + i * 2);
+  return out;
+}
+beforeAll(async () => {
+  dir = await mkdtemp(join(tmpdir(), "spectest-audio-test-"));
+  await writeFile(join(dir, "440%name.wav"), wav(440));
+  await writeFile(join(dir, "880.wav"), wav(880));
+  await writeFile(join(dir, "invalid.wav"), "not audio");
+});
+afterAll(async () => { await rm(dir, { recursive: true, force: true }); });
+
+test("stages WAV bytes under an immutable safe path and distinguishes looping", async () => {
+  for (const loop of [false, true]) {
+    const fixture = await prepareMicrophoneFixture({ path: join(dir, "440%name.wav"), loop });
+    const path = fixture.arg.split("=")[1]!.replace(/%noloop$/, "");
+    expect(path).not.toContain("%");
+    const staged = await readFile(path);
+    if (loop) expect(staged).toEqual(wav(440));
+    else {
+      expect(staged.subarray(44, wav(440).length)).toEqual(wav(440).subarray(44));
+      expect(staged.subarray(wav(440).length).every(byte => byte === 0)).toBe(true);
+    }
+    expect(fixture.arg.endsWith("%noloop")).toBe(!loop);
+    await fixture.cleanup();
+    expect(await Bun.file(path).exists()).toBe(false);
+  }
+});
+
+test("missing and invalid audio fail before Chromium launches", async () => {
+  await expect(prepareMicrophoneFixture({ path: join(dir, "missing.wav") })).rejects.toThrow("microphone fixture");
+  await expect(prepareMicrophoneFixture({ path: join(dir, "invalid.wav") })).rejects.toThrow("16-bit PCM");
+  await expect(prepareMicrophoneFixture({ path: "" })).rejects.toThrow("microphone.path");
+});
+
+async function capture(browser: MobileBackend): Promise<void> {
+  await browser.silentRead(page => page.evaluate(async () => {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: {
+      echoCancellation: false, noiseSuppression: false, autoGainControl: false,
+    } });
+    const context = new AudioContext();
+    const analyser = context.createAnalyser();
+    analyser.fftSize = 4096;
+    context.createMediaStreamSource(stream).connect(analyser);
+    await context.resume();
+    (globalThis as any).__mic = { stream, context, analyser };
+  }));
+}
+
+async function peak(browser: MobileBackend): Promise<number> {
+  return browser.silentRead(page => page.evaluate(async () => {
+    const { context, analyser } = (globalThis as any).__mic;
+    const bins = new Float32Array(analyser.frequencyBinCount);
+    for (let i = 0; i < 100; i++) {
+      analyser.getFloatFrequencyData(bins);
+      const max = Math.max(...bins);
+      if (max > -40) return bins.indexOf(max) * context.sampleRate / analyser.fftSize;
+      await new Promise(resolve => setTimeout(resolve, 20));
+    }
+    throw new Error("microphone produced no audible fixture");
+  }));
+}
+
+describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("native Chromium microphone", () => {
+  let server: ReturnType<typeof Bun.serve>;
+  beforeAll(() => { server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response("<html>microphone</html>", { headers: { "content-type": "text/html" } }) }); });
+  afterAll(() => server.stop(true));
+
+  test("captures the fixture through native tracks and MediaRecorder", async () => {
+    const browser = await openMobileBackend({ url: server.url.href, microphone: { path: join(dir, "440%name.wav"), loop: true } });
+    try {
+      await capture(browser);
+      expect(await peak(browser)).toBeCloseTo(440, -1);
+      const result = await browser.silentRead(page => page.evaluate(async () => {
+        const { stream } = (globalThis as any).__mic;
+        const recorder = new MediaRecorder(stream);
+        const chunks: Blob[] = [];
+        recorder.ondataavailable = e => chunks.push(e.data);
+        const stopped = new Promise<void>(resolve => { recorder.onstop = () => resolve(); });
+        recorder.start();
+        await new Promise(resolve => setTimeout(resolve, 150));
+        recorder.stop(); await stopped;
+        const track = stream.getAudioTracks()[0];
+        const before = track.readyState;
+        track.stop();
+        return { before, after: track.readyState, size: new Blob(chunks).size };
+      }));
+      expect(result.before).toBe("live");
+      expect(result.after).toBe("ended");
+      expect(result.size).toBeGreaterThan(0);
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test("named sessions have isolated fixtures and reattachment preserves the original source", async () => {
+    const a = await acquirePersistentBrowser("audio-a", { url: server.url.href, microphone: { path: join(dir, "440%name.wav"), loop: true } });
+    const b = await acquirePersistentBrowser("audio-b", { url: server.url.href, microphone: { path: join(dir, "880.wav"), loop: true } });
+    try {
+      await Promise.all([capture(a.browser), capture(b.browser)]);
+      expect(await peak(a.browser)).toBeCloseTo(440, -1);
+      expect(await peak(b.browser)).toBeCloseTo(880, -1);
+      await a.detach();
+      const attached = await acquirePersistentBrowser("audio-a");
+      expect(attached.attached).toBe(true);
+      expect(await peak(attached.browser)).toBeCloseTo(440, -1);
+      await attached.detach();
+    } finally { await Promise.all([a.browser.close(), b.browser.close()]); }
+  }, 20000);
+
+  test("single playback becomes silence without ending the media track", async () => {
+    const browser = await openMobileBackend({ url: server.url.href, microphone: { path: join(dir, "440%name.wav") } });
+    try {
+      await capture(browser);
+      expect(await peak(browser)).toBeCloseTo(440, -1);
+      const result = await browser.silentRead(page => page.evaluate(async () => {
+        const { stream, analyser } = (globalThis as any).__mic;
+        const samples = new Float32Array(analyser.fftSize);
+        for (let i = 0; i < 100; i++) {
+          await new Promise(resolve => setTimeout(resolve, 30));
+          analyser.getFloatTimeDomainData(samples);
+          if (Math.max(...samples.map(Math.abs)) < 0.001) return stream.getAudioTracks()[0].readyState;
+        }
+        throw new Error("single playback did not become silent");
+      }));
+      expect(result).toBe("live");
+    } finally { await browser.close(); }
+  }, 20000);
+});