@specific.dev/spectest 0.62.0 → 0.63.0

package/dist/daemon.js

@@ -42,6 +42,7 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
+import { InterceptRegistry, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
@@ -54,7 +55,7 @@ import { openTerminal } from "./terminal.js";
 import { openMcp } from "./mcp.js";
 import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation } from "./annotate.js";
-import { pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { isRecording, pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
@@ -1993,17 +1994,27 @@ server, byHost, listenerLabel, proto) {
     // to list in Access-Control-Allow-Headers.
     if (isCorsPreflight(req))
         return corsPreflightResponse(req);
-    if (route.kind === "fake") {
-        try {
-            const res = await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
-            return augmentCorsResponse(req, res);
-        }
-        catch (err) {
-            const e = err;
-            return new Response(`spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
+    // The real answer — a fake handled in-process, or the proxied container.
+    const upstream = async (current) => {
+        if (route.kind === "fake") {
+            try {
+                return await route.fake.def.handler(current, route.fake.state, FAKE_CTX);
+            }
+            catch (err) {
+                const e = err;
+                return new Response(`spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
+            }
         }
-    }
-    const res = await proxyToService(req, server, route.service, route.port, listenerLabel, proto);
+        return proxyToService(current, server, route.service, route.port, listenerLabel, proto);
+    };
+    // `ctx.intercept` middleware runs first, in registration order, and reaches
+    // the upstream through `next()`. The CORS headers go on *after* the chain,
+    // so a forced 500 reaches the browser as a 500 and not as a CORS error —
+    // the trap `page.route`-style interception falls into.
+    const chain = INTERCEPTORS.chainFor(host, new URL(req.url).pathname);
+    const res = chain.length === 0
+        ? await upstream(req)
+        : await runChain(chain, req, upstream, recordInterceptedRequest);
     return augmentCorsResponse(req, res);
 }
 /**
@@ -2263,6 +2274,120 @@ async function seedNamesRegistry(opts) {
     }
     await writeRegistry();
 }
+/**
+ * The live interceptors (`ctx.intercept`). Module memory, so they fork with
+ * the environment like the route tables; a test's own are removed when its
+ * case ends (`runOne` opens and closes the scope), so a `dependsOn` child
+ * never inherits a parent's forced outage.
+ */
+const INTERCEPTORS = new InterceptRegistry();
+/** The recorder seq of the `intercept` step each interceptor was registered
+ *  under, so every request it sees can nest below that step. */
+const INTERCEPT_STEP_SEQ = new Map();
+/** What every port's route table together claims — the hostnames a request
+ *  can reach the ingress under at all. */
+function ingressClaimsHostname(hostname) {
+    for (const byHost of INGRESS.routesByPort.values()) {
+        if (matchRoute(byHost, hostname))
+            return true;
+        if (isWildcard(hostname)) {
+            // A wildcard interceptor is fine when any route sits under it.
+            const suffix = wildcardSuffix(hostname);
+            for (const key of byHost.keys()) {
+                if (key === hostname || key.endsWith(suffix))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Record one request an interceptor saw, nested under its `intercept` step. */
+function recordInterceptedRequest(it, rec, durationMs) {
+    const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
+    if (parentSeq === undefined || !isRecording())
+        return;
+    const by = rec.answeredBy === "handler"
+        ? "answered by the interceptor"
+        : rec.answeredBy === "modified"
+            ? "upstream answer replaced by the interceptor"
+            : "passed through to the upstream";
+    recordStep({
+        kind: "intercept-request",
+        parentSeq,
+        title: `${rec.method} ${rec.path} → ${rec.status}`,
+        status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+        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 },
+                ],
+            },
+        ],
+        durationMs,
+    });
+}
+/**
+ * Put middleware in front of a hostname the ingress serves — the
+ * implementation behind `ctx.intercept`.
+ *
+ * Refuses a hostname no route claims: a request for it would never reach
+ * 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.
+ */
+function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
+    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 host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    if (!handler) {
+        throw new Error("ctx.intercept: a handler (req, next) => Response is required");
+    }
+    if (!ingressClaimsHostname(host)) {
+        throw new Error(`ctx.intercept(${JSON.stringify(host)}): no request can reach the ingress under that hostname. ` +
+            `Only traffic that passes through the daemon can be intercepted: give the service a \`tls\`/\`hostnames\` ` +
+            `entry (or \`supabase({ hostname })\`), or target a fake's hostname. A bare service name ` +
+            `(\`http://<service>:<port>\`) is container-to-container traffic and never passes through here.`);
+    }
+    const resv = reserveEvent();
+    const it = INTERCEPTORS.register(host, path, handler);
+    const seq = recordStep({
+        kind: "intercept",
+        title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+        blocks: [
+            {
+                type: "kv",
+                rows: [
+                    { label: "Host", value: host },
+                    { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+                ],
+            },
+        ],
+        durationMs: 0,
+    }, resv);
+    if (seq !== undefined)
+        INTERCEPT_STEP_SEQ.set(it.id, seq);
+    return {
+        hostname: host,
+        path: it.path,
+        get calls() {
+            return wrap(it.calls, seq);
+        },
+        get requests() {
+            return wrap(it.requests.map((r) => ({ ...r })), seq);
+        },
+        remove() {
+            INTERCEPTORS.remove(it.id);
+            INTERCEPT_STEP_SEQ.delete(it.id);
+        },
+    };
+}
 /**
  * Register a hostname at runtime — the implementation behind `ctx.dnsName`.
  * Validates via the same `dnsName` primitive the static path uses, resolves
@@ -3491,6 +3616,7 @@ async function spectestContext(scope = {}) {
         certificate: mintCertificate,
         startService: startRuntimeService,
         stopService: stopRuntimeService,
+        intercept: registerInterceptor,
     };
 }
 /** Handles for a service hook: its dependencies (always up by the time the
@@ -4306,6 +4432,9 @@ async function runOne(testCase) {
     // time — so from here on a service helper's `docker exec` lands on the
     // timeline (and in the cast) exactly like the test's own `ctx.exec`.
     RECORDING_EXEC = recordedExec;
+    // Interceptors this case registers die with it (see harness/intercept.ts
+    // — the post-state snapshot must not carry a forced outage into children).
+    INTERCEPTORS.beginScope(testCase.id);
     const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
     let timer;
     const timedOut = new Promise((_, reject) => {
@@ -4335,6 +4464,7 @@ async function runOne(testCase) {
         if (timer)
             clearTimeout(timer);
         RECORDING_EXEC = undefined;
+        INTERCEPTORS.endScope();
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/harness/intercept.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Request interceptors on the ingress — the mechanism behind `ctx.intercept`.
+ *
+ * An interceptor is middleware in the Hono/Koa sense: it sees a request
+ * that reached the daemon's ingress for a hostname it claims, and either
+ * answers it itself or calls `next()` to let the real upstream (a proxied
+ * service, or a fake) answer. That is what lets a test make its *own*
+ * backend misbehave for one case — force a 500 from an edge function, add
+ * latency, fail twice then pass — without redefining the service.
+ *
+ * ## Why this is a chain and not a replacement handler
+ *
+ * A replacement handler covers "answer instead of the upstream" and nothing
+ * else. Every other shape a test needs — observe and count, mutate a real
+ * response, delay it, fail N times — needs the real answer in hand, which is
+ * what `next()` gives. Registration order is the chain order, as in Hono
+ * or Koa: the first interceptor sees the request first, and each one
+ * decides whether the next runs.
+ *
+ * ## Scope
+ *
+ * The registry is module memory in the harness process, so like fake state
+ * and the route tables it forks with the environment. That alone would make
+ * a parent's interceptor leak into every `dependsOn` child through the
+ * post-state snapshot, so a test's interceptors are **scoped to the case**:
+ * {@link InterceptRegistry.beginScope} opens the case, and
+ * {@link InterceptRegistry.endScope} removes everything registered inside it
+ * — the harness calls both around the test body. An interceptor registered
+ * outside a case (`eval`, project `setup`) has no scope and lasts until
+ * `remove()`.
+ *
+ * Pure module: no Bun, no listener, no recorder — so it is testable with
+ * plain `Request`/`Response` objects.
+ */
+/** The continuation an interceptor calls to reach the upstream (or the next
+ *  interceptor in the chain). Passing a `Request` replaces the one that goes
+ *  on — the way to forward a modified request, since a fetch `Request` is
+ *  immutable. */
+export type InterceptNext = (req?: Request) => Promise<Response>;
+export type InterceptHandler = (req: Request, next: InterceptNext) => Response | Promise<Response>;
+/** One observed request, as the handle reports it. */
+export interface InterceptedRequest {
+    method: string;
+    /** Path + query, as requested. */
+    path: string;
+    status: number;
+    /** Who produced the response: the interceptor itself (`handler`), the
+     *  upstream via `next()` untouched (`upstream`), or the upstream's answer
+     *  replaced by the interceptor after `next()` (`modified`). */
+    answeredBy: "handler" | "upstream" | "modified";
+}
+export interface Interceptor {
+    id: number;
+    hostname: string;
+    /** Mount path, like `app.use(path, fn)`: matches the path itself and
+     *  everything below it. `"/"` (the default) matches every path. */
+    path: string;
+    handler: InterceptHandler;
+    /** The case this interceptor belongs to, if registered inside one. */
+    scope?: string;
+    calls: number;
+    requests: InterceptedRequest[];
+}
+/** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
+ *  never `/apix`. `/` matches everything. Query strings do not take part. */
+export declare function pathMounts(mount: string, pathname: string): boolean;
+/** Exact hostname, or a `*.suffix` pattern that covers the host at any
+ *  depth — the same rule the route tables use for a wildcard route. */
+export declare function hostnameMatches(pattern: string, host: string): boolean;
+/** Normalise a mount path: must start with `/`, no query, no trailing
+ *  slash (except the root). */
+export declare function normalizeMount(path: string | undefined): string;
+export declare class InterceptRegistry {
+    private list;
+    private nextId;
+    private scope;
+    /** Every interceptor registered from now on belongs to `scope`, until
+     *  {@link endScope}. */
+    beginScope(scope: string): void;
+    /** Close the current scope and remove every interceptor registered in it.
+     *  Returns how many were removed. */
+    endScope(): number;
+    register(hostname: string, path: string | undefined, handler: InterceptHandler): Interceptor;
+    /** Idempotent: removing twice, or after the scope ended, is a no-op. */
+    remove(id: number): void;
+    /** The interceptors that apply to a request, in registration order. */
+    chainFor(host: string, pathname: string): Interceptor[];
+    size(): number;
+    clear(): void;
+}
+/** What `runChain` reports about one interceptor's part in a request. */
+export interface ChainObserver {
+    (interceptor: Interceptor, record: InterceptedRequest, durationMs: number): void;
+}
+/**
+ * Run `req` through `chain`, ending at `upstream`.
+ *
+ * Each interceptor's `next` runs the rest of the chain; an interceptor
+ * that returns without calling `next` answers the request itself. A thrown
+ * error becomes a 500 naming the interceptor — the same rule a fake handler
+ * gets — so a bug in test code is a visible failure of that request, not a
+ * hung browser.
+ *
+ * `observe` is called once per interceptor that saw the request, after it
+ * returned, with what it did.
+ */
+export declare function runChain(chain: readonly Interceptor[], req: Request, upstream: (req: Request) => Promise<Response>, observe?: ChainObserver): Promise<Response>;

