@specific.dev/spectest 0.99.0 → 0.101.0

package/src/components/replay-key.ts

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import type { CassetteRequest } from "./replayFake.js";
+
+export type JsonValue =
+  | null | boolean | number | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/** Identity content. Objects compare independently of property order; arrays
+ *  preserve order. Bytes are distinct from strings, arrays, and objects. */
+export type MatchKey =
+  | null | boolean | number | string | Uint8Array
+  | readonly MatchKey[]
+  | { readonly [key: string]: MatchKey };
+
+/** A buffered request view shared by incoming and recorded requests.
+ *  Headers are lowercase and exclude credentials. Recorded values may be
+ *  redacted; choose identity fields that survive recording. */
+export interface ReplayRequest {
+  readonly method: string;
+  readonly path: string;
+  readonly query: Readonly<Record<string, readonly string[]>>;
+  readonly headers: Readonly<Record<string, string>>;
+  /** Decode UTF-8, throwing on invalid text. */
+  text(): string;
+  /** Parse JSON. The type parameter is not runtime validation. */
+  json<T = JsonValue>(): T;
+  /** Return an independent copy of the body bytes. */
+  bytes(): Uint8Array;
+}
+
+export type ReplayKey = (request: ReplayRequest) => MatchKey;
+
+/** Stream a typed, length-delimited canonical representation into the hash.
+ *  Never call toJSON: unsupported values must fail rather than silently lose
+ *  identity fields. In particular, an async callback must not become `{}`. */
+function hashKey(key: MatchKey): string {
+  const hash = createHash("sha256");
+  const ancestors = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+      hash.update(JSON.stringify(value));
+      return;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      hash.update(JSON.stringify(value));
+      return;
+    }
+    if (value instanceof Uint8Array) {
+      hash.update(`bytes:${value.byteLength}:`);
+      hash.update(value);
+      return;
+    }
+    if (value instanceof Promise) {
+      // Report the invalid callback synchronously without leaving a rejected
+      // async callback to become an unrelated unhandled-rejection failure.
+      void value.catch(() => {});
+      throw new Error("key callbacks must be synchronous, not return promises");
+    }
+    if (typeof value !== "object" || value === null) {
+      throw new Error("key must contain only JSON values or Uint8Array bytes (no undefined, functions, or non-finite numbers)");
+    }
+    if (ancestors.has(value)) throw new Error("key must not contain cycles");
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new Error("key must not contain symbol properties");
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+      if (Object.keys(value).length !== value.length) {
+        throw new Error("key arrays must be dense and have no extra properties");
+      }
+      hash.update("[");
+      for (let i = 0; i < value.length; i++) {
+        if (!Object.hasOwn(value, i)) throw new Error("key arrays must be dense");
+        visit(value[i]);
+        hash.update(",");
+      }
+      hash.update("]");
+    } else {
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new Error("key must use plain objects, not promises, dates, maps, or class instances; callbacks must be synchronous");
+      }
+      hash.update("{");
+      for (const name of Object.keys(value).sort()) {
+        hash.update(JSON.stringify(name));
+        hash.update(":");
+        visit((value as Record<string, unknown>)[name]);
+        hash.update(",");
+      }
+      hash.update("}");
+    }
+    ancestors.delete(value);
+  };
+  visit(key);
+  return hash.digest("hex");
+}
+
+function bodyBytes(request: CassetteRequest): Uint8Array {
+  return Buffer.from(request.body ?? "", request.bodyEncoding === "base64" ? "base64" : "utf8");
+}
+
+function requestView(request: CassetteRequest): ReplayRequest {
+  let bytes: Uint8Array | undefined;
+  let text: string | undefined;
+  const readBytes = () => bytes ??= bodyBytes(request);
+  const readText = () => text ??= new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readBytes());
+  const query = Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, Object.freeze([...v])]));
+  return Object.freeze({
+    method: request.method.toUpperCase(),
+    path: request.path,
+    query: Object.freeze(query),
+    headers: Object.freeze({ ...request.headers }),
+    text: readText,
+    json: <T = JsonValue>(): T => JSON.parse(readText()) as T,
+    bytes: () => Uint8Array.from(readBytes()),
+  });
+}
+
+/** Internal only; the SDK exports the request/key types, not this function. */
+export function replaySignature(request: CassetteRequest, key?: ReplayKey): string {
+  if (key) return hashKey(key(requestView(request)));
+  // Existing cassettes retain the original byte hash even when their stored
+  // text was redacted. Older/hand-written cassettes may only have the body.
+  const body = request.bodyHash ?? `sha256:${createHash("sha256").update(bodyBytes(request)).digest("hex")}`;
+  return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query, body });
+}

