@specific.dev/spectest 0.106.0 → 0.107.1

package/README.md

@@ -107,6 +107,32 @@ return annotate(turns, "chat", {
 });
 ```
 
+## Inline replies (0.107.0)
+
+A `chat` message can carry an `id` — any non-empty string the fake chooses,
+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 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", {
+  messages: turns.map((t) => ({
+    id: t.id,
+    side: t.fromCustomer ? "self" : "other",
+    text: t.body,
+    replyTo: t.inReplyTo,
+  })),
+});
+```
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and

package/dist/annotate.d.ts

@@ -140,6 +140,21 @@ export interface ChatMessageAnnotation {
      * qualify and is dropped.
      */
     statusAt?: string;
+    /**
+     * The author's handle for this message — the provider's message id,
+     * usually — so a later message can reply to it by name. Any non-empty
+     * string; the dashboard never draws it.
+     */
+    id?: string;
+    /**
+     * The `id` of an earlier message in this transcript that this one
+     * replies to, drawn the way a messaging app threads a reply: an excerpt
+     * of that message quoted above this bubble, on this bubble's side. One
+     * that names no earlier message of the same call — an unknown id, a
+     * later message, the message itself — draws nothing extra, and the
+     * bubble reads as an ordinary message.
+     */
+    replyTo?: string;
 }
 /** One reaction on a {@link ChatMessageAnnotation}. */
 export interface ChatReactionAnnotation {

package/dist/annotate.js

@@ -191,6 +191,16 @@ function chatMessageOf(src) {
             msg.statusAt = truncateUtf8(src.statusAt).value;
         }
     }
+    // A reply threads to an earlier message by the handle its author gave
+    // it, so both ride through as given — a non-empty string, cut like a
+    // body — and anything else is dropped. Whether `replyTo` names an
+    // earlier message of the transcript is the dashboard's to decide: it
+    // draws the quote when it can and an ordinary bubble when it cannot.
+    if (typeof src.id === "string" && src.id !== "")
+        msg.id = truncateUtf8(src.id).value;
+    if (typeof src.replyTo === "string" && src.replyTo !== "") {
+        msg.replyTo = truncateUtf8(src.replyTo).value;
+    }
     return msg;
 }
 /** The block's `typing`: `self` or `other`, else nobody. The thread's

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/dist/recorder.d.ts

@@ -660,6 +660,15 @@ export interface ChatBlockMessage {
      *  text drawn after the status caption ("Read 23:14"). Rides with
      *  `status`; alone it has nothing to qualify. */
     statusAt?: string;
+    /** The author's handle for this message — the provider's message id,
+     *  usually — which a later message's `replyTo` names. Never drawn.
+     *  Absent when the author gave none. */
+    id?: string;
+    /** The `id` of an earlier message in the same block this one replies
+     *  to, drawn as a quoted excerpt of that message above the bubble, the
+     *  way a messaging app threads a reply. One that names no earlier
+     *  message draws nothing extra. */
+    replyTo?: string;
 }
 /** One reaction on a {@link ChatBlockMessage}. */
 export interface ChatBlockReaction {

package/package.json

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

package/src/annotate.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import { annotate, readAnnotation, type ChatMessageAnnotation } from "./annotate.js";
+import { truncateUtf8 } from "./recorder.js";
 
 /** Open a chat annotation: the messages its one block lowered to, and the
  *  value the test would receive. */
@@ -135,3 +136,69 @@ describe("annotate chat status and typing", () => {
     expect(chat(annotate(messages, "chat")).typing).toBeUndefined();
   });
 });
