@specific.dev/spectest 0.55.0 → 0.56.0

package/dist/recorder.d.ts

@@ -599,6 +599,7 @@ export type StepBlock = {
         value?: string;
         error?: boolean;
     }[];
+    label?: string;
 } | {
     type: "table";
     columns: string[];
@@ -611,6 +612,10 @@ export type StepBlock = {
     type: "chat";
     messages: ChatBlockMessage[];
     label?: string;
+} | {
+    type: "details";
+    summary: string;
+    blocks: StepBlock[];
 };
 /** One message of a `chat` block. */
 export interface ChatBlockMessage {

package/package.json

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

package/src/daemon.ts

@@ -118,6 +118,10 @@ import {
 } from "./harness/methods.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
+// `ctx.mcp(url)`. One client per call, no registry: an authenticated
+// client is passed to descendants as a test's return value.
+import { openMcp } from "./mcp.js";
+import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
   pauseRecording,
@@ -4178,6 +4182,10 @@ function isTransportError(err: unknown): boolean {
  */
 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.
+  setRawFetch(original);
   const wrappedFn = async (
     input: Parameters<typeof fetch>[0],
     init?: Parameters<typeof fetch>[1],
@@ -4934,6 +4942,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     openTerminal: recordedOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    mcp: openMcp,
     testName: testCase.name,
     parent,
   };
@@ -5455,6 +5464,7 @@ async function evalCode(
     openTerminal: evalOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    mcp: openMcp,
     testName: "eval",
     parent: undefined,
   };

package/src/harness/raw-fetch.ts

@@ -0,0 +1,36 @@
+// The real `fetch`, for SDK internals that must not go through the test
+// recorder's wrapper.
+//
+// While a test (or an eval) runs, the daemon replaces `globalThis.fetch`
+// with an instrumented one: it records an `http` event, and it hands back
+// a WRAPPED response whose `ok` / `status` are provenance handles rather
+// than a boolean and a number. That is exactly right for a test's own
+// calls, and exactly wrong inside the SDK, in two ways:
+//
+//   1. `if (!res.ok)` is always false against a handle, because a handle
+//      is an object. An SDK client that checks it would read a `401` as a
+//      success. (`pauseRecording()` does not help: it stops the event, not
+//      the wrapper.)
+//   2. The wrapper clones the response and reads the clone to the end so
+//      it can record the body. For a streaming reply — Server-Sent Events
+//      — that does not finish until the stream closes, so the caller is
+//      handed its response only after the stream it was waiting to read
+//      has already ended. A long-lived stream deadlocks.
+//
+// So SDK-internal HTTP goes through `rawFetch`. The daemon publishes the
+// original here when it installs its wrapper.
+
+let original: typeof fetch | undefined;
+
+/** Called by the daemon with the real `fetch`, before it installs its
+ *  instrumented one. */
+export function setRawFetch(fn: typeof fetch): void {
+  original = fn;
+}
+
+/** `fetch`, never the instrumented wrapper. Falls back to the global for
+ *  a context where nothing was ever installed (unit tests, a plain
+ *  script). */
+export function rawFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  return (original ?? globalThis.fetch)(input as RequestInfo, init);
+}

package/src/ids.ts

@@ -44,7 +44,18 @@ export function generateId(prefix: string): string {
   return `${prefix}_0${base32Crockford(digest.subarray(0, 16)).slice(0, RANDOM_LEN)}`;
 }
 
-/** Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool). */
+/**
+ * Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool).
+ *
+ * Exported because every in-VM secret with a uniqueness requirement has
+ * the same problem as an id: Bun's pool is frozen into the snapshot, so
+ * sibling forks draw identical bytes. An OAuth PKCE verifier and `state`
+ * (`mcp-auth.ts`) must come from here, not from `crypto.getRandomValues`.
+ */
+export function secureRandomBytes(n: number): Uint8Array {
+  return urandom(n);
+}
+
 function urandom(n: number): Uint8Array {
   const buf = new Uint8Array(n);
   try {

package/src/index.ts

@@ -66,6 +66,34 @@ export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./br
 
 import type { Browser, BrowserOptions } from "./browser.js";
 
+// The MCP client (`ctx.mcp`). Drives a Model Context Protocol server the
+// way a real AI client would, with the OAuth flow a test runs through its
+// own browser. See `mcp.ts`.
+export {
+  McpHttpError,
+  McpRpcError,
+  McpAuthDeniedError,
+  type Mcp,
+  type McpOptions,
+  type McpAuthorization,
+  type McpChallenge,
+  type McpIdentity,
+  type McpToolResult,
+  type McpToolInfo,
+  type McpResourceInfo,
+  type McpResourceContents,
+  type McpPromptInfo,
+  type McpPromptResult,
+  type McpContent,
+  type McpNotification,
+  type McpSamplingRequest,
+  type McpSamplingResult,
+  type AuthorizeOptions,
+  type AuthorizationServerInfo,
+} from "./mcp.js";
+
+import type { Mcp, McpOptions } from "./mcp.js";
+
 // Playwright-native locators — the select-then-act surface shared by
 // `ctx.browser()` and `ctx.mobile()`. `Locator` mirrors playwright-core's
 // Locator (getBy*/filter/first/nth/click/fill/textContent/…, STRICT mode).
@@ -1498,6 +1526,47 @@ export interface TestContext<
    * natural way to assert on the exit code.
    */
   openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
+  /**
+   * Connect to a Model Context Protocol server over HTTP, as an AI client
+   * would. Every tool call, resource read and prompt renders as its own
+   * step in the timeline, with the arguments and the result.
+   *
+   * ```ts
+   * const mcp = await ctx.mcp("https://api.test/mcp");
+   * const res = await mcp.call("create_invoice", { customer: "Acme" });
+   * expect(res.json<{ id: string }>().id).toMatch(/^inv_/);
+   * ```
+   *
+   * **Each call returns a NEW client.** There is no per-name registry like
+   * `ctx.browser("alice")` has, and no default session. A client that has
+   * authenticated is handed to the tests that need it, as this test's
+   * return value — `ctx.parent` crosses the fork in daemon memory, live
+   * connections included:
+   *
+   * ```ts
+   * export const signedIn = env.test("sign in", async (ctx) => {
+   *   const mcp = await ctx.mcp(URL);
+   *   const auth = await mcp.authorize();
+   *   const page = await ctx.browser();
+   *   await page.goto(auth.url);
+   *   await page.getByRole("button", { name: "Allow" }).click();
+   *   await auth.complete();
+   *   return mcp;
+   * });
+   *
+   * env.test("call a tool", { dependsOn: signedIn }, async (ctx) => {
+   *   await ctx.parent.call("create_invoice", { amount: 250 });
+   * });
+   * ```
+   *
+   * Two identities are two calls to `ctx.mcp` — nothing to name.
+   *
+   * A server that needs authorization answers `401`, which is reported and
+   * not hidden: `ctx.mcp(url)` returns an unauthenticated client carrying
+   * the challenge, and a call on it fails with the server's own rejection.
+   * That is what makes "this tool is protected" a test.
+   */
+  mcp(url: string, opts?: McpOptions): Promise<Mcp>;
   /**
    * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
    *