@specific.dev/spectest 0.64.0 → 0.67.0

package/src/components/supabase.ts

@@ -1043,6 +1043,14 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** Where the generated entry of the shared isolate lives — outside the repo
+ *  mount, which is read-only and the user's checkout, and NOT under /tmp:
+ *  the runtime gives its workers an in-memory /tmp, so a file the main
+ *  worker writes there does not exist for the user worker's bootstrap
+ *  ("could not find an appropriate entrypoint"). */
+const SHARED_DIR = "/home/deno/spectest-functions";
+const WORKER_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+
 /** One isolate per function, reused across requests (the runtime pools by
  *  servicePath). The idle timeout is a day, not upstream's five minutes: a
  *  test environment is a snapshot lineage whose forks inherit these
@@ -1053,32 +1061,268 @@ function workerFor(name: string) {
   return EdgeRuntime.userWorkers.create({
     servicePath: FUNCTIONS_DIR + "/" + name,
     memoryLimitMb: 256,
-    workerTimeoutMs: 24 * 60 * 60 * 1000,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
     noModuleCache: false,
     importMapPath: null,
     envVars: Object.entries(Deno.env.toObject()),
   });
 }
 
-/** Boot every function's isolate now, without calling it. Creating the
- *  worker loads the module graph and runs the module's top level — for a
- *  function that is its \`Deno.serve(handler)\` registration, no business
- *  logic. Called once at environment setup, before the warm snapshot, so
- *  the isolates are shared, clean pages of the snapshot rather than a boot
- *  in every test that first touches a function. */
-async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, string> }> {
+async function exists(path: string): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The function directories: every child of FUNCTIONS_DIR with an index.ts,
+ *  minus the conventional private ones. */
+async function functionNames(): Promise<string[]> {
   const names: string[] = [];
   for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
     if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    if (await exists(FUNCTIONS_DIR + "/" + entry.name + "/index.ts")) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Every "https://deno.land/std@…/http/server.ts" a source under the
+ *  functions directory imports — the legacy serve() each of them has to be
+ *  redirected to the shim in the shared isolate. */
+async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
+  for await (const e of Deno.readDir(dir)) {
+    const p = dir + "/" + e.name;
+    if (e.isDirectory) {
+      if (e.name !== "node_modules" && !e.name.startsWith(".")) await stdServerUrls(p, out);
+      continue;
+    }
+    if (!/\.(ts|tsx|js|mjs|jsx)$/.test(e.name)) continue;
+    const src = await Deno.readTextFile(p);
+    for (const m of src.matchAll(/https:\/\/deno\.land\/std@[0-9.]+\/http\/server\.ts/g)) out.add(m[0]);
+  }
+}
+
+// ── The shared isolate ────────────────────────────────────────────────────
+//
+// The runtime's own model is one isolate per function, each loading its own
+// copy of the module graph. On a project with dozens of functions sharing a
+// \`_shared/\` tree that is dozens of copies of the same graph — measured at
+// ~90 MB and ~1 s per function, against 18 MB for an empty isolate — and in
+// an 8 GB guest that memory comes straight out of the page cache every test
+// needs. So by default every function is loaded into ONE user worker: a
+// generated entry module imports each function's index.ts in turn, a prelude
+// (imported first, so it runs first) has replaced \`Deno.serve\` with a
+// registration that records the handler under the function whose module is
+// calling, the std \`serve()\` the older functions use is redirected to the
+// same registration by an import map, and the worker's own server routes a
+// request to the handler of the function its path names. The runtime, the
+// request a function receives and the per-function JWT check are unchanged;
+// what differs from hosted Supabase is that module-level state is one
+// object for every function rather than one per function.
+//
+// There is deliberately no opt-out: it stands in wherever it can be exact,
+// and where it cannot the per-function isolates are used. A function with its own
+// deno.json / import map (per-function resolution the one config cannot
+// express), a functions/deno.jsonc (comments; not merged) or a config that
+// names an importMap keep the per-function isolates, and so does a shared
+// isolate that fails to boot — with the reason in the log, since a boot
+// failure names the module at fault.
+
+interface SharedSpec {
+  names: string[];
+  reason: string | null;
+}
+let sharedSpec: Promise<SharedSpec> | null = null;
+
+/** Why the shared isolate cannot stand in for per-function ones, or null. */
+async function sharedBlocker(names: string[]): Promise<string | null> {
+  for (const n of names) {
+    for (const f of ["deno.json", "deno.jsonc", "import_map.json"]) {
+      if (await exists(FUNCTIONS_DIR + "/" + n + "/" + f)) return "function \"" + n + "\" has its own " + f;
+    }
+  }
+  if (await exists(FUNCTIONS_DIR + "/deno.jsonc")) return "functions/deno.jsonc is not merged (comments)";
+  return null;
+}
+
+/** POSIX-relative path from directory \`from\` to \`to\`. The entry imports the
+ *  functions relatively: an absolute file specifier is refused by the
+ *  runtime's module bundler ("Module not found"), a relative one resolves. */
+function relativePath(from: string, to: string): string {
+  const a = from.split("/").filter(Boolean);
+  const b = to.split("/").filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  const up = a.slice(i).map(() => "..");
+  const rel = [...up, ...b.slice(i)].join("/");
+  return rel.startsWith(".") ? rel : "./" + rel;
+}
+
+function reString(s: string): string {
+  return s.replace(/[.*+?^$()|[\]\\\/{}]/g, "\\$&");
+}
+
+/** Write SHARED_DIR: the entry, the prelude, the std shim and the config. */
+async function writeShared(names: string[]): Promise<string | null> {
+  await Deno.mkdir(SHARED_DIR, { recursive: true });
+
+  // Config: the project's functions/deno.json (its imports are what every
+  // function resolves against) plus the std shim redirections.
+  let cfg: Record<string, unknown> = {};
+  if (await exists(FUNCTIONS_DIR + "/deno.json")) {
     try {
-      await Deno.stat(FUNCTIONS_DIR + "/" + entry.name + "/index.ts");
-      names.push(entry.name);
-    } catch {
-      // not a function directory
+      cfg = JSON.parse(await Deno.readTextFile(FUNCTIONS_DIR + "/deno.json"));
+    } catch (e) {
+      return "functions/deno.json could not be parsed: " + String(e);
     }
+    if (typeof cfg.importMap === "string") return "functions/deno.json names an importMap";
   }
-  // All at once: a project can have dozens of functions, and each boot is
-  // mostly module loading — the isolates come up concurrently.
+  const urls = new Set<string>();
+  await stdServerUrls(FUNCTIONS_DIR, urls);
+  const imports: Record<string, string> = { ...((cfg.imports as Record<string, string>) ?? {}) };
+  for (const u of urls) imports[u] = "./std-http-server.ts";
+  await Deno.writeTextFile(
+    SHARED_DIR + "/deno.json",
+    JSON.stringify({ ...cfg, lock: false, imports }, null, 2),
+  );
+
+  // The registration. Which function is calling comes from the stack: the
+  // first frame under FUNCTIONS_DIR whose directory is a function.
+  const known = JSON.stringify(names);
+  const prelude = [
+    "// spectest-generated. Do not edit.",
+    "const g = globalThis as any;",
+    "g.__spectestHandlers = {};",
+    "const known = new Set(" + known + ");",
+    "const frame = new RegExp(\"" + reString(FUNCTIONS_DIR) + "/([^/]+)/\", \"g\");",
+    "// serve()'s onError is part of the contract: a project maps its thrown",
+    "// errors to responses there, and without it every throw is a bare 500.",
+    "g.__spectestRegister = (handler: unknown, onError?: unknown) => {",
+    "  if (typeof handler !== \"function\") throw new TypeError(\"spectest: serve() without a handler function\");",
+    "  const stack = new Error().stack ?? \"\";",
+    "  let name: string | null = null;",
+    "  for (const m of stack.matchAll(frame)) { if (known.has(m[1])) { name = m[1]; break; } }",
+    "  if (name === null) throw new Error(\"spectest: could not tell which function registered a handler; the call must come from under \" + JSON.stringify(\"" + FUNCTIONS_DIR + "\"));",
+    "  g.__spectestHandlers[name] = { handler, onError: typeof onError === \"function\" ? onError : null };",
+    "};",
+    "g.__spectestRealServe = Deno.serve.bind(Deno);",
+    "const listener = { finished: new Promise<void>(() => {}), addr: { transport: \"tcp\", hostname: \"0.0.0.0\", port: 8000 }, shutdown: async () => {}, ref() {}, unref() {} };",
+    "(Deno as any).serve = (a: any, b: any) => {",
+    "  const h = typeof a === \"function\" ? a : typeof b === \"function\" ? b : a?.handler ?? a?.fetch;",
+    "  const opts = typeof a === \"function\" ? b : a;",
+    "  g.__spectestRegister(h, opts?.onError);",
+    "  return listener;",
+    "};",
+    "",
+  ].join("\n");
+  await Deno.writeTextFile(SHARED_DIR + "/prelude.ts", prelude);
+
+  // std's legacy serve(handler, options): the same registration.
+  await Deno.writeTextFile(
+    SHARED_DIR + "/std-http-server.ts",
+    [
+      "// spectest-generated stand-in for https://deno.land/std/http/server.ts. Do not edit.",
+      "export function serve(handler: unknown, options?: { onError?: unknown }): Promise<void> {",
+      "  (globalThis as any).__spectestRegister(handler, options?.onError);",
+      "  return new Promise(() => {});",
+      "}",
+      "export type ConnInfo = { localAddr: Deno.Addr; remoteAddr: Deno.Addr };",
+      "export type Handler = (request: Request, connInfo: ConnInfo) => Response | Promise<Response>;",
+      "export type ServeInit = Record<string, unknown>;",
+      "",
+    ].join("\n"),
+  );
+
+  // The entry: the prelude first, then every function, then the router. A
+  // function written the declarative way (export default { fetch }) never
+  // calls serve, so its default export is picked up here.
+  const lines = ["// spectest-generated entry of the shared functions isolate. Do not edit.", "import \"./prelude.ts\";"];
+  const fnRel = relativePath(SHARED_DIR, FUNCTIONS_DIR);
+  names.forEach((n, i) => lines.push("import * as f" + i + " from " + JSON.stringify(fnRel + "/" + n + "/index.ts") + ";"));
+  lines.push("const mods: Record<string, any> = {");
+  names.forEach((n, i) => lines.push("  " + JSON.stringify(n) + ": f" + i + ","));
+  lines.push("};");
+  lines.push(
+    "const g = globalThis as any;",
+    "for (const [n, m] of Object.entries(mods)) {",
+    "  const d = m.default;",
+    "  if (!g.__spectestHandlers[n] && d && typeof d.fetch === \"function\") g.__spectestHandlers[n] = { handler: d.fetch.bind(d), onError: null };",
+    "}",
+    "const addr = { transport: \"tcp\", hostname: \"127.0.0.1\", port: 0 };",
+    "g.__spectestRealServe(async (req: Request) => {",
+    "  const name = new URL(req.url).pathname.split(\"/\")[1] ?? \"\";",
+    "  const h = g.__spectestHandlers[name];",
+    "  if (!h) return new Response(JSON.stringify({ msg: \"function \" + name + \" registered no handler\" }), { status: 500, headers: { \"content-type\": \"application/json\" } });",
+    "  try {",
+    "    return await h.handler(req, { remoteAddr: addr, localAddr: addr, completed: Promise.resolve() });",
+    "  } catch (e) {",
+    "    if (h.onError) return await h.onError(e);",
+    "    console.error(e);",
+    "    return new Response(\"Internal Server Error\", { status: 500 });",
+    "  }",
+    "});",
+    "",
+  );
+  await Deno.writeTextFile(SHARED_DIR + "/index.ts", lines.join("\n"));
+  return null;
+}
+
+/** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
+ *  the functions run one isolate each — decided once, with the reason logged. */
+async function sharedWorker(): Promise<any | null> {
+  if (!sharedSpec) {
+    sharedSpec = (async () => {
+      const names = await functionNames();
+      let reason = names.length === 0 ? "no functions" : await sharedBlocker(names);
+      if (reason === null) reason = await writeShared(names);
+      if (reason === null) {
+        try {
+          await createShared();
+        } catch (e) {
+          reason = "the shared isolate failed to boot: " + String(e);
+        }
+      }
+      if (reason !== null) console.warn("spectest: functions run one isolate each — " + reason);
+      return { names, reason };
+    })();
+  }
+  const spec = await sharedSpec;
+  return spec.reason === null ? createShared() : null;
+}
+
+function createShared() {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: SHARED_DIR,
+    // A cap on the one isolate that holds every function, not a reservation.
+    memoryLimitMb: 2048,
+    workerTimeoutMs: WORKER_TIMEOUT_MS,
+    // The supervisor counts CPU time over the worker's LIFETIME (soft limit:
+    // retire, hard limit: terminate and cancel in-flight requests with
+    // "request has been cancelled by supervisor"). One isolate serving every
+    // function for a day of tests spends what 51 short-lived ones never
+    // would, so its budget is the day itself. Per-function isolates keep the
+    // runtime's defaults.
+    cpuTimeSoftLimitMs: WORKER_TIMEOUT_MS,
+    cpuTimeHardLimitMs: WORKER_TIMEOUT_MS,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot the functions now, without calling them: the shared isolate, or —
+ *  where it cannot stand in — every function's own. Loading a function
+ *  runs its module top level, which for a function is its serve()
+ *  registration, no business logic. Called once at environment setup,
+ *  before the warm snapshot, so the isolates are shared, clean pages of the
+ *  snapshot rather than a boot in every test that first touches a function. */
+async function warmAll(): Promise<{ mode: "shared" | "per-function"; warmed: string[]; failed: Record<string, string> }> {
+  const names = await functionNames();
+  if ((await sharedWorker()) !== null) return { mode: "shared", warmed: names, failed: {} };
+  // All at once: each boot is mostly module loading, and the isolates come
+  // up concurrently.
   const results = await Promise.allSettled(names.map((name) => workerFor(name)));
   const warmed: string[] = [];
   const failed: Record<string, string> = {};
@@ -1086,7 +1330,7 @@ async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, str
     if (r.status === "fulfilled") warmed.push(names[i]);
     else failed[names[i]] = String(r.reason);
   });
-  return { warmed: warmed.sort(), failed };
+  return { mode: "per-function", warmed: warmed.sort(), failed };
 }
 
 Deno.serve(async (req: Request) => {
@@ -1111,7 +1355,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await workerFor(name);
+    const worker = (await sharedWorker()) ?? (await workerFor(name));
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -2025,13 +2269,20 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           // fork of it. Warm, the isolates are clean shared pages of the
           // snapshot and a test's diff is what its requests mutate.
           setup: async () => {
+            const t0 = Date.now();
             const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
             if (!res.ok) {
               console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
               return;
             }
-            const { warmed, failed } = (await res.json()) as { warmed: string[]; failed: Record<string, string> };
-            console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"}${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+            const { mode, warmed, failed } = (await res.json()) as {
+              mode: "shared" | "per-function";
+              warmed: string[];
+              failed: Record<string, string>;
+            };
+            const secs = ((Date.now() - t0) / 1000).toFixed(1);
+            const how = mode === "shared" ? "in one isolate" : "one isolate each (see the functions service log for why)";
+            console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"} ${how} in ${secs}s${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
             for (const [name, err] of Object.entries(failed)) {
               console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
             }

package/src/daemon.ts

@@ -100,6 +100,7 @@ import {
 import { encodeRegistry } from "./harness/names-registry.js";
 import {
   InterceptRegistry,
+  parseTarget,
   runChain,
   type Interceptor,
 } from "./harness/intercept.js";
@@ -174,6 +175,7 @@ import {
   startRecording,
   stopRecording,
   truncateUtf8,
+  type StepBlock,
   type TestEvent,
   type OmittedBody,
 } from "./recorder.js";
@@ -2796,16 +2798,22 @@ function ingressClaimsHostname(hostname: string): boolean {
   return false;
 }
 
-/** Record one request an interceptor saw, nested under its `intercept` step. */
+/** Record one request an interceptor saw, nested under its `intercept` step.
+ *
+ * A forced 503 is the step doing exactly what its description says, so it is
+ * **not** marked failed — reddening the outcome the test asked for trains the
+ * reader to ignore the colour. Only a handler that threw is marked, because
+ * that 500 is a bug in the middleware rather than the outage it stands for. */
 function recordInterceptedRequest(
   it: Interceptor,
-  rec: { method: string; path: string; status: number; answeredBy: string },
+  rec: { method: string; path: string; status: number; answeredBy: string; threw?: boolean },
   durationMs: number,
 ): void {
   const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
   if (parentSeq === undefined || !isRecording()) return;
-  const by =
-    rec.answeredBy === "handler"
+  const by = rec.threw
+    ? "the interceptor threw — 500 from spectest, not from your handler"
+    : rec.answeredBy === "handler"
       ? "answered by the interceptor"
       : rec.answeredBy === "modified"
         ? "upstream answer replaced by the interceptor"
@@ -2814,22 +2822,42 @@ function recordInterceptedRequest(
     kind: "intercept-request",
     parentSeq,
     title: `${rec.method} ${rec.path} → ${rec.status}`,
-    status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+    status: rec.threw ? "failed" : "passed",
+    // Method, path and status are already the title; the one thing the row
+    // cannot say for itself is who produced that status.
     blocks: [
-      {
-        type: "kv",
-        rows: [
-          { label: "Host", value: it.hostname },
-          { label: "Request", value: `${rec.method} ${rec.path}` },
-          { label: "Status", value: String(rec.status) },
-          { label: "Answered", value: by },
-        ],
-      },
+      { type: "kv", rows: [{ label: "Answered", value: by, error: rec.threw === true }] },
     ],
     durationMs,
   });
 }
 
+/** The handler's own source, which is what the interceptor actually does.
+ *
+ * Free and impossible to let rot: Bun runs the project's TypeScript
+ * directly, so `toString()` is the text the author wrote. It is the step's
+ * body, under the description — a mechanism the reader can check against
+ * the intent the description claims. A handler long enough to be a wall of
+ * code folds into a disclosure instead of pushing the requests off screen.
+ */
+function handlerBlocks(handler: InterceptHandler): StepBlock[] {
+  let src: string;
+  try {
+    src = String(handler);
+  } catch {
+    return [];
+  }
+  const code: StepBlock = { type: "code", lang: "ts", label: "Handler", code: src };
+  return src.split("\n").length > HANDLER_FOLD_LINES
+    ? [{ type: "details", summary: "Handler", blocks: [code] }]
+    : [code];
+}
+
+/** Past this many lines the handler source is folded away. Chosen so the
+ *  shapes this feature is for — a one-line forced status, a short
+ *  fail-twice-then-pass — always show, and only a real program hides. */
+const HANDLER_FOLD_LINES = 15;
+
 /**
  * Put middleware in front of a hostname the ingress serves — the
  * implementation behind `ctx.intercept`.
@@ -2838,19 +2866,25 @@ function recordInterceptedRequest(
  * the daemon (DNS does not point here), so the interceptor could only be
  * silent — and silence is the failure mode this whole layer is designed
  * against. The message names the two ways to get a route.
+ *
+ * The `description` is required because it is the step's whole title in the
+ * timeline and in the CLI's failure detail: it is what tells a reader why
+ * the UI under test went to its error state. The handler source says how;
+ * only the author can say what it means.
  */
 function registerInterceptor(
-  hostname: string,
-  pathOrHandler: string | InterceptHandler,
-  maybeHandler?: InterceptHandler,
+  target: string,
+  description: string,
+  handler: InterceptHandler,
 ): Interception {
-  const path = typeof pathOrHandler === "string" ? pathOrHandler : undefined;
-  const handler = typeof pathOrHandler === "function" ? pathOrHandler : maybeHandler;
-  if (typeof hostname !== "string" || hostname.length === 0) {
-    throw new Error("ctx.intercept: a hostname is required");
+  const { hostname: host, path } = parseTarget(target);
+  if (typeof description !== "string" || description.trim() === "") {
+    throw new Error(
+      `ctx.intercept(${JSON.stringify(target)}): a description is required — what the ` +
+        `environment now does, as the timeline reads it, e.g. "the sync endpoint returns 503".`,
+    );
   }
-  const host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-  if (!handler) {
+  if (typeof handler !== "function") {
     throw new Error("ctx.intercept: a handler (req, next) => Response is required");
   }
   if (!ingressClaimsHostname(host)) {
@@ -2863,20 +2897,42 @@ function registerInterceptor(
   }
   const resv = reserveEvent();
   const it = INTERCEPTORS.register(host, path, handler);
+  const where = `${host}${it.path === "/" ? "" : it.path}`;
   const seq = recordStep(
     {
       kind: "intercept",
-      title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+      // The description alone. The pill already says INTERCEPT, and the
+      // target is in the panel — a row that repeats both spends its width
+      // on what the reader can already see and none of it on the one thing
+      // only the author knows.
+      title: description.trim(),
       blocks: [
+        ...handlerBlocks(handler),
         {
-          type: "kv",
-          rows: [
-            { label: "Host", value: host },
-            { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+          // The target IS the summary line, so the closed disclosure still
+          // says where the interceptor sits — a generic "Target" label
+          // would spend the one visible line saying nothing.
+          type: "details",
+          summary: where,
+          blocks: [
+            {
+              type: "kv",
+              rows: [
+                {
+                  label: "Matches",
+                  value: it.path === "/" ? "every path on this host" : `${it.path} and below`,
+                },
+                {
+                  label: "Until",
+                  value: it.scope === undefined ? "remove()" : "the end of this test",
+                },
+              ],
+            },
           ],
         },
       ],
-      durationMs: 0,
+      // No duration: this is a marker for the moment the interceptor went
+      // up, and "(0 ms)" reads as a step that did nothing.
     },
     resv,
   );

package/src/harness/intercept.test.ts

@@ -3,6 +3,7 @@ import {
   InterceptRegistry,
   hostnameMatches,
   normalizeMount,
+  parseTarget,
   pathMounts,
   runChain,
   type Interceptor,
@@ -39,6 +40,41 @@ describe("normalizeMount", () => {
   });
 });
 
+describe("parseTarget", () => {
+  test("a bare hostname mounts at the root", () => {
+    expect(parseTarget("app.test")).toEqual({ hostname: "app.test", path: "/" });
+  });
+  test("a path rides the target", () => {
+    expect(parseTarget("app.test/api/sync")).toEqual({
+      hostname: "app.test",
+      path: "/api/sync",
+    });
+    expect(parseTarget("app.test/api/")).toEqual({ hostname: "app.test", path: "/api" });
+    expect(parseTarget("app.test/")).toEqual({ hostname: "app.test", path: "/" });
+  });
+  test("a scheme and case are tolerated", () => {
+    expect(parseTarget("https://App.Test/API")).toEqual({
+      hostname: "app.test",
+      path: "/api",
+    });
+  });
+  test("a wildcard host keeps its pattern", () => {
+    expect(parseTarget("*.example.com/v1")).toEqual({
+      hostname: "*.example.com",
+      path: "/v1",
+    });
+  });
+  test("rejects a target that is only a path, or none at all", () => {
+    expect(() => parseTarget("/api")).toThrow(/names no hostname/);
+    expect(() => parseTarget("")).toThrow(/target hostname is required/);
+    expect(() => parseTarget("   ")).toThrow(/target hostname is required/);
+  });
+  test("rejects a query or fragment", () => {
+    expect(() => parseTarget("app.test/api?x=1")).toThrow(/mount prefix/);
+    expect(() => parseTarget("app.test?x=1")).toThrow(/query or fragment/);
+  });
+});
+
 describe("hostnameMatches", () => {
   test("exact and wildcard", () => {
     expect(hostnameMatches("api.test", "api.test")).toBe(true);

package/src/harness/intercept.ts

@@ -56,6 +56,12 @@ export interface InterceptedRequest {
    *  upstream via `next()` untouched (`upstream`), or the upstream's answer
    *  replaced by the interceptor after `next()` (`modified`). */
   answeredBy: "handler" | "upstream" | "modified";
+  /** The handler threw (or returned something that is not a `Response`), so
+   *  the 500 below is a bug in the test's own middleware rather than the
+   *  outage it was asked to produce. The distinction cannot be recovered
+   *  from the status: a deliberate 500 and a crashed handler are the same
+   *  number, and only this tells the timeline which one to mark as wrong. */
+  threw?: boolean;
 }
 
 export interface Interceptor {
@@ -71,6 +77,39 @@ export interface Interceptor {
   requests: InterceptedRequest[];
 }
 
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export function parseTarget(target: string): { hostname: string; path: string } {
+  if (typeof target !== "string" || target.trim() === "") {
+    throw new Error("intercept: a target hostname is required, e.g. \"app.test\" or \"app.test/api\"");
+  }
+  const bare = target.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+  const slash = bare.indexOf("/");
+  const hostname = slash === -1 ? bare : bare.slice(0, slash);
+  const rest = slash === -1 ? undefined : bare.slice(slash);
+  if (hostname === "") {
+    throw new Error(
+      `intercept: target ${JSON.stringify(target)} names no hostname — write it as "app.test/api", not "/api"`,
+    );
+  }
+  if (hostname.includes("?") || hostname.includes("#")) {
+    throw new Error(
+      `intercept: target ${JSON.stringify(target)} cannot carry a query or fragment`,
+    );
+  }
+  return { hostname, path: normalizeMount(rest) };
+}
+
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export function pathMounts(mount: string, pathname: string): boolean {
@@ -222,6 +261,7 @@ export async function runChain(
       );
       record.answeredBy = "handler";
       record.status = 500;
+      record.threw = true;
       it.calls++;
       it.requests.push(record);
       observe?.(it, record, Date.now() - started);