testkit (MCP surface) — MVP

Black-box tests through the MCP surface, on the vendored mcporter fork (vendor/mcporter, with its headless cookieConsentStrategy). Every run emits a chat-transcript recording (run.json) — the MCP surface is an agent-in-a-chat, so that's the natural shape.

Write a test

import { mcpTarget, mcpTest, cookieConsentStrategy } from "./src/testkit.mjs";

// the per-host seam: which MCP server + how to consent (headless, CI-safe)
const selfhost = mcpTarget({
  name: "selfhost",
  server: "http://localhost:5173/mcp",
  consent: cookieConsentStrategy({ appBaseUrl: "http://localhost:5173", email, password }),
});

mcpTest("execute runs code", selfhost, async (mcp) => {
  mcp.say("Confirm the sandbox evaluates and returns a value");  // → reasoning turn
  const r = await mcp.call("execute", { code: "return 6*7;" });  // → tool turn
  mcp.expect(r.text).toBe("42");                                 // → assert turn
});

Run + watch

node run.mjs                      # runs tests, writes runs/*.run.json, prints chat
node src/render.mjs runs/X.run.json            # render a recording in the terminal
node src/render.mjs runs/X.run.json --html out.html   # watchable HTML
node serve.mjs                    # serve runs/ (index + per-run HTML) on :8901

What a recording is

run.json = a chat transcript (turns: user / assistant·reasoning / tool / assert / error) + asserts + ok/error/durationMs. The HTML renders it as a chat: task bubble → reasoning → collapsible tool cards (args + result) → inline asserts. Failures record too — ok:false with the failing turn in place.

Status / next

• Now: scripted brain (deterministic, no LLM). Proven against dev /mcp.
• Next: agentTest — LLM brain (real model drives via MCP, reasoning captured verbatim); raw JSON-RPC protocol[] layer linked to tool turns; MCP-apps as app turns. Productionize to TS + Effect Vitest later (see memory: effect-testing-stack-note).
• Self-contained ESM JS under testkit/ (not in the bun workspace) — imports the fork's built dist. Throwaway-grade until productionized; the proof is real.