@specific.dev/spectest 0.107.0 → 0.107.1

package/README.md

@@ -114,8 +114,13 @@ the provider's message handle usually; it is never drawn — and a reply names
 an earlier message's `id` as `replyTo`. The dashboard draws the reply the
 way a messaging app threads one: an excerpt of the earlier message in a
 muted mini-bubble directly above the reply, on the reply's side, with a
-short connector between them. A `replyTo` that names no earlier message of
-the same call draws nothing extra; the bubble is an ordinary message.
+short connector between them. A reply to the bubble right above it draws
+only the connector, since the message it answers is already on screen. A
+run of consecutive replies to one message quotes it once, above the first
+of them, and the rest draw only the connector so they read as one thread;
+a reply to a different message, or an ordinary message, ends the run. A
+`replyTo` that names no earlier message of the same call draws nothing
+extra; the bubble is an ordinary message.
 
 ```ts
 return annotate(turns, "chat", {

package/dist/components/replay-key.js

@@ -89,8 +89,8 @@ function requestView(request) {
 export function replaySignature(request, key) {
     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 });
+    // Preserve the original replay default: bodies and headers may change
+    // between recording and replay. Requests to the same endpoint consume
+    // responses in cassette order; body-sensitive identity is opt-in via key.
+    return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query });
 }

package/dist/components/replayFake.d.ts

@@ -71,8 +71,10 @@ export interface ReplayFakeOptions<S = undefined, H extends Record<string, unkno
      *  resolved via an external DNS server — see the module header). Your
      *  app points at this real host directly; no separate stand-in. */
     host: string;
-    /** Complete request identity. Default: method, path, normalized query,
-     *  and exact body bytes. The same synchronous, deterministic callback runs
+    /** Complete request identity. Default: method, path, and normalized query;
+     *  bodies and headers are ignored, and matching responses replay in cassette
+     *  order. Include body content in a custom key to distinguish concurrent
+     *  calls to the same endpoint. The same synchronous, deterministic callback runs
      *  on recorded and incoming requests. Return JSON values and/or Uint8Array
      *  bytes; objects compare independently of property order. No implicit
      *  matching dimensions or fallback apply when a key is supplied. */

package/package.json

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

package/src/components/replay-key.ts

@@ -120,8 +120,8 @@ function requestView(request: CassetteRequest): ReplayRequest {
 /** 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 });
+  // Preserve the original replay default: bodies and headers may change
+  // between recording and replay. Requests to the same endpoint consume
+  // responses in cassette order; body-sensitive identity is opt-in via key.
+  return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query });
 }

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

@@ -25,6 +25,7 @@ const request = (task = "one", path = "/messages") => new Request(`https://${hos
 function mixedFake() {
   return replayFake({
     name: "mixed", host, mode: "replay",
+    key: request => ({ method: request.method, path: request.path, task: request.json<{ task: string }>().task }),
     state: () => ({ useRecordings: false, reply: "scripted", seen: [] as string[] }),
     helpers: ({ state }) => ({
       useRecordings(enabled = true) { state.useRecordings = enabled; },

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

@@ -5,7 +5,7 @@ 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 () => {
+test("recorded bodies and redaction survive; replay uses default order or an explicit header key", async () => {
   const moduleUrl = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
   const script = `
     import { strict as assert } from "node:assert";
@@ -37,7 +37,7 @@ test("recorded headers, redaction, and exact body bytes survive record → repla
         res.statusCode = 200;
         res.headers = { "content-type": "text/plain" };
         callback(res);
-        res.emit("data", Buffer.from("response"));
+        res.emit("data", Buffer.from(options.headers["x-task"] ? "response-" + options.headers["x-task"] : "response"));
         res.emit("end");
       });
       return req;
@@ -86,12 +86,12 @@ test("recorded headers, redaction, and exact body bytes survive record → repla
       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]) {
+      for (const [position, i] of [2, 0, 1].entries()) {
         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(await res.text(), "response-task-" + (key ? i : position));
       }
     }
     assert.equal(upstreamHeaders.length, 3); // Replay never forwards.

package/src/components/replayFake.test.ts

@@ -6,6 +6,9 @@ import { replayFake, type Cassette, type CassetteInteraction, type ReplayFakeOpt
 const context = {} as FakeContext;
 const host = "api.example.test";
 const sha = (body: string | Uint8Array) => `sha256:${createHash("sha256").update(body).digest("hex")}`;
+const exactBodyKey: ReplayKey = request => ({
+  method: request.method, path: request.path, query: request.query, body: request.bytes(),
+});
 
 function interaction(body: string | Uint8Array, answer: string, path = "/messages"): CassetteInteraction {
   return {
@@ -38,8 +41,8 @@ async function harness(options: Partial<ReplayFakeOptions> = {}) {
 }
 
 describe("replay request identity", () => {
-  test("default matches 654 concurrent requests by body, independently of arrival order", async () => {
-    const h = await harness();
+  test("explicit body key matches 654 concurrent requests independently of arrival order", async () => {
+    const h = await harness({ key: exactBodyKey });
     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.
@@ -53,7 +56,7 @@ describe("replay request identity", () => {
     expect(h.state.cursor.size).toBe(654);
   });
 
-  test("default uses method/path/normalized query/exact bytes, including old cassettes without hashes", async () => {
+  test("default uses method/path/normalized query and ignores changed bodies and headers", async () => {
     const h = await harness();
     const it = interaction('{"a":1}', "ok");
     delete it.request.bodyHash;
@@ -61,15 +64,36 @@ describe("replay request identity", () => {
     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");
+    expect(await (await h.send('{"a":2,"generatedId":"new"}', "/messages?b=2&a=x&b=1", {
+      headers: { "content-type": "text/plain", "x-request-id": "new" },
+    })).text()).toBe("ok");
+  });
+
+  test.each([true, false])("default replays version 1 cassettes in order despite body drift (stored hashes: %p)", async storedHashes => {
+    const h = await harness();
+    const c = cassette([
+      interaction('{"projectId":"old","turn":1}', "first"),
+      interaction('{"projectId":"old","turn":2}', "second"),
+    ]);
+    for (const it of c.interactions) {
+      if (storedHashes) it.request.body = "<REDACTED>";
+      else { delete it.request.bodyHash; delete it.request.bodyEncoding; }
+    }
+    h.helpers.replay(JSON.parse(JSON.stringify(c)));
+    expect(await (await h.send('{"projectId":"new","turn":1}')).text()).toBe("first");
+    expect(await (await h.send('{"projectId":"new","turn":2}')).text()).toBe("second");
+    const exhausted = await h.send("another body");
+    expect(exhausted.status).toBe(599);
+    expect(await exhausted.text()).toContain("exhausted key");
+    h.helpers.replay(c);
+    expect(await (await h.send("yet another body")).text()).toBe("first");
   });
 
-  test("the existing committed HTTP cassette still replays with the new default", async () => {
+  test("the existing committed HTTP cassette still replays with the 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);
@@ -134,7 +158,7 @@ describe("replay request identity", () => {
   });
 
   test("empty and BOM-prefixed bodies preserve their bytes", async () => {
-    for (const key of [undefined, (r: ReplayRequest) => r.bytes()]) {
+    for (const key of [exactBodyKey, (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");
@@ -144,7 +168,7 @@ describe("replay request identity", () => {
   });
 
   test("same-key queues consume once, fail on exhaustion, and reset on reload", async () => {
-    const h = await harness();
+    const h = await harness({ key: exactBodyKey });
     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"]);

package/src/components/replayFake.ts

@@ -161,8 +161,10 @@ export interface ReplayFakeOptions<
    *  resolved via an external DNS server — see the module header). Your
    *  app points at this real host directly; no separate stand-in. */
   host: string;
-  /** Complete request identity. Default: method, path, normalized query,
-   *  and exact body bytes. The same synchronous, deterministic callback runs
+  /** Complete request identity. Default: method, path, and normalized query;
+   *  bodies and headers are ignored, and matching responses replay in cassette
+   *  order. Include body content in a custom key to distinguish concurrent
+   *  calls to the same endpoint. The same synchronous, deterministic callback runs
    *  on recorded and incoming requests. Return JSON values and/or Uint8Array
    *  bytes; objects compare independently of property order. No implicit
    *  matching dimensions or fallback apply when a key is supplied. */