@specific.dev/spectest 0.88.2 → 0.89.0

package/src/harness/fetch.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { expect as assertValue } from "../index.js";
-import { type WrappedResponse } from "../inspect.js";
-import { recordFake, startRecording, stopRecording } from "../recorder.js";
+import { readRaw, readTag, type SpectestFetch, type WrappedResponse } from "../inspect.js";
+import { recordFake, startRecording, stopRecording, type HttpEvent } from "../recorder.js";
 import { installFetchWrapper, isTransportError } from "./fetch.js";
 import {
   bindInstrumentationScope,
@@ -65,6 +65,72 @@ describe("fetch execution scopes", () => {
     expect(stopRecording()).toEqual([]);
   });
 
+  test("header assertions retain HTTP provenance, including missing headers and cookies", async () => {
+    handler = () => new Response("ok", { headers: [
+      ["content-type", "text/plain"],
+      ["set-cookie", "a=1; Path=/"],
+      ["set-cookie", "b=2; Path=/"],
+    ] });
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/headers")) as unknown as WrappedResponse;
+      assertValue(res.headers.get("Content-Type")).toBe("text/plain");
+      assertValue(res.headers.get("x-missing")).toBe(null);
+      assertValue(res.headers.has("CONTENT-TYPE")).toBe(true);
+      assertValue(res.headers.has("x-missing")).toBe(false);
+      assertValue(res.headers.getSetCookie()).toEqual(["a=1; Path=/", "b=2; Path=/"]);
+      assertValue(res.headers.getSetCookie()[1]).toBe("b=2; Path=/");
+    });
+    const events = stopRecording();
+    expect(events.map((e) => e.kind)).toEqual(["http", ...Array(6).fill("assertion")]);
+    expect(events.slice(1)).toMatchObject([
+      { sourceSeq: events[0]!.seq, path: ["headers", "content-type"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "x-missing"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "content-type", "<has>"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "x-missing", "<has>"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "set-cookie"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "set-cookie", "1"] },
+    ]);
+  });
+
+  test("wrapped headers keep native iteration and expose raw headers for ordinary APIs", async () => {
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/headers")) as unknown as WrappedResponse;
+      const headers = res.headers;
+      const raw = res.unwrap().headers;
+      expect(res.headers).toBe(headers);
+      expect(headers.unwrap()).toBe(raw);
+      expect<unknown>(readRaw(headers)).toBe(raw);
+      expect(headers.get("content-type")?.unwrap() ?? null).toBe(raw.get("content-type"));
+      expect(headers.get("missing")).toBe(null);
+      expect(headers.has("missing").unwrap()).toBe(false);
+      expect([...headers]).toEqual([...raw]);
+      expect([...headers.entries()]).toEqual([...raw.entries()]);
+      expect([...headers.keys()]).toEqual([...raw.keys()]);
+      expect([...headers.values()]).toEqual([...raw.values()]);
+      const entries: [string, string][] = [];
+      headers.forEach((value, key) => entries.push([key, value]));
+      expect(entries).toEqual([...raw]);
+      assertValue(headers.transform("entries", (h) => Object.fromEntries(h))["content-type"])
+        .toBe(raw.get("content-type"));
+    });
+  });
+
+  test("cloned responses keep header provenance and independent bodies", async () => {
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/clone")) as unknown as WrappedResponse;
+      const clone = res.clone();
+      assertValue(clone.headers.get("content-type")).toBe("application/json;charset=utf-8");
+      expect(clone.unwrap()).not.toBe(res.unwrap());
+      expect((await clone.text()).unwrap()).toBe('{"value":42}');
+      expect((await res.json<{ value: number }>()).value.unwrap()).toBe(42);
+    });
+    const events = stopRecording();
+    expect(events).toMatchObject([
+      { kind: "http" },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["headers", "content-type"] },
+    ]);
+  });
+
   test("an HTTP fake records only the test's outer request", async () => {
     handler = (req) => {
       if (new URL(req.url).pathname === "/fake") {
@@ -142,6 +208,42 @@ describe("fetch execution scopes", () => {
     expect(stopRecording()).toEqual([]);
   }, 2_000);
 
+  test.each([
+    { contentType: "text/event-stream; charset=utf-8", captureBody: undefined },
+    { contentType: "text/plain", captureBody: false },
+  ])("instrumented streams return before closing: %j", async ({ contentType, captureBody }) => {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    handler = () => new Response(new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+        c.enqueue(new TextEncoder().encode("first chunk"));
+      },
+    }), { headers: { "content-type": contentType } });
+    try {
+      await runInstrumented(scope, async () => {
+        const res = await (fetch as unknown as SpectestFetch)(url("/stream"), {
+          captureBody, signal: AbortSignal.timeout(1_000),
+        });
+        assertValue(res.bodyUsed).toBe(false);
+        const reader = res.body!.getReader();
+        try {
+          const chunk = await reader.read();
+          expect(chunk.done).toBe(false);
+          assertValue(chunk.value!.transform("text", (bytes) => new TextDecoder().decode(bytes)))
+            .toBe("first chunk");
+        } finally { reader.releaseLock(); }
+      });
+    } finally { controller?.close(); }
+    const events = stopRecording();
+    expect(events).toMatchObject([
+      { kind: "http", status: 200 },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["bodyUsed"] },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["body", "<read>", "0", "<text>"] },
+    ]);
+    if (events[0]?.kind !== "http") throw new Error("Missing HTTP event");
+    expect((events[0] as HttpEvent).responseBody).toBeUndefined();
+  }, 2_000);
+
   test("test-authored ingress callbacks retain their scope but their fake upstream does not", async () => {
     const callback = runInstrumented(scope, () => bindInstrumentationScope(async () => {
       const res = await fetch(url("/interceptor")) as unknown as WrappedResponse;
@@ -241,6 +343,10 @@ describe("fetch execution scopes", () => {
       await runInstrumented(setup, async () => {
         const res = await fetch(url("/setup")) as unknown as WrappedResponse;
         expect(res.status.unwrap()).toBe(200);
+        expect(res.headers.get("content-type")?.unwrap()).toBe("application/json;charset=utf-8");
+        expect(readTag(res.headers.get("content-type"))).toEqual({
+          sourceSeq: undefined, path: ["headers", "content-type"],
+        });
         await runUninstrumented(async () => {
           expect((await fetch(url("/setup-fake"))).status).toBe(200);
         });

package/src/harness/fetch.ts

@@ -1,4 +1,4 @@
-import { wrapResponse, type WrappedResponse } from "../inspect.js";
+import { wrapResponse, type SpectestRequestInit, type WrappedResponse } from "../inspect.js";
 import { recordHttp, reserveEvent, truncateUtf8, type OmittedBody } from "../recorder.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength } from "./http-body.js";
 import { currentInstrumentationScope } from "./instrumentation-scope.js";
@@ -72,12 +72,11 @@ export function isTransportError(err: unknown): boolean {
 export function installFetchWrapper(): () => void {
   const original = globalThis.fetch;
   // SDK internals (the MCP client, its OAuth flow) must not see the
-  // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
-  // body to the end, which never finishes for an SSE stream.
+  // wrapper: its response properties and body readers return wrapped values.
   setRawFetch(original);
   const wrappedFn = async (
     input: Parameters<typeof fetch>[0],
-    init?: Parameters<typeof fetch>[1],
+    init?: SpectestRequestInit,
   ): Promise<Response | WrappedResponse> => {
     const scope = currentInstrumentationScope();
     if (!scope?.active) return original(input, init);
@@ -97,7 +96,11 @@ export function installFetchWrapper(): () => void {
       const contentType = res.headers.get("content-type");
       const contentLength = () => parseContentLength(res.headers.get("content-length"));
       const textual = isTextualContentType(contentType);
-      if (textual === false) {
+      const streaming = contentType?.split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+      if (init?.captureBody === false || streaming) {
+        // Return on headers: an open-ended stream must not be drained (or
+        // cloned into an unbounded background buffer) by the recorder.
+      } else if (textual === false) {
         responseBody = omittedBody("binary", contentType, contentLength());
       } else {
         try {

package/src/index.ts

@@ -17,9 +17,21 @@ export type {
   Wrapped,
   WrappedObject,
   WrappedArray,
+  WrappedHeaders,
+  WrappedBuffer,
+  WrappedBinaryView,
+  WrappedBytes,
+  WrappedBlob,
+  WrappedFile,
+  WrappedFormData,
+  WrappedStream,
+  WrappedReader,
+  WrappedBYOBReader,
+  WrappedReadResult,
   WrappedResponse,
   Provenanced,
   SpectestFetch,
+  SpectestRequestInit,
   Unwrap,
 } from "./inspect.js";
 import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
@@ -475,11 +487,15 @@ export interface SpectestContext<
   /**
    * Instrumented `fetch`. In a test each call is recorded on the timeline
    * and resolves to a {@link WrappedResponse}: reads carry provenance so
-   * `expect(res.status)` / `expect(await res.json())` nest under the HTTP
+   * `expect(res.status)`, `expect(res.headers.get("content-type"))`, and
+   * `expect(await res.json())` nest under the HTTP
    * call. Because the status-line accessors are {@link Carrier}s, a raw
    * `res.status === 200` is a *type error* — use `res.status.unwrap()` /
    * `res.unwrap().status`, or assert via `expect`. Outside a test the
    * result is wrapped the same way, just with no timeline to link to.
+   * Body readers (`bytes`, `arrayBuffer`, `blob`, `formData`, `json`, `text`)
+   * and stream reader values also retain provenance. Use `captureBody: false`
+   * for open-ended streams; SSE responses skip recorder body capture automatically.
    *
    * (The plain global `fetch` is wrapped the same way at runtime but keeps
    * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed

package/src/inspect-fetch.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { expect as assertValue } from "./index.js";
+import { readRaw, readTag, wrap, wrapResponse } from "./inspect.js";
+import { recordHttp, startRecording, stopRecording, type AssertionEvent } from "./recorder.js";
+
+let seq: number;
+beforeEach(() => {
+  startRecording();
+  seq = recordHttp({ method: "GET", url: "http://test/", status: 200, durationMs: 0 })!;
+});
+afterEach(() => { stopRecording(); });
+
+function paths() {
+  const assertions = stopRecording().filter((e): e is AssertionEvent => e.kind === "assertion");
+  for (const assertion of assertions) expect(assertion.sourceSeq).toBe(seq);
+  return assertions.map((e) => e.path);
+}
+
+describe("fetch body provenance", () => {
+  test("bytes retain indexes, sizes, derived values and native escape hatches", async () => {
+    const raw = new Uint8Array([0x89, 0x50, 0, 0xff]);
+    const res = wrapResponse(new Response(raw), seq);
+    assertValue(res.bodyUsed).toBe(false);
+    const bytes = await res.bytes();
+    assertValue(res.bodyUsed).toBe(true);
+    assertValue(bytes).toEqual(raw);
+    assertValue(bytes).toHaveLength(4);
+    assertValue(bytes.byteLength).toBe(4);
+    assertValue(bytes[0]).toBe(0x89);
+    assertValue(bytes.slice(1, 3)).toEqual(new Uint8Array([0x50, 0]));
+    assertValue(bytes.subarray(1).at(0)).toBe(0x50);
+    assertValue(bytes.includes(0xff)).toBe(true);
+    assertValue(bytes.filter((v) => v === 0)).toHaveLength(1);
+    assertValue(bytes.map((v) => v + 1)[2]).toBe(1);
+    assertValue(bytes.at(99)).toBe(undefined);
+    expect(bytes.length).toBe(4);
+    expect([...bytes]).toEqual([...raw]);
+    expect(bytes.unwrap()).toBeInstanceOf(Uint8Array);
+    expect(readRaw<unknown>(bytes)).toBe(bytes.unwrap());
+    expect(new TextDecoder().decode(bytes.unwrap())).toBe(new TextDecoder().decode(raw));
+    expect(paths()).toContainEqual(["body", "<subarray>", "<at>"]);
+  });
+
+  test("array buffers and derived DataViews retain provenance", async () => {
+    const res = wrapResponse(new Response(new Uint8Array([1, 2, 3])), seq);
+    const buffer = await res.arrayBuffer();
+    assertValue(buffer.byteLength).toBe(3);
+    assertValue(buffer.slice(1).byteLength).toBe(2);
+    const bytes = buffer.transform("bytes", (b) => new Uint8Array(b));
+    assertValue(bytes.buffer.byteLength).toBe(3);
+    const view = buffer.transform("view", (b) => new DataView(b));
+    assertValue(view.getUint16(0)).toBe(258);
+    expect(new Uint8Array(buffer.unwrap())).toEqual(new Uint8Array([1, 2, 3]));
+    expect(paths()).toEqual([
+      ["body", "byteLength"], ["body", "<slice>", "byteLength"],
+      ["body", "<bytes>", "buffer", "byteLength"], ["body", "<view>", "<getUint16>"],
+    ]);
+  });
+
+  test("blobs wrap metadata, slices, decoded bodies and streams", async () => {
+    const res = wrapResponse(new Response("hello", { headers: { "content-type": "text/plain" } }), seq);
+    const blob = await res.blob();
+    assertValue(blob.size).toBe(5);
+    assertValue(blob.type).toBe(blob.unwrap().type);
+    assertValue(await blob.slice(1, 4).text()).toBe("ell");
+    assertValue((await blob.bytes())[0]).toBe(104);
+    assertValue((await blob.arrayBuffer()).byteLength).toBe(5);
+    const reader = blob.stream().getReader();
+    try {
+      const chunk = await reader.read();
+      expect(chunk.done).toBe(false);
+      assertValue(chunk.value).toEqual(new TextEncoder().encode("hello"));
+    } finally { await reader.cancel(); reader.releaseLock(); }
+    expect(blob.unwrap()).toBeInstanceOf(Blob);
+    expect(paths()).toContainEqual(["body", "<stream>", "<read>", "0"]);
+  });
+
+  test("form data wraps missing and repeated fields and uploaded files", async () => {
+    const form = new FormData();
+    form.append("tag", "one");
+    form.append("tag", "two");
+    form.append("file", new File(["hello"], "hello.txt", { type: "text/plain", lastModified: 123 }));
+    const res = wrapResponse(new Response(form), seq);
+    const parsed = await res.formData();
+    assertValue(parsed.get("tag")).toBe("one");
+    assertValue(parsed.getAll("tag")).toEqual(["one", "two"]);
+    assertValue(parsed.getAll("tag")[1]).toBe("two");
+    assertValue(parsed.has("tag")).toBe(true);
+    assertValue(parsed.has("missing")).toBe(false);
+    assertValue(parsed.get("missing")).toBe(null);
+    const file = parsed.get("file");
+    if (!file || !("name" in file)) throw new Error("Expected a file");
+    assertValue(file.name).toBe("hello.txt");
+    assertValue(file.type).toBe(file.unwrap().type);
+    assertValue(file.size).toBe(5);
+    assertValue(file.lastModified).toBe(file.unwrap().lastModified);
+    assertValue(await file.text()).toBe("hello");
+    assertValue((await file.bytes())[0]).toBe(104);
+    expect([...parsed][0]).toEqual(["tag", "one"]);
+    expect(parsed.unwrap()).toBeInstanceOf(FormData);
+    expect(paths()).toContainEqual(["body", "file", "<text>"]);
+  });
+
+  test("top-level JSON null and absent bodies retain provenance", async () => {
+    const json = wrapResponse(new Response("null"), seq);
+    assertValue(await json.json<null>()).toBe(null);
+    const empty = wrapResponse(new Response(null, { status: 204 }), seq);
+    assertValue(empty.body).toBe(null);
+    expect(paths()).toEqual([["body"], ["body"]]);
+  });
+
+  test("Bun header helpers are wrapped and serialization stays native", () => {
+    const res = wrapResponse(new Response(null, { headers: [
+      ["x-test", "yes"], ["set-cookie", "a=1"], ["set-cookie", "b=2"],
+    ] }), seq);
+    assertValue(res.headers.getAll("Set-Cookie")).toEqual(["a=1", "b=2"]);
+    assertValue(res.headers.toJSON()["x-test"]).toBe("yes");
+    assertValue(res.headers.count).toBe(res.unwrap().headers.count);
+    expect(JSON.stringify(res.headers)).toBe(JSON.stringify(res.unwrap().headers));
+    expect(paths()).toEqual([["headers", "set-cookie"], ["headers", "x-test"], ["headers", "count"]]);
+  });
+
+  test("reader values are wrapped but done and locked remain control-flow booleans", async () => {
+    const res = wrapResponse(new Response("hello"), seq);
+    const body = res.body!;
+    expect(res.body).toBe(body);
+    const reader = body.getReader();
+    expect(body.locked).toBe(true);
+    expect(readRaw<unknown>(reader)).toBe(reader.unwrap());
+    let chunks = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      assertValue(value.byteLength).toBe(5);
+      chunks++;
+    }
+    expect(chunks).toBe(1);
+    reader.releaseLock();
+    expect(body.locked).toBe(false);
+    expect(paths()).toEqual([["body", "<read>", "0", "byteLength"]]);
+  });
+
+  test("BYOB readers wrap the returned view while preserving buffer semantics", async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      type: "bytes",
+      pull(controller) {
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+        controller.close();
+      },
+    });
+    const res = wrapResponse(new Response(stream), seq);
+    const reader = res.body!.getReader({ mode: "byob" });
+    const chunk = await reader.read(new Uint8Array(8));
+    expect(chunk.done).toBe(false);
+    assertValue(chunk.value).toEqual(new Uint8Array([1, 2, 3]));
+    expect((await reader.read(new Uint8Array(8))).done).toBe(true);
+    reader.releaseLock();
+    expect(paths()).toEqual([["body", "<read>", "0"]]);
+  });
+
+  test("tee and pipeThrough preserve provenance and pipeTo consumes native chunks", async () => {
+    const res = wrapResponse(new Response("hi"), seq);
+    const [left, right] = res.body!.tee();
+    const decoded = left.pipeThrough(new TextDecoderStream());
+    const reader = decoded.getReader();
+    assertValue((await reader.read()).value).toBe("hi");
+    reader.releaseLock();
+    const chunks: Uint8Array[] = [];
+    await right.pipeTo(new WritableStream({ write(chunk) { chunks.push(chunk); } }));
+    expect(chunks).toEqual([new TextEncoder().encode("hi")]);
+    expect(paths()).toEqual([["body", "<tee>", "0", "<pipeThrough>", "<read>", "0"]]);
+  });
+
+  test("native reader errors and body consumption errors propagate", async () => {
+    const res = wrapResponse(new Response("once"), seq);
+    await res.bytes();
+    await expect(res.text()).rejects.toThrow();
+    const failure = new Error("stream failed");
+    const broken = wrapResponse(new Response(new ReadableStream({ start(c) { c.error(failure); } })), seq);
+    const reader = broken.body!.getReader();
+    await expect(reader.read()).rejects.toBe(failure);
+    reader.releaseLock();
+  });
+
+  test("native body wrappers are available without a recorded event", async () => {
+    const bytes = await wrapResponse(new Response("hi"), undefined).bytes();
+    expect(bytes.byteLength.unwrap()).toBe(2);
+    expect(readTag(bytes[0])).toEqual({ sourceSeq: undefined, path: ["body", "0"] });
+  });
+
+  test("retagging native values unwraps fully and replaces their provenance", async () => {
+    const bytes = await wrapResponse(new Response("hi"), seq).bytes();
+    const retagged = wrap(bytes, 99, ["poll"]);
+    expect(retagged.unwrap()).toBe(bytes.unwrap());
+    expect(readTag(retagged.byteLength)).toEqual({ sourceSeq: 99, path: ["poll", "byteLength"] });
+    expect(retagged.byteLength.unwrap()).toBe(2);
+    const blob = await wrapResponse(new Response("hi"), seq).blob();
+    const retaggedBlob = wrap(blob, 99, ["poll"]);
+    expect(retaggedBlob.unwrap()).toBe(blob.unwrap());
+    expect((await retaggedBlob.text()).unwrap()).toBe("hi");
+  });
+});