package/src/components/replayFake-handler.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineEnvironment, type FakeContext } from "../index.js";
+import { replayFake, type Cassette, type ReplayFakeContext, type ReplayHandler } from "./index.js";
+
+const host = "api.example.test";
+const context = {} as FakeContext;
+const fixture: Cassette = {
+  version: 1, fake: "mixed", host,
+  interactions: ["one", "two"].map((task) => ({
+    request: {
+      method: "POST", path: "/messages", query: {}, headers: {},
+      body: JSON.stringify({ task }), bodyEncoding: "utf8",
+    },
+    response: { status: 200, headers: {}, body: `recorded-${task}`, bodyEncoding: "utf8" },
+  })),
+};
+const request = (task = "one", path = "/messages") => new Request(`https://${host}${path}`, {
+  method: "POST", body: JSON.stringify({ task }),
+});
+
+function mixedFake() {
+  return replayFake({
+    name: "mixed", host, mode: "replay",
+    state: () => ({ useRecordings: false, reply: "scripted", seen: [] as string[] }),
+    helpers: ({ state }) => ({
+      useRecordings(enabled = true) { state.useRecordings = enabled; },
+      reply(text: string) { state.reply = text; },
+      seen() { return [...state.seen]; },
+    }),
+    async handler(req, state, ctx) {
+      const body = await req.clone().json() as { task: string };
+      state.seen.push(body.task);
+      if (state.useRecordings && new URL(req.url).pathname === "/messages") {
+        return ctx.replay(req);
+      }
+      return new Response(state.reply);
+    },
+  });
+}
+
+describe("scripted behavior on replay fakes", () => {
+  test("loading only loads; custom helpers select behavior and misses never fall back", async () => {
+    const fake = mixedFake();
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    const send = (task?: string, path?: string) => fake.handler(request(task, path), state, context);
+
+    expect(await (await send()).text()).toBe("scripted");
+    helpers.reply("configured");
+    helpers.replay(fixture);
+    expect(await (await send()).text()).toBe("configured");
+    helpers.useRecordings();
+    expect((await send("missing")).status).toBe(599);
+    // The same fake mixes scripted and replayed endpoints concurrently.
+    expect(await Promise.all([
+      send("two"), send("one", "/transcription"), send("one"),
+    ].map(async (response) => (await response).text()))).toEqual([
+      "recorded-two", "configured", "recorded-one",
+    ]);
+    expect((await send()).status).toBe(599);
+    helpers.useRecordings(false);
+    expect(await (await send()).text()).toBe("configured");
+    expect(helpers.count()).toBe(0);
+    expect(helpers.recorded()).toEqual([]);
+    expect(helpers.seen()).toHaveLength(8);
+  });
+
+  test("delegating without a cassette fails even when scripted responses are available", async () => {
+    const fake = mixedFake();
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    helpers.useRecordings();
+    expect((await fake.handler(request(), state, context)).status).toBe(599);
+  });
+
+  test("custom state and cassette cursors survive cloning and siblings remain independent", async () => {
+    const fake = mixedFake();
+    const parent = await fake.state!();
+    const parentHelpers = await fake.helpers!({ name: "mixed", state: parent, ctx: context });
+    parentHelpers.replay(fixture);
+    parentHelpers.useRecordings();
+    await fake.handler(request("one"), parent, context);
+    // Model the state inherited by forks, including custom state and cursors.
+    const left = structuredClone(parent);
+    const right = structuredClone(parent);
+    const leftHelpers = await fake.helpers!({ name: "mixed", state: left, ctx: context });
+    leftHelpers.reply("left only");
+    expect((await fake.handler(request("one"), right, context)).status).toBe(599);
+    expect(await (await fake.handler(request("two"), left, context)).text()).toBe("recorded-two");
+    expect(await (await fake.handler(request("two"), right, context)).text()).toBe("recorded-two");
+    leftHelpers.useRecordings(false);
+    expect(right.custom.useRecordings).toBe(true);
+    expect(right.custom.reply).toBe("scripted");
+    expect(parent.cursor.size).toBe(1);
+  });
+
+  test("async factories receive custom state and the normal fake context", async () => {
+    const ctx = { dnsName: async () => {} } as unknown as FakeContext;
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      state: async () => ({ reply: "async" }),
+      helpers: async ({ state, name, ctx: received }) => {
+        expect(name).toBe("mixed");
+        expect(received).toBe(ctx);
+        return { reply: (text: string) => { state.reply = text; } };
+      },
+      handler: (_req, state, received) => {
+        expect(received.dnsName).toBe(ctx.dnsName);
+        expect(typeof received.replay).toBe("function");
+        expect("replay" in ctx).toBe(false);
+        return new Response(state.reply);
+      },
+    });
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx });
+    helpers.reply("updated");
+    expect(await (await fake.handler(request(), state, ctx)).text()).toBe("updated");
+  });
+
+  test.each(["replay", "dump", "recorded", "count"])("rejects reserved helper name %s", async (name) => {
+    const fake = replayFake({ name: "mixed", host, helpers: () => ({ [name]: () => {} }) });
+    const state = await fake.state!();
+    await expect(Promise.resolve().then(() => fake.helpers!({ name: "mixed", state, ctx: context })))
+      .rejects.toThrow(`custom helper "${name}" is reserved`);
+  });
+
+  test("handler-only customization needs no state or helpers", async () => {
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      handler(req, state, ctx) {
+        expect(state).toBeUndefined();
+        return ctx.replay(req);
+      },
+    });
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    helpers.replay(fixture);
+    expect(await (await fake.handler(request(), state, context)).text()).toBe("recorded-one");
+  });
+
+  test("a consumed body reports how to inspect safely before delegation", async () => {
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      async handler(req, _state, ctx) {
+        await req.json();
+        return ctx.replay(req);
+      },
+    });
+    const state = await fake.state!();
+    await expect(fake.handler(request(), state, context)).rejects.toThrow("inspect request.clone()");
+  });
+
+  test("public state, context, and helper types stay inferred through defineEnvironment", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spectest-replay-types-"));
+    try {
+      const config = join(dir, "tsconfig.json");
+      await writeFile(config, JSON.stringify({
+        extends: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
+        compilerOptions: {
+          noEmit: true,
+          typeRoots: [fileURLToPath(new URL("../../node_modules/@types", import.meta.url))],
+        },
+        include: [fileURLToPath(import.meta.url)],
+        exclude: [],
+      }));
+      const child = Bun.spawn([process.execPath, fileURLToPath(import.meta.resolve("typescript/bin/tsc")), "-p", config], {
+        stdout: "pipe", stderr: "pipe",
+      });
+      const [exit, stdout, stderr] = await Promise.all([
+        child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+      ]);
+      expect(exit, stdout + stderr).toBe(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }, 30_000);
+});
+
+// Checked with tsc as well as the runtime tests: inference must survive the
+// public components export and defineEnvironment's wrapped helper surface.
+function checkPublicTypes() {
+  const fake = replayFake({
+    name: "typed", host,
+    state: () => ({ enabled: false }),
+    helpers: ({ state }) => ({
+      enable(value: boolean) {
+        state.enabled = value;
+        // @ts-expect-error custom state is inferred, not any
+        state.missing;
+      },
+    }),
+    handler(req, state, ctx) {
+      const enabled: boolean = state.enabled;
+      const typedContext: ReplayFakeContext = ctx;
+      // @ts-expect-error internal cassette state is not exposed to the handler
+      state.cassette;
+      return enabled ? typedContext.replay(req) : new Response("scripted");
+    },
+  });
+  const env = defineEnvironment({ name: "typed", services: {}, fakes: { typed: fake } });
+  env.test("types", (ctx) => {
+    ctx.fakes.typed.enable(true);
+    ctx.fakes.typed.replay(fixture);
+    ctx.fakes.typed.dump();
+    // @ts-expect-error helper arguments retain their inferred types
+    ctx.fakes.typed.enable("yes");
+    // @ts-expect-error unknown helpers are not callable
+    ctx.fakes.typed.missing();
+  });
+  const handler: ReplayHandler<{ enabled: boolean }> = (req, state, ctx) =>
+    state.enabled ? ctx.replay(req) : new Response("scripted");
+  return handler;
+}