+
+describe("annotate chat inline replies", () => {
+  test("threads a reply to the earlier message it names and leaves the rest alone", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          { id: "m1", side: "other", text: "Let me check." },
+          { id: "m2", side: "self", text: "where is my order?", replyTo: "m1", new: true },
+          { side: "other", text: "It ships today." },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]).toEqual({ id: "m1", side: "other", text: "Let me check." });
+    expect(messages[1]).toEqual({ id: "m2", side: "self", text: "where is my order?", replyTo: "m1", new: true });
+    // A message with neither carries neither key.
+    expect(messages[2]).toEqual({ side: "other", text: "It ships today." });
+  });
+
+  // Both are the author's handles, carried as given: the dashboard sees
+  // the whole transcript and decides whether a `replyTo` names an earlier
+  // message, drawing an ordinary bubble when it does not. Only a value
+  // that is not a non-empty string is dropped.
+  test("drops an id or a replyTo that is not a non-empty string and carries the rest as given", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          { id: 42, side: "self", text: "a", replyTo: 7 },
+          { id: "", side: "self", text: "b", replyTo: "" },
+          { id: null, side: "self", text: "c", replyTo: true },
+          { id: "m4", side: "self", text: "d", replyTo: "nowhere" },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]).toEqual({ side: "self", text: "a" });
+    expect(messages[1]).toEqual({ side: "self", text: "b" });
+    expect(messages[2]).toEqual({ side: "self", text: "c" });
+    expect(messages[3]).toEqual({ id: "m4", side: "self", text: "d", replyTo: "nowhere" });
+  });
+
+  test("an id is cut like a body, and the replyTo that names it the same way", () => {
+    // Past the recorder's snippet cap, so the cut is visible.
+    const long = "m".repeat(300_000);
+    const { messages } = chat(
+      annotate(
+        [
+          { id: long, side: "other", text: "Let me check." },
+          { side: "self", text: "ok", replyTo: long },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]!.id).toBe(truncateUtf8(long).value);
+    expect(messages[0]!.id!.length).toBeLessThan(long.length);
+    expect(messages[1]!.replyTo).toBe(messages[0]!.id);
+  });
+
+  test("replies ride along when the messages are passed as options", () => {
+    const messages: ChatMessageAnnotation[] = [
+      { id: "m1", side: "other", text: "Done?" },
+      { id: "m2", side: "self", text: "Yes.", replyTo: "m1" },
+    ];
+    expect(chat(annotate({ id: 7 }, "chat", { title: "+46 70 123 45 67", messages })).messages).toEqual(messages);
+  });
+});

package/src/annotate.ts

@@ -199,6 +199,21 @@ export interface ChatMessageAnnotation {
    * qualify and is dropped.
    */
   statusAt?: string;
+  /**
+   * The author's handle for this message — the provider's message id,
+   * usually — so a later message can reply to it by name. Any non-empty
+   * string; the dashboard never draws it.
+   */
+  id?: string;
+  /**
+   * The `id` of an earlier message in this transcript that this one
+   * replies to, drawn the way a messaging app threads a reply: an excerpt
+   * of that message quoted above this bubble, on this bubble's side. One
+   * that names no earlier message of the same call — an unknown id, a
+   * later message, the message itself — draws nothing extra, and the
+   * bubble reads as an ordinary message.
+   */
+  replyTo?: string;
 }
 
 /** One reaction on a {@link ChatMessageAnnotation}. */
@@ -394,6 +409,15 @@ function chatMessageOf(src: Record<string, unknown>): ChatBlockMessage {
       msg.statusAt = truncateUtf8(src.statusAt).value;
     }
   }
+  // A reply threads to an earlier message by the handle its author gave
+  // it, so both ride through as given — a non-empty string, cut like a
+  // body — and anything else is dropped. Whether `replyTo` names an
+  // earlier message of the transcript is the dashboard's to decide: it
+  // draws the quote when it can and an ordinary bubble when it cannot.
+  if (typeof src.id === "string" && src.id !== "") msg.id = truncateUtf8(src.id).value;
+  if (typeof src.replyTo === "string" && src.replyTo !== "") {
+    msg.replyTo = truncateUtf8(src.replyTo).value;
+  }
   return msg;
 }
 

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. */

package/src/recorder.ts

@@ -912,6 +912,15 @@ export interface ChatBlockMessage {
    *  text drawn after the status caption ("Read 23:14"). Rides with
    *  `status`; alone it has nothing to qualify. */
   statusAt?: string;
+  /** The author's handle for this message — the provider's message id,
+   *  usually — which a later message's `replyTo` names. Never drawn.
+   *  Absent when the author gave none. */
+  id?: string;
+  /** The `id` of an earlier message in the same block this one replies
+   *  to, drawn as a quoted excerpt of that message above the bubble, the
+   *  way a messaging app threads a reply. One that names no earlier
+   *  message draws nothing extra. */
+  replyTo?: string;
 }
 
 /** One reaction on a {@link ChatBlockMessage}. */