package/dist/harness/intercept.js

@@ -0,0 +1,175 @@
+/**
+ * Request interceptors on the ingress — the mechanism behind `ctx.intercept`.
+ *
+ * An interceptor is middleware in the Hono/Koa sense: it sees a request
+ * that reached the daemon's ingress for a hostname it claims, and either
+ * answers it itself or calls `next()` to let the real upstream (a proxied
+ * service, or a fake) answer. That is what lets a test make its *own*
+ * backend misbehave for one case — force a 500 from an edge function, add
+ * latency, fail twice then pass — without redefining the service.
+ *
+ * ## Why this is a chain and not a replacement handler
+ *
+ * A replacement handler covers "answer instead of the upstream" and nothing
+ * else. Every other shape a test needs — observe and count, mutate a real
+ * response, delay it, fail N times — needs the real answer in hand, which is
+ * what `next()` gives. Registration order is the chain order, as in Hono
+ * or Koa: the first interceptor sees the request first, and each one
+ * decides whether the next runs.
+ *
+ * ## Scope
+ *
+ * The registry is module memory in the harness process, so like fake state
+ * and the route tables it forks with the environment. That alone would make
+ * a parent's interceptor leak into every `dependsOn` child through the
+ * post-state snapshot, so a test's interceptors are **scoped to the case**:
+ * {@link InterceptRegistry.beginScope} opens the case, and
+ * {@link InterceptRegistry.endScope} removes everything registered inside it
+ * — the harness calls both around the test body. An interceptor registered
+ * outside a case (`eval`, project `setup`) has no scope and lasts until
+ * `remove()`.
+ *
+ * Pure module: no Bun, no listener, no recorder — so it is testable with
+ * plain `Request`/`Response` objects.
+ */
+import { isWildcard, wildcardSuffix } from "./hostmatch";
+/** 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, pathname) {
+    if (mount === "/" || mount === "")
+        return true;
+    const m = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+    return pathname === m || pathname.startsWith(`${m}/`);
+}
+/** Exact hostname, or a `*.suffix` pattern that covers the host at any
+ *  depth — the same rule the route tables use for a wildcard route. */
+export function hostnameMatches(pattern, host) {
+    if (pattern === host)
+        return true;
+    if (!isWildcard(pattern))
+        return false;
+    return host.endsWith(wildcardSuffix(pattern));
+}
+/** Normalise a mount path: must start with `/`, no query, no trailing
+ *  slash (except the root). */
+export function normalizeMount(path) {
+    if (path === undefined || path === "" || path === "/")
+        return "/";
+    if (!path.startsWith("/")) {
+        throw new Error(`intercept: path ${JSON.stringify(path)} must start with "/"`);
+    }
+    if (path.includes("?") || path.includes("#")) {
+        throw new Error(`intercept: path ${JSON.stringify(path)} is a mount prefix and cannot carry a query or fragment`);
+    }
+    return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+export class InterceptRegistry {
+    list = [];
+    nextId = 1;
+    scope;
+    /** Every interceptor registered from now on belongs to `scope`, until
+     *  {@link endScope}. */
+    beginScope(scope) {
+        this.scope = scope;
+    }
+    /** Close the current scope and remove every interceptor registered in it.
+     *  Returns how many were removed. */
+    endScope() {
+        const scope = this.scope;
+        this.scope = undefined;
+        if (scope === undefined)
+            return 0;
+        const before = this.list.length;
+        this.list = this.list.filter((i) => i.scope !== scope);
+        return before - this.list.length;
+    }
+    register(hostname, path, handler) {
+        if (typeof handler !== "function") {
+            throw new Error("intercept: the handler must be a function (req, next) => Response");
+        }
+        const it = {
+            id: this.nextId++,
+            hostname: hostname.toLowerCase(),
+            path: normalizeMount(path),
+            handler,
+            scope: this.scope,
+            calls: 0,
+            requests: [],
+        };
+        this.list.push(it);
+        return it;
+    }
+    /** Idempotent: removing twice, or after the scope ended, is a no-op. */
+    remove(id) {
+        this.list = this.list.filter((i) => i.id !== id);
+    }
+    /** The interceptors that apply to a request, in registration order. */
+    chainFor(host, pathname) {
+        return this.list.filter((i) => hostnameMatches(i.hostname, host) && pathMounts(i.path, pathname));
+    }
+    size() {
+        return this.list.length;
+    }
+    clear() {
+        this.list = [];
+        this.scope = undefined;
+    }
+}
+/**
+ * Run `req` through `chain`, ending at `upstream`.
+ *
+ * Each interceptor's `next` runs the rest of the chain; an interceptor
+ * that returns without calling `next` answers the request itself. A thrown
+ * error becomes a 500 naming the interceptor — the same rule a fake handler
+ * gets — so a bug in test code is a visible failure of that request, not a
+ * hung browser.
+ *
+ * `observe` is called once per interceptor that saw the request, after it
+ * returned, with what it did.
+ */
+export async function runChain(chain, req, upstream, observe) {
+    const run = async (index, current) => {
+        const it = chain[index];
+        if (!it)
+            return upstream(current);
+        let calledNext = false;
+        let fromUpstream;
+        const next = async (replacement) => {
+            calledNext = true;
+            fromUpstream = await run(index + 1, replacement ?? current);
+            return fromUpstream;
+        };
+        const started = Date.now();
+        const url = new URL(current.url);
+        const record = {
+            method: current.method,
+            path: `${url.pathname}${url.search}`,
+            status: 0,
+            answeredBy: "handler",
+        };
+        let res;
+        try {
+            res = await it.handler(current, next);
+            if (!(res instanceof Response)) {
+                throw new Error(`interceptor for ${it.hostname}${it.path === "/" ? "" : it.path} returned ${res === undefined ? "undefined" : typeof res} — return a Response, or the result of next()`);
+            }
+        }
+        catch (err) {
+            const e = err;
+            res = new Response(`spectest-daemon: interceptor for ${it.hostname} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
+            record.answeredBy = "handler";
+            record.status = 500;
+            it.calls++;
+            it.requests.push(record);
+            observe?.(it, record, Date.now() - started);
+            return res;
+        }
+        record.status = res.status;
+        record.answeredBy = !calledNext ? "handler" : res === fromUpstream ? "upstream" : "modified";
+        it.calls++;
+        it.requests.push(record);
+        observe?.(it, record, Date.now() - started);
+        return res;
+    };
+    return run(0, req);
+}

package/dist/index.d.ts

@@ -25,6 +25,27 @@ import { type ServiceCoverage } from "./coverage.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
 export type { CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, LoweredIngress, } from "./ingress.js";
 import type { DnsTarget } from "./ingress.js";
+import type { InterceptHandler, InterceptNext, InterceptedRequest } from "./harness/intercept.js";
+export type { InterceptHandler, InterceptNext, InterceptedRequest };
+/**
+ * The handle `ctx.intercept` returns: what the interceptor has seen so far,
+ * and the way to take it down early. A test's interceptors are removed
+ * when the test ends whether or not `remove()` was called.
+ */
+export interface Interception {
+    hostname: string;
+    /** The normalised mount path (`"/"` when none was given). */
+    path: string;
+    /** How many requests the interceptor has seen. Provenance-wrapped, so an
+     *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
+     *  the raw number. */
+    readonly calls: Wrapped<number>;
+    /** Every request it saw, in order, with the status it got and who
+     *  answered it (`handler` | `upstream` | `modified`). */
+    readonly requests: Wrapped<InterceptedRequest[]>;
+    /** Stop intercepting now. Idempotent. */
+    remove(): void;
+}
 export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
     /** Human-friendly name for the environment, e.g. "my-app". */
     name: string;
@@ -355,6 +376,40 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * ```
      */
     dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /**
+     * Put middleware in front of a hostname the ingress serves — the way to
+     * make your **own** backend misbehave for one test: force a 500 from an
+     * API route, add latency, fail twice then pass, or just count calls.
+     *
+     * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
+     * response (a proxied service, or a fake). Return a `Response` to answer
+     * yourself, `next()` to pass through, or change what `next()` returned.
+     * An optional mount `path` limits it to that path and everything below
+     * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
+     * registration order.
+     *
+     * Only traffic that reaches the daemon can be intercepted: the browser,
+     * `ctx.fetch`, and any container that calls the hostname — so the service
+     * needs a `tls`/`hostnames` entry (or `supabase({ hostname })`), or the
+     * target is a fake. A bare `http://<service>:<port>` call between
+     * containers never passes through here, and a hostname nothing claims is
+     * refused at registration.
+     *
+     * From a test, the interceptor lasts until the test ends (a `dependsOn`
+     * child never inherits it); from `eval` or `setup` it lasts until
+     * `remove()`. Every request it sees is recorded under the intercept step.
+     *
+     * ```ts
+     * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
+     *   new Response("boom", { status: 500 }));
+     * await page.getByRole("button", { name: "Sync" }).click();
+     * await expect(page.getByText("Retry")).toBeVisible();
+     * expect(outage.calls).toBe(1);
+     * outage.remove();                           // the retry now reaches the real function
+     * ```
+     */
+    intercept(hostname: string, handler: InterceptHandler): Interception;
+    intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
     /**
      * Mint a leaf certificate from the in-VM root CA and return the PEMs.
      *

package/package.json

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

package/src/daemon.ts

@@ -98,6 +98,11 @@ import {
   parseContentLength,
 } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
+import {
+  InterceptRegistry,
+  runChain,
+  type Interceptor,
+} from "./harness/intercept.js";
 import {
   HOP_BY_HOP_HEADERS,
   augmentCorsResponse,
@@ -151,6 +156,7 @@ import { openMcp } from "./mcp.js";
 import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
+  isRecording,
   pauseRecording,
   recordEmail,
   recordEnv,
@@ -191,6 +197,9 @@ import type {
   FakeContext,
   FakeDefinition,
   FileMount,
+  InterceptHandler,
+  Interception,
+  InterceptedRequest,
   Project,
   ProjectSetupContext,
   ReadyCheck,
@@ -2449,26 +2458,30 @@ async function dispatchIngress(
   // Cache-Control, Pragma, … — isn't rejected by whatever the upstream happens
   // to list in Access-Control-Allow-Headers.
   if (isCorsPreflight(req)) return corsPreflightResponse(req);
-  if (route.kind === "fake") {
-    try {
-      const res = await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
-      return augmentCorsResponse(req, res);
-    } catch (err) {
-      const e = err as Error;
-      return new Response(
-        `spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`,
-        { status: 500, headers: { "content-type": "text/plain" } },
-      );
+  // The real answer — a fake handled in-process, or the proxied container.
+  const upstream = async (current: Request): Promise<Response> => {
+    if (route.kind === "fake") {
+      try {
+        return await route.fake.def.handler(current, route.fake.state, FAKE_CTX);
+      } catch (err) {
+        const e = err as Error;
+        return new Response(
+          `spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`,
+          { status: 500, headers: { "content-type": "text/plain" } },
+        );
+      }
     }
-  }
-  const res = await proxyToService(
-    req,
-    server,
-    route.service,
-    route.port,
-    listenerLabel,
-    proto,
-  );
+    return proxyToService(current, server, route.service, route.port, listenerLabel, proto);
+  };
+  // `ctx.intercept` middleware runs first, in registration order, and reaches
+  // the upstream through `next()`. The CORS headers go on *after* the chain,
+  // so a forced 500 reaches the browser as a 500 and not as a CORS error —
+  // the trap `page.route`-style interception falls into.
+  const chain = INTERCEPTORS.chainFor(host, new URL(req.url).pathname);
+  const res =
+    chain.length === 0
+      ? await upstream(req)
+      : await runChain(chain, req, upstream, recordInterceptedRequest);
   return augmentCorsResponse(req, res);
 }
 
@@ -2755,6 +2768,137 @@ async function seedNamesRegistry(opts: { servicesUp: boolean }): Promise<void> {
   await writeRegistry();
 }
 
+/**
+ * The live interceptors (`ctx.intercept`). Module memory, so they fork with
+ * the environment like the route tables; a test's own are removed when its
+ * case ends (`runOne` opens and closes the scope), so a `dependsOn` child
+ * never inherits a parent's forced outage.
+ */
+const INTERCEPTORS = new InterceptRegistry();
+
+/** The recorder seq of the `intercept` step each interceptor was registered
+ *  under, so every request it sees can nest below that step. */
+const INTERCEPT_STEP_SEQ = new Map<number, number>();
+
+/** What every port's route table together claims — the hostnames a request
+ *  can reach the ingress under at all. */
+function ingressClaimsHostname(hostname: string): boolean {
+  for (const byHost of INGRESS.routesByPort.values()) {
+    if (matchRoute(byHost, hostname)) return true;
+    if (isWildcard(hostname)) {
+      // A wildcard interceptor is fine when any route sits under it.
+      const suffix = wildcardSuffix(hostname);
+      for (const key of byHost.keys()) {
+        if (key === hostname || key.endsWith(suffix)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** Record one request an interceptor saw, nested under its `intercept` step. */
+function recordInterceptedRequest(
+  it: Interceptor,
+  rec: { method: string; path: string; status: number; answeredBy: string },
+  durationMs: number,
+): void {
+  const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
+  if (parentSeq === undefined || !isRecording()) return;
+  const by =
+    rec.answeredBy === "handler"
+      ? "answered by the interceptor"
+      : rec.answeredBy === "modified"
+        ? "upstream answer replaced by the interceptor"
+        : "passed through to the upstream";
+  recordStep({
+    kind: "intercept-request",
+    parentSeq,
+    title: `${rec.method} ${rec.path} → ${rec.status}`,
+    status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+    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 },
+        ],
+      },
+    ],
+    durationMs,
+  });
+}
+
+/**
+ * Put middleware in front of a hostname the ingress serves — the
+ * implementation behind `ctx.intercept`.
+ *
+ * Refuses a hostname no route claims: a request for it would never reach
+ * 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.
+ */
+function registerInterceptor(
+  hostname: string,
+  pathOrHandler: string | InterceptHandler,
+  maybeHandler?: 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 host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+  if (!handler) {
+    throw new Error("ctx.intercept: a handler (req, next) => Response is required");
+  }
+  if (!ingressClaimsHostname(host)) {
+    throw new Error(
+      `ctx.intercept(${JSON.stringify(host)}): no request can reach the ingress under that hostname. ` +
+        `Only traffic that passes through the daemon can be intercepted: give the service a \`tls\`/\`hostnames\` ` +
+        `entry (or \`supabase({ hostname })\`), or target a fake's hostname. A bare service name ` +
+        `(\`http://<service>:<port>\`) is container-to-container traffic and never passes through here.`,
+    );
+  }
+  const resv = reserveEvent();
+  const it = INTERCEPTORS.register(host, path, handler);
+  const seq = recordStep(
+    {
+      kind: "intercept",
+      title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+      blocks: [
+        {
+          type: "kv",
+          rows: [
+            { label: "Host", value: host },
+            { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+          ],
+        },
+      ],
+      durationMs: 0,
+    },
+    resv,
+  );
+  if (seq !== undefined) INTERCEPT_STEP_SEQ.set(it.id, seq);
+  return {
+    hostname: host,
+    path: it.path,
+    get calls(): Wrapped<number> {
+      return wrap(it.calls, seq) as unknown as Wrapped<number>;
+    },
+    get requests(): Wrapped<InterceptedRequest[]> {
+      return wrap(it.requests.map((r) => ({ ...r })), seq) as unknown as Wrapped<
+        InterceptedRequest[]
+      >;
+    },
+    remove(): void {
+      INTERCEPTORS.remove(it.id);
+      INTERCEPT_STEP_SEQ.delete(it.id);
+    },
+  };
+}
+
 /**
  * Register a hostname at runtime — the implementation behind `ctx.dnsName`.
  * Validates via the same `dnsName` primitive the static path uses, resolves
@@ -4303,6 +4447,7 @@ async function spectestContext(scope: ContextScope = {}): Promise<SpectestContex
     certificate: mintCertificate,
     startService: startRuntimeService,
     stopService: stopRuntimeService,
+    intercept: registerInterceptor as SpectestContext["intercept"],
   };
 }
 
@@ -5253,6 +5398,9 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // time — so from here on a service helper's `docker exec` lands on the
   // timeline (and in the cast) exactly like the test's own `ctx.exec`.
   RECORDING_EXEC = recordedExec;
+  // Interceptors this case registers die with it (see harness/intercept.ts
+  // — the post-state snapshot must not carry a forced outage into children).
+  INTERCEPTORS.beginScope(testCase.id);
 
   const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
   let timer: NodeJS.Timeout | undefined;
@@ -5284,6 +5432,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   } finally {
     if (timer) clearTimeout(timer);
     RECORDING_EXEC = undefined;
+    INTERCEPTORS.endScope();
     restoreFetch();
     restoreConsole();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/harness/intercept.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import {
+  InterceptRegistry,
+  hostnameMatches,
+  normalizeMount,
+  pathMounts,
+  runChain,
+  type Interceptor,
+} from "./intercept";
+
+const upstream = async (_req: Request) => new Response("real", { status: 200 });
+
+function req(path = "/", init?: RequestInit): Request {
+  return new Request(`https://api.test${path}`, init);
+}
+
+describe("pathMounts", () => {
+  test("root matches everything", () => {
+    expect(pathMounts("/", "/")).toBe(true);
+    expect(pathMounts("/", "/a/b")).toBe(true);
+  });
+  test("a mount matches itself and below, on a segment boundary", () => {
+    expect(pathMounts("/api", "/api")).toBe(true);
+    expect(pathMounts("/api", "/api/")).toBe(true);
+    expect(pathMounts("/api", "/api/x")).toBe(true);
+    expect(pathMounts("/api", "/apix")).toBe(false);
+    expect(pathMounts("/api", "/")).toBe(false);
+  });
+});
+
+describe("normalizeMount", () => {
+  test("defaults and trims", () => {
+    expect(normalizeMount(undefined)).toBe("/");
+    expect(normalizeMount("/api/")).toBe("/api");
+  });
+  test("rejects a relative path or a query", () => {
+    expect(() => normalizeMount("api")).toThrow(/must start with/);
+    expect(() => normalizeMount("/api?x=1")).toThrow(/mount prefix/);
+  });
+});
+
+describe("hostnameMatches", () => {
+  test("exact and wildcard", () => {
+    expect(hostnameMatches("api.test", "api.test")).toBe(true);
+    expect(hostnameMatches("api.test", "www.api.test")).toBe(false);
+    expect(hostnameMatches("*.api.test", "www.api.test")).toBe(true);
+    expect(hostnameMatches("*.api.test", "a.b.api.test")).toBe(true);
+    expect(hostnameMatches("*.api.test", "api.test")).toBe(false);
+  });
+});
+
+describe("runChain", () => {
+  test("no interceptors reaches the upstream", async () => {
+    const res = await runChain([], req(), upstream);
+    expect(await res.text()).toBe("real");
+  });
+
+  test("a handler that answers stops the chain", async () => {
+    const reg = new InterceptRegistry();
+    reg.register("api.test", undefined, () => new Response("boom", { status: 500 }));
+    let upstreamHit = 0;
+    const res = await runChain(reg.chainFor("api.test", "/x"), req("/x"), async (r) => {
+      upstreamHit++;
+      return upstream(r);
+    });
+    expect(res.status).toBe(500);
+    expect(upstreamHit).toBe(0);
+    const it = reg.chainFor("api.test", "/x")[0]!;
+    expect(it.calls).toBe(1);
+    expect(it.requests[0]).toEqual({ method: "GET", path: "/x", status: 500, answeredBy: "handler" });
+  });
+
+  test("next() reaches the upstream and reports it", async () => {
+    const reg = new InterceptRegistry();
+    const it = reg.register("api.test", undefined, (_r, next) => next());
+    const res = await runChain([it], req("/x?y=1"), upstream);
+    expect(res.status).toBe(200);
+    expect(it.requests[0]).toEqual({ method: "GET", path: "/x?y=1", status: 200, answeredBy: "upstream" });
+  });
+
+  test("a replaced upstream answer reports modified", async () => {
+    const it: Interceptor = new InterceptRegistry().register("api.test", undefined, async (_r, next) => {
+      const real = await next();
+      return new Response(await real.text(), { status: 503 });
+    });
+    const res = await runChain([it], req(), upstream);
+    expect(res.status).toBe(503);
+    expect(it.requests[0]!.answeredBy).toBe("modified");
+  });
+
+  test("next(request) forwards the replacement", async () => {
+    const it = new InterceptRegistry().register("api.test", undefined, (r, next) =>
+      next(new Request(r.url, { method: "POST", headers: { "x-added": "1" } })),
+    );
+    let seen: Request | undefined;
+    await runChain([it], req(), async (r) => {
+      seen = r;
+      return upstream(r);
+    });
+    expect(seen!.method).toBe("POST");
+    expect(seen!.headers.get("x-added")).toBe("1");
+  });
+
+  test("chains run in registration order, each deciding on the next", async () => {
+    const reg = new InterceptRegistry();
+    const order: string[] = [];
+    reg.register("api.test", undefined, (_r, next) => {
+      order.push("first");
+      return next();
+    });
+    reg.register("api.test", "/api", () => {
+      order.push("second");
+      return new Response("second", { status: 418 });
+    });
+    reg.register("api.test", undefined, () => {
+      order.push("third");
+      return new Response("third");
+    });
+    const res = await runChain(reg.chainFor("api.test", "/api/x"), req("/api/x"), upstream);
+    expect(res.status).toBe(418);
+    expect(order).toEqual(["first", "second"]);
+    // A path outside the second mount skips it.
+    order.length = 0;
+    const res2 = await runChain(reg.chainFor("api.test", "/other"), req("/other"), upstream);
+    expect(await res2.text()).toBe("third");
+    expect(order).toEqual(["first", "third"]);
+  });
+
+  test("a throwing handler becomes a 500 naming the host", async () => {
+    const it = new InterceptRegistry().register("api.test", undefined, () => {
+      throw new Error("kaput");
+    });
+    const res = await runChain([it], req(), upstream);
+    expect(res.status).toBe(500);
+    expect(await res.text()).toContain("kaput");
+    expect(it.requests[0]!.answeredBy).toBe("handler");
+  });
+
+  test("a handler that returns nothing is a 500, not a hang", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const it = new InterceptRegistry().register("api.test", undefined, (() => undefined) as any);
+    const res = await runChain([it], req(), upstream);
+    expect(res.status).toBe(500);
+    expect(await res.text()).toContain("returned undefined");
+  });
+
+  test("the observer sees every interceptor that ran", async () => {
+    const reg = new InterceptRegistry();
+    reg.register("api.test", undefined, (_r, next) => next());
+    reg.register("api.test", undefined, () => new Response("x", { status: 404 }));
+    const seen: string[] = [];
+    await runChain(reg.chainFor("api.test", "/"), req(), upstream, (it, rec) => {
+      seen.push(`${it.id}:${rec.status}:${rec.answeredBy}`);
+    });
+    // Inner finishes first (its observer fires as the stack unwinds).
+    expect(seen).toEqual(["2:404:handler", "1:404:upstream"]);
+  });
+});
+
+describe("InterceptRegistry scopes", () => {
+  test("endScope removes what the scope registered and nothing else", () => {
+    const reg = new InterceptRegistry();
+    const global = reg.register("api.test", undefined, (_r, n) => n());
+    reg.beginScope("case-1");
+    reg.register("api.test", "/a", (_r, n) => n());
+    reg.register("api.test", "/b", (_r, n) => n());
+    expect(reg.size()).toBe(3);
+    expect(reg.endScope()).toBe(2);
+    expect(reg.size()).toBe(1);
+    expect(reg.chainFor("api.test", "/a")[0]!.id).toBe(global.id);
+    // Closing again is a no-op.
+    expect(reg.endScope()).toBe(0);
+  });
+
+  test("remove is idempotent", () => {
+    const reg = new InterceptRegistry();
+    const it = reg.register("api.test", undefined, (_r, n) => n());
+    reg.remove(it.id);
+    reg.remove(it.id);
+    expect(reg.size()).toBe(0);
+  });
+});

package/src/harness/intercept.ts

@@ -0,0 +1,238 @@
+/**
+ * Request interceptors on the ingress — the mechanism behind `ctx.intercept`.
+ *
+ * An interceptor is middleware in the Hono/Koa sense: it sees a request
+ * that reached the daemon's ingress for a hostname it claims, and either
+ * answers it itself or calls `next()` to let the real upstream (a proxied
+ * service, or a fake) answer. That is what lets a test make its *own*
+ * backend misbehave for one case — force a 500 from an edge function, add
+ * latency, fail twice then pass — without redefining the service.
+ *
+ * ## Why this is a chain and not a replacement handler
+ *
+ * A replacement handler covers "answer instead of the upstream" and nothing
+ * else. Every other shape a test needs — observe and count, mutate a real
+ * response, delay it, fail N times — needs the real answer in hand, which is
+ * what `next()` gives. Registration order is the chain order, as in Hono
+ * or Koa: the first interceptor sees the request first, and each one
+ * decides whether the next runs.
+ *
+ * ## Scope
+ *
+ * The registry is module memory in the harness process, so like fake state
+ * and the route tables it forks with the environment. That alone would make
+ * a parent's interceptor leak into every `dependsOn` child through the
+ * post-state snapshot, so a test's interceptors are **scoped to the case**:
+ * {@link InterceptRegistry.beginScope} opens the case, and
+ * {@link InterceptRegistry.endScope} removes everything registered inside it
+ * — the harness calls both around the test body. An interceptor registered
+ * outside a case (`eval`, project `setup`) has no scope and lasts until
+ * `remove()`.
+ *
+ * Pure module: no Bun, no listener, no recorder — so it is testable with
+ * plain `Request`/`Response` objects.
+ */
+
+import { isWildcard, wildcardSuffix } from "./hostmatch";
+
+/** The continuation an interceptor calls to reach the upstream (or the next
+ *  interceptor in the chain). Passing a `Request` replaces the one that goes
+ *  on — the way to forward a modified request, since a fetch `Request` is
+ *  immutable. */
+export type InterceptNext = (req?: Request) => Promise<Response>;
+
+export type InterceptHandler = (
+  req: Request,
+  next: InterceptNext,
+) => Response | Promise<Response>;
+
+/** One observed request, as the handle reports it. */
+export interface InterceptedRequest {
+  method: string;
+  /** Path + query, as requested. */
+  path: string;
+  status: number;
+  /** Who produced the response: the interceptor itself (`handler`), the
+   *  upstream via `next()` untouched (`upstream`), or the upstream's answer
+   *  replaced by the interceptor after `next()` (`modified`). */
+  answeredBy: "handler" | "upstream" | "modified";
+}
+
+export interface Interceptor {
+  id: number;
+  hostname: string;
+  /** Mount path, like `app.use(path, fn)`: matches the path itself and
+   *  everything below it. `"/"` (the default) matches every path. */
+  path: string;
+  handler: InterceptHandler;
+  /** The case this interceptor belongs to, if registered inside one. */
+  scope?: string;
+  calls: number;
+  requests: InterceptedRequest[];
+}
+
+/** 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 {
+  if (mount === "/" || mount === "") return true;
+  const m = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  return pathname === m || pathname.startsWith(`${m}/`);
+}
+
+/** Exact hostname, or a `*.suffix` pattern that covers the host at any
+ *  depth — the same rule the route tables use for a wildcard route. */
+export function hostnameMatches(pattern: string, host: string): boolean {
+  if (pattern === host) return true;
+  if (!isWildcard(pattern)) return false;
+  return host.endsWith(wildcardSuffix(pattern));
+}
+
+/** Normalise a mount path: must start with `/`, no query, no trailing
+ *  slash (except the root). */
+export function normalizeMount(path: string | undefined): string {
+  if (path === undefined || path === "" || path === "/") return "/";
+  if (!path.startsWith("/")) {
+    throw new Error(`intercept: path ${JSON.stringify(path)} must start with "/"`);
+  }
+  if (path.includes("?") || path.includes("#")) {
+    throw new Error(
+      `intercept: path ${JSON.stringify(path)} is a mount prefix and cannot carry a query or fragment`,
+    );
+  }
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+
+export class InterceptRegistry {
+  private list: Interceptor[] = [];
+  private nextId = 1;
+  private scope: string | undefined;
+
+  /** Every interceptor registered from now on belongs to `scope`, until
+   *  {@link endScope}. */
+  beginScope(scope: string): void {
+    this.scope = scope;
+  }
+
+  /** Close the current scope and remove every interceptor registered in it.
+   *  Returns how many were removed. */
+  endScope(): number {
+    const scope = this.scope;
+    this.scope = undefined;
+    if (scope === undefined) return 0;
+    const before = this.list.length;
+    this.list = this.list.filter((i) => i.scope !== scope);
+    return before - this.list.length;
+  }
+
+  register(hostname: string, path: string | undefined, handler: InterceptHandler): Interceptor {
+    if (typeof handler !== "function") {
+      throw new Error("intercept: the handler must be a function (req, next) => Response");
+    }
+    const it: Interceptor = {
+      id: this.nextId++,
+      hostname: hostname.toLowerCase(),
+      path: normalizeMount(path),
+      handler,
+      scope: this.scope,
+      calls: 0,
+      requests: [],
+    };
+    this.list.push(it);
+    return it;
+  }
+
+  /** Idempotent: removing twice, or after the scope ended, is a no-op. */
+  remove(id: number): void {
+    this.list = this.list.filter((i) => i.id !== id);
+  }
+
+  /** The interceptors that apply to a request, in registration order. */
+  chainFor(host: string, pathname: string): Interceptor[] {
+    return this.list.filter(
+      (i) => hostnameMatches(i.hostname, host) && pathMounts(i.path, pathname),
+    );
+  }
+
+  size(): number {
+    return this.list.length;
+  }
+
+  clear(): void {
+    this.list = [];
+    this.scope = undefined;
+  }
+}
+
+/** What `runChain` reports about one interceptor's part in a request. */
+export interface ChainObserver {
+  (interceptor: Interceptor, record: InterceptedRequest, durationMs: number): void;
+}
+
+/**
+ * Run `req` through `chain`, ending at `upstream`.
+ *
+ * Each interceptor's `next` runs the rest of the chain; an interceptor
+ * that returns without calling `next` answers the request itself. A thrown
+ * error becomes a 500 naming the interceptor — the same rule a fake handler
+ * gets — so a bug in test code is a visible failure of that request, not a
+ * hung browser.
+ *
+ * `observe` is called once per interceptor that saw the request, after it
+ * returned, with what it did.
+ */
+export async function runChain(
+  chain: readonly Interceptor[],
+  req: Request,
+  upstream: (req: Request) => Promise<Response>,
+  observe?: ChainObserver,
+): Promise<Response> {
+  const run = async (index: number, current: Request): Promise<Response> => {
+    const it = chain[index];
+    if (!it) return upstream(current);
+    let calledNext = false;
+    let fromUpstream: Response | undefined;
+    const next: InterceptNext = async (replacement?: Request) => {
+      calledNext = true;
+      fromUpstream = await run(index + 1, replacement ?? current);
+      return fromUpstream;
+    };
+    const started = Date.now();
+    const url = new URL(current.url);
+    const record: InterceptedRequest = {
+      method: current.method,
+      path: `${url.pathname}${url.search}`,
+      status: 0,
+      answeredBy: "handler",
+    };
+    let res: Response;
+    try {
+      res = await it.handler(current, next);
+      if (!(res instanceof Response)) {
+        throw new Error(
+          `interceptor for ${it.hostname}${it.path === "/" ? "" : it.path} returned ${
+            res === undefined ? "undefined" : typeof res
+          } — return a Response, or the result of next()`,
+        );
+      }
+    } catch (err) {
+      const e = err as Error;
+      res = new Response(
+        `spectest-daemon: interceptor for ${it.hostname} threw: ${e?.message ?? String(err)}\n`,
+        { status: 500, headers: { "content-type": "text/plain" } },
+      );
+      record.answeredBy = "handler";
+      record.status = 500;
+      it.calls++;
+      it.requests.push(record);
+      observe?.(it, record, Date.now() - started);
+      return res;
+    }
+    record.status = res.status;
+    record.answeredBy = !calledNext ? "handler" : res === fromUpstream ? "upstream" : "modified";
+    it.calls++;
+    it.requests.push(record);
+    observe?.(it, record, Date.now() - started);
+    return res;
+  };
+  return run(0, req);
+}

package/src/index.ts

@@ -168,6 +168,32 @@ export type {
   LoweredIngress,
 } from "./ingress.js";
 import type { DnsTarget } from "./ingress.js";
+import type {
+  InterceptHandler,
+  InterceptNext,
+  InterceptedRequest,
+} from "./harness/intercept.js";
+export type { InterceptHandler, InterceptNext, InterceptedRequest };
+
+/**
+ * The handle `ctx.intercept` returns: what the interceptor has seen so far,
+ * and the way to take it down early. A test's interceptors are removed
+ * when the test ends whether or not `remove()` was called.
+ */
+export interface Interception {
+  hostname: string;
+  /** The normalised mount path (`"/"` when none was given). */
+  path: string;
+  /** How many requests the interceptor has seen. Provenance-wrapped, so an
+   *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
+   *  the raw number. */
+  readonly calls: Wrapped<number>;
+  /** Every request it saw, in order, with the status it got and who
+   *  answered it (`handler` | `upstream` | `modified`). */
+  readonly requests: Wrapped<InterceptedRequest[]>;
+  /** Stop intercepting now. Idempotent. */
+  remove(): void;
+}
 import { isWildcard as isWildcardHost } from "./ingress.js";
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -514,6 +540,40 @@ export interface SpectestContext<
    * ```
    */
   dnsName(hostname: string, target: DnsTarget): Promise<void>;
+  /**
+   * Put middleware in front of a hostname the ingress serves — the way to
+   * make your **own** backend misbehave for one test: force a 500 from an
+   * API route, add latency, fail twice then pass, or just count calls.
+   *
+   * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
+   * response (a proxied service, or a fake). Return a `Response` to answer
+   * yourself, `next()` to pass through, or change what `next()` returned.
+   * An optional mount `path` limits it to that path and everything below
+   * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
+   * registration order.
+   *
+   * Only traffic that reaches the daemon can be intercepted: the browser,
+   * `ctx.fetch`, and any container that calls the hostname — so the service
+   * needs a `tls`/`hostnames` entry (or `supabase({ hostname })`), or the
+   * target is a fake. A bare `http://<service>:<port>` call between
+   * containers never passes through here, and a hostname nothing claims is
+   * refused at registration.
+   *
+   * From a test, the interceptor lasts until the test ends (a `dependsOn`
+   * child never inherits it); from `eval` or `setup` it lasts until
+   * `remove()`. Every request it sees is recorded under the intercept step.
+   *
+   * ```ts
+   * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
+   *   new Response("boom", { status: 500 }));
+   * await page.getByRole("button", { name: "Sync" }).click();
+   * await expect(page.getByText("Retry")).toBeVisible();
+   * expect(outage.calls).toBe(1);
+   * outage.remove();                           // the retry now reaches the real function
+   * ```
+   */
+  intercept(hostname: string, handler: InterceptHandler): Interception;
+  intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
   /**
    * Mint a leaf certificate from the in-VM root CA and return the PEMs.
    *