package/src/components/replayFake-record.test.ts

@@ -0,0 +1,156 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Isolate module mocks from other tests. Drive the actual record handler,
+// replacing only DNS/HTTPS transport; no credentials or external egress.
+test("recorded headers, redaction, and exact body bytes survive record → replay", async () => {
+  const moduleUrl = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+  const script = `
+    import { strict as assert } from "node:assert";
+    import { EventEmitter } from "node:events";
+    import { mock, test } from "bun:test";
+    import * as dnsPacket from ${JSON.stringify(import.meta.resolve("dns-packet"))};
+
+    test("record round trip", async () => {
+    mock.module("node:dgram", () => ({ createSocket() {
+      const socket = new EventEmitter();
+      socket.close = () => {};
+      socket.send = (_query, _port, _host, done) => {
+        done();
+        queueMicrotask(() => socket.emit("message", dnsPacket.encode({
+          type: "response", id: 1,
+          answers: [{ type: "A", name: "api.example.test", ttl: 60, data: "127.0.0.1" }],
+        })));
+      };
+      return socket;
+    } }));
+
+    const upstreamHeaders = [];
+    mock.module("node:https", () => ({ request(options, callback) {
+      upstreamHeaders.push(options.headers);
+      const req = new EventEmitter();
+      req.write = () => {};
+      req.end = () => queueMicrotask(() => {
+        const res = new EventEmitter();
+        res.statusCode = 200;
+        res.headers = { "content-type": "text/plain" };
+        callback(res);
+        res.emit("data", Buffer.from("response"));
+        res.emit("end");
+      });
+      return req;
+    } }));
+
+    const { replayFake } = await import(${moduleUrl("./replayFake.ts")});
+    const { setRecordSecrets } = await import(${moduleUrl("../record-secrets.ts")});
+    setRecordSecrets({ API_KEY: "recording-secret" });
+    const options = {
+      name: "test", host: "api.example.test",
+      inject: [{ headers: { authorization: "Bearer {{secret:API_KEY}}" } }],
+      redactPatterns: ["private-field"],
+    };
+    const record = replayFake({ ...options, mode: "record" });
+    const state = record.state();
+    const helpers = record.helpers({ name: "test", state, ctx: {} });
+    const bodies = ["\\ufeffhello", new Uint8Array([0, 128, 255]), "recording-secret private-field"];
+    for (const [i, body] of bodies.entries()) {
+      const res = await record.handler(new Request("https://api.example.test/messages", {
+        method: "POST", body,
+        headers: {
+          "X-Task": "task-" + i,
+          authorization: "Bearer dummy", cookie: "dummy-cookie",
+          "api-key": "dummy-api-key", "x-goog-api-key": "dummy-google-key",
+          "x-extra": "recording-secret private-field",
+        },
+      }), state, {});
+      assert.equal(res.status, 200, await res.text());
+    }
+    assert.equal(helpers.count(), 3);
+    assert.equal(upstreamHeaders[0].authorization, "Bearer recording-secret");
+    const cassette = JSON.parse(JSON.stringify(helpers.dump()));
+    assert.equal(cassette.interactions[0].request.body, "\\ufeffhello");
+    assert.equal(cassette.interactions[1].request.bodyEncoding, "base64");
+    assert.equal(cassette.interactions[2].request.body, "<REDACTED:API_KEY> <REDACTED>");
+    for (const [i, it] of cassette.interactions.entries()) {
+      assert.equal(it.request.headers["x-task"], "task-" + i);
+      assert.equal(it.request.headers["x-extra"], "<REDACTED:API_KEY> <REDACTED>");
+      for (const name of ["authorization", "cookie", "api-key", "x-goog-api-key"]) {
+        assert.equal(it.request.headers[name], undefined);
+      }
+    }
+    assert.equal(JSON.stringify(cassette).includes("recording-secret"), false);
+
+    for (const key of [undefined, r => r.headers["x-task"]]) {
+      const replay = replayFake({ ...options, mode: "replay", key });
+      const replayState = replay.state();
+      replay.helpers({ name: "test", state: replayState, ctx: {} }).replay(cassette);
+      for (const i of [2, 0, 1]) {
+        const res = await replay.handler(new Request("https://api.example.test/messages", {
+          method: "POST", body: bodies[i], headers: { "X-Task": "task-" + i },
+        }), replayState, {});
+        assert.equal(res.status, 200);
+        assert.equal(await res.text(), "response");
+      }
+    }
+    assert.equal(upstreamHeaders.length, 3); // Replay never forwards.
+
+    // The custom handler delegates through the same auto-mode pipeline.
+    // Scripted requests must neither forward nor enter the cassette.
+    const { startRecording, stopRecording } = await import(${moduleUrl("../recorder.ts")});
+    const mixed = replayFake({
+      ...options,
+      state: () => ({ useRecordings: false }),
+      helpers: ({ state }) => ({ useRecordings() { state.useRecordings = true; } }),
+      async handler(request, state, ctx) {
+        const body = await request.clone().text();
+        return state.useRecordings && body !== "scripted"
+          ? ctx.replay(request)
+          : new Response("scripted response");
+      },
+    });
+    const mixedState = await mixed.state();
+    const mixedHelpers = await mixed.helpers({ name: "test", state: mixedState, ctx: {} });
+    const send = (body) => mixed.handler(new Request("https://api.example.test/messages", {
+      method: "POST", body,
+    }), mixedState, {});
+    assert.equal(await (await send("delegated")).text(), "scripted response");
+    assert.equal(upstreamHeaders.length, 3);
+    mixedHelpers.useRecordings();
+    assert.equal(await (await send("scripted")).text(), "scripted response");
+    assert.equal(await (await send("delegated")).text(), "response");
+    assert.equal(upstreamHeaders.length, 4);
+    assert.equal(upstreamHeaders[3].authorization, "Bearer recording-secret");
+    assert.equal(mixedHelpers.count(), 1);
+    const mixedCassette = mixedHelpers.dump();
+    assert.equal(mixedCassette.interactions[0].request.body, "delegated");
+    mixedHelpers.replay(mixedCassette);
+    startRecording(); // Enter a test: auto now replays instead of forwarding.
+    try {
+      assert.equal(await (await send("scripted")).text(), "scripted response");
+      assert.equal(await (await send("delegated")).text(), "response");
+      assert.equal((await send("delegated")).status, 599);
+      assert.equal((await send("unrecorded")).status, 599);
+      assert.equal(mixedHelpers.count(), 1);
+      assert.equal(upstreamHeaders.length, 4);
+    } finally {
+      stopRecording();
+    }
+    });
+  `;
+  const dir = await mkdtemp(join(tmpdir(), "spectest-replay-record-"));
+  try {
+    const file = join(dir, "record.test.ts");
+    await writeFile(file, script);
+    const child = Bun.spawn([process.execPath, "test", file], {
+      stdout: "pipe", stderr: "pipe",
+    });
+    const [exit, stdout, stderr] = await Promise.all([
+      child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+    ]);
+    expect(exit, stdout + stderr).toBe(0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}, 10_000);