@specific.dev/spectest 0.99.0 → 0.101.0

package/src/components/replayFake.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import type { FakeContext } from "../index.js";
+import { replayFake, type Cassette, type CassetteInteraction, type ReplayFakeOptions, type ReplayRequest, type ReplayKey, type MatchKey } from "./index.js";
+
+const context = {} as FakeContext;
+const host = "api.example.test";
+const sha = (body: string | Uint8Array) => `sha256:${createHash("sha256").update(body).digest("hex")}`;
+
+function interaction(body: string | Uint8Array, answer: string, path = "/messages"): CassetteInteraction {
+  return {
+    request: {
+      method: "POST", path, query: {}, headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : Buffer.from(body).toString("base64"),
+      bodyEncoding: typeof body === "string" ? "utf8" : "base64",
+      bodyHash: sha(body),
+    },
+    response: { status: 200, headers: {}, body: answer, bodyEncoding: "utf8" },
+  };
+}
+
+function cassette(interactions: CassetteInteraction[]): Cassette {
+  return { version: 1, fake: "test", host, interactions };
+}
+
+async function harness(options: Partial<ReplayFakeOptions> = {}) {
+  const fake = replayFake({ name: "test", host, mode: "replay", ...options });
+  const state = await fake.state!();
+  const helpers = await fake.helpers!({ name: "test", state, ctx: context });
+  return {
+    state, helpers,
+    async send(body: string | Uint8Array = "", path = "/messages", init: RequestInit = {}) {
+      return await fake.handler(new Request(`https://${host}${path}`, {
+        method: "POST", body: body as BodyInit, ...init,
+      }), state, context);
+    },
+  };
+}
+
+describe("replay request identity", () => {
+  test("default matches 654 concurrent requests by body, independently of arrival order", async () => {
+    const h = await harness();
+    const calls = Array.from({ length: 654 }, (_, id) => interaction(JSON.stringify({ id }), `answer-${id}`));
+    h.helpers.replay(cassette(calls));
+    // A permutation visits every identity once in a different order.
+    const results = await Promise.all(calls.map(async (_, i) => {
+      const id = (i * 37) % calls.length;
+      const response = await h.send(JSON.stringify({ id }));
+      expect(response.status).toBe(200);
+      expect(await response.text()).toBe(`answer-${id}`);
+    }));
+    expect(results).toHaveLength(654);
+    expect(h.state.cursor.size).toBe(654);
+  });
+
+  test("default uses method/path/normalized query/exact bytes, including old cassettes without hashes", async () => {
+    const h = await harness();
+    const it = interaction('{"a":1}', "ok");
+    delete it.request.bodyHash;
+    delete it.request.bodyEncoding;
+    it.request.query = { b: ["1", "2"], a: ["x"] };
+    h.helpers.replay(cassette([it]));
+    for (const [body, path, init] of [
+      ['{ "a":1}', "/messages?a=x&b=2&b=1", {}],
+      ['{"a":1}', "/other?a=x&b=2&b=1", {}],
+      ['{"a":1}', "/messages?a=x&b=2&b=1", { method: "PUT" }],
+      ['{"a":1}', "/messages?a=y&b=2&b=1", {}],
+    ] as const) expect((await h.send(body, path, init)).status).toBe(599);
+    expect(await (await h.send('{"a":1}', "/messages?b=2&a=x&b=1")).text()).toBe("ok");
+  });
+
+  test("the existing committed HTTP cassette still replays with the new default", async () => {
+    const h = await harness();
+    const existing = await Bun.file(new URL("../../../examples/replay-fake/spectest/tests/recordings/httpbin.json", import.meta.url)).json() as Cassette;
+    h.helpers.replay(existing);
+    const response = await h.send("", "/get?hello=world", { method: "GET", body: null });
+    expect(response.status).toBe(200);
+    expect((await response.json()).args).toEqual({ hello: ["world"] });
+  });
+
+  test("SigV4 query credentials stay outside default and custom identity", async () => {
+    for (const key of [undefined, (r: ReplayRequest) => ({ path: r.path, query: r.query })]) {
+      const h = await harness({ key, sign: { type: "awsSigv4", accessKeyId: "ACCESS", secretAccessKey: "SECRET" } });
+      h.helpers.replay(cassette([interaction("body", "ok")]));
+      expect(await (await h.send("body", "/messages?X-Amz-Signature=changing&X-Amz-Date=20261001")).text()).toBe("ok");
+    }
+  });
+
+  test("Dentio keys separate model/tasks while ignoring a changing date", async () => {
+    let evaluations = 0;
+    const h = await harness({ key(request) {
+      evaluations++;
+      const body = request.json<{ system: { text: string }[] }>();
+      return { model: request.path, task: body.system[0].text.slice(0, 200) };
+    } });
+    const calls = Array.from({ length: 8 }, (_, i) => ({
+      task: `task-${i}`.padEnd(200, "."),
+      path: `/model/${i < 4 ? "haiku" : "sonnet"}/converse`,
+    }));
+    const body = (task: string, date: string) => JSON.stringify({ system: [{ text: `${task} Today: ${date}` }] });
+    h.helpers.replay(cassette(calls.map((call, i) => interaction(body(call.task, "2026-10-01"), i === 4 ? "Karies 16o" : `task-${i}`, call.path))));
+    expect(evaluations).toBe(8);
+    for (const i of [7, 2, 4, 0, 6, 1, 5, 3]) {
+      expect(await (await h.send(body(calls[i].task, "2026-10-02"), calls[i].path)).text()).toBe(i === 4 ? "Karies 16o" : `task-${i}`);
+    }
+    expect(evaluations).toBe(16); // No rescanning/recomputing cassette keys.
+  });
+
+  test("custom key is the entire identity, with no implicit HTTP dimensions", async () => {
+    const h = await harness({ key: request => request.json<{ task: string }>().task });
+    h.helpers.replay(cassette([interaction('{"task":"same","date":"yesterday"}', "ok", "/old")]));
+    expect(await (await h.send('{"task":"same","date":"today"}', "/new?nonce=123", { method: "PUT" })).text()).toBe("ok");
+  });
+
+  test("JSON objects compare structurally but arrays preserve order", async () => {
+    const h = await harness({ key: request => request.json() });
+    h.helpers.replay(cassette([interaction('{"b":2,"a":{"x":[1,2]}}', "ok")]));
+    expect((await h.send('{"a":{"x":[2,1]},"b":2}')).status).toBe(599);
+    expect(await (await h.send('{ "a": {"x":[1,2]}, "b": 2 }')).text()).toBe("ok");
+  });
+
+  test("binary keys are lossless and distinct from JSON lookalikes", async () => {
+    const h = await harness({ key: request => ({ body: request.bytes() }) });
+    const bytes = new Uint8Array([0, 255, 128]);
+    h.helpers.replay(cassette([interaction(bytes, "binary")]));
+    expect((await h.send("[0,255,128]")).status).toBe(599);
+    expect(await (await h.send(bytes)).text()).toBe("binary");
+
+    const mixed = await harness({ key: r => r.path === "/binary" ? new Uint8Array([1, 2]) : r.json() });
+    mixed.helpers.replay(cassette([interaction("", "bytes", "/binary"), interaction("[1,2]", "array"), interaction('{"0":1,"1":2}', "object")]));
+    expect(await (await mixed.send("[1,2]")).text()).toBe("array");
+    expect(await (await mixed.send('{"0":1,"1":2}')).text()).toBe("object");
+    expect(await (await mixed.send("", "/binary")).text()).toBe("bytes");
+  });
+
+  test("empty and BOM-prefixed bodies preserve their bytes", async () => {
+    for (const key of [undefined, (r: ReplayRequest) => r.bytes()]) {
+      const h = await harness({ key });
+      h.helpers.replay(cassette([interaction("", "empty"), interaction("\ufeffhello", "bom")]));
+      expect(await (await h.send("")).text()).toBe("empty");
+      expect((await h.send("hello")).status).toBe(599);
+      expect(await (await h.send("\ufeffhello")).text()).toBe("bom");
+    }
+  });
+
+  test("same-key queues consume once, fail on exhaustion, and reset on reload", async () => {
+    const h = await harness();
+    const c = cassette([interaction("same", "first"), interaction("other", "other"), interaction("same", "second")]);
+    h.helpers.replay(c);
+    expect(await Promise.all([h.send("same"), h.send("same")].map(async p => (await p).text()))).toEqual(["first", "second"]);
+    const exhausted = await h.send("same");
+    expect(exhausted.status).toBe(599);
+    expect(await exhausted.text()).toContain("exhausted key");
+    expect(await (await h.send("missing")).text()).toContain("unknown key");
+    expect(await (await h.send("other")).text()).toBe("other");
+    h.helpers.replay(c);
+    expect(await (await h.send("same")).text()).toBe("first");
+  });
+
+  test("cassette keys and cursors are isolated between fake states", async () => {
+    const a = await harness(), b = await harness();
+    const c = cassette([interaction("same", "ok")]);
+    a.helpers.replay(c); b.helpers.replay(c);
+    expect(await (await a.send("same")).text()).toBe("ok");
+    expect((await a.send("same")).status).toBe(599);
+    expect(await (await b.send("same")).text()).toBe("ok");
+    // Inline input cannot mutate a loaded/indexed cassette.
+    c.interactions[0].response.body = "mutated";
+    expect(a.helpers.dump().interactions[0].response.body).toBe("ok");
+    a.helpers.dump().interactions[0].response.body = "mutated dump";
+    expect(a.helpers.dump().interactions[0].response.body).toBe("ok");
+  });
+
+  test("request accessors are synchronous, reusable, and omit internal hashes/credentials", async () => {
+    const h = await harness({ key(r) {
+      expect("bodyHash" in r).toBe(false);
+      expect(r.headers.authorization).toBeUndefined();
+      expect(r.headers.cookie).toBeUndefined();
+      expect(Object.isFrozen(r)).toBe(true);
+      expect(Object.isFrozen(r.query)).toBe(true);
+      const bytes = r.bytes(); bytes.fill(0);
+      expect(r.text()).toBe('{"a":1}');
+      expect(r.json<{ a: number }>()).toEqual({ a: 1 });
+      return r.headers["x-task"]!;
+    } });
+    const it = interaction('{"a":1}', "ok");
+    it.request.headers["x-task"] = "journal";
+    h.helpers.replay(cassette([it]));
+    expect(await (await h.send('{"a":1}', "/messages", { headers: { "X-Task": "journal", authorization: "secret", cookie: "secret" } })).text()).toBe("ok");
+  });
+
+  test("bad incoming JSON fails without consuming a response; bad loads preserve live state", async () => {
+    const h = await harness({ key: r => r.json() });
+    h.helpers.replay(cassette([interaction("{}", "ok")]));
+    expect(() => h.helpers.replay(cassette([interaction("invalid", "bad")]))).toThrow("interaction #1");
+    const bad = await h.send("invalid");
+    expect(bad.status).toBe(599);
+    expect(await bad.text()).toContain("invalid replay key");
+    expect(await (await h.send("{}")).text()).toBe("ok");
+  });
+
+  test.each([
+    undefined, NaN, Infinity, BigInt(1), new Date(), new Map(), Promise.resolve("x"),
+    { missing: undefined }, [undefined], Array(1), () => "x",
+  ])("rejects unsupported keys instead of silently collapsing identities: %p", async value => {
+    const h = await harness({ key: () => value as MatchKey });
+    expect(() => h.helpers.replay(cassette([interaction("", "bad")]))).toThrow("invalid replay key");
+  });
+
+  test("rejects cyclic keys but permits shared subobjects", async () => {
+    const value: Record<string, MatchKey> = {};
+    value.self = value;
+    const bad = await harness({ key: () => value });
+    expect(() => bad.helpers.replay(cassette([interaction("", "bad")]))).toThrow("cycles");
+    const shared = { a: 1 };
+    const good = await harness({ key: () => [shared, shared] });
+    good.helpers.replay(cassette([interaction("", "ok")]));
+    expect(await (await good.send()).text()).toBe("ok");
+  });
+
+  test("rejects an async callback that throws without leaking an unhandled rejection", async () => {
+    const h = await harness({ key: (async () => { throw new Error("async failure"); }) as unknown as ReplayFakeOptions["key"] });
+    expect(() => h.helpers.replay(cassette([interaction("", "bad")]))).toThrow("synchronous");
+    await Promise.resolve();
+  });
+
+  test("old match options fail with migration guidance", () => {
+    expect(() => replayFake({ name: "test", host, match: { body: "hash" } } as unknown as ReplayFakeOptions)).toThrow("has been replaced by `key(request)`");
+  });
+});
+
+// Compile-time API checks, verified by the targeted TypeScript check as well
+// as the SDK build. Never invoked: invalid callbacks must not run.
+function publicTypes(request: ReplayRequest): void {
+  const json: ReplayKey = r => r.json();
+  const bytes: ReplayKey = r => ({ body: r.bytes(), query: r.query });
+  void [json, bytes];
+  // @ts-expect-error bodyHash is internal, not part of the callback view.
+  request.bodyHash;
+  // @ts-expect-error Request metadata is read-only.
+  request.method = "POST";
+  // @ts-expect-error Query values are read-only.
+  request.query.id.push("another");
+  // @ts-expect-error Callbacks must be synchronous.
+  const asyncKey: ReplayKey = async r => r.text();
+  // @ts-expect-error Undefined is not an identity.
+  const absentKey: ReplayKey = () => undefined;
+  void [asyncKey, absentKey];
+  replayFake({ name: "test", host,
+    // @ts-expect-error Per-dimension matching switches have been removed.
+    match: { body: "hash" },
+  });
+}
+void publicTypes;