@specific.dev/spectest 0.61.0 → 0.63.0

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.
      *
@@ -658,17 +713,67 @@ export interface ServiceTls {
 export type ServiceImage = {
     type: "registry";
     reference: string;
+} | {
+    type: "dockerfile";
+    /**
+     * Path of a Dockerfile in your repo, relative to the project root
+     * (where `spectest/` lives) — `"Dockerfile"`, `"apps/api/Dockerfile"`.
+     * This is the preferred form: the test environment builds the same
+     * Dockerfile production does, so the two cannot drift. The build
+     * context is always the project root, as with
+     * `docker build -f apps/api/Dockerfile .`, so `COPY` / `ADD` resolve
+     * against the repo root wherever the file sits. The file is read when
+     * the environment loads; a missing file fails the load and names the
+     * path. Mutually exclusive with `content`.
+     */
+    path: string;
+    content?: never;
+    /** Extra glob patterns to exclude from the build context. */
+    exclude?: readonly string[];
+    /**
+     * `--build-arg` values for the Dockerfile's `ARG`s — `{ NODE_ENV: "test" }`.
+     * Build-time only: they are not in the container's environment (use
+     * `env` for that), and they are part of the image's identity, so two
+     * services building one Dockerfile with different args build twice.
+     * Build args land in the image history; pass nothing secret.
+     */
+    buildArgs?: Readonly<Record<string, string>>;
 } | {
     type: "dockerfile";
     /**
      * Dockerfile contents, written verbatim into the build context. The
      * build context is the project root (where `spectest/` lives), so any
      * `COPY` / `ADD` references resolve relative to that directory.
+     * Prefer `path`, which points at the Dockerfile your repo already has.
+     * Mutually exclusive with `path`.
      */
     content: string;
+    path?: never;
     /** Extra glob patterns to exclude from the build context. */
     exclude?: readonly string[];
+    /**
+     * `--build-arg` values for the Dockerfile's `ARG`s — `{ NODE_ENV: "test" }`.
+     * Build-time only: they are not in the container's environment (use
+     * `env` for that), and they are part of the image's identity, so two
+     * services building one Dockerfile with different args build twice.
+     * Build args land in the image history; pass nothing secret.
+     */
+    buildArgs?: Readonly<Record<string, string>>;
 };
+/**
+ * Resolve a service's `image` to the form the harness builds: a `path`
+ * Dockerfile is read from the repo and becomes `content`. The wire config
+ * therefore never carries `path` — the control plane and the daemon's build
+ * code only ever see Dockerfile bytes, and the warm-template hash covers
+ * them because the file is part of the project tree.
+ *
+ * Runs at config time (`defineEnvironment`, and the daemon's runtime
+ * `startService` twin), inside the VM, where the repo sits at the project
+ * root. The read goes through the project-file resolver, so the same rules
+ * as `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
+ * instead of read stale).
+ */
+export declare function resolveServiceImage(serviceName: string, image: ServiceImage): ServiceImage;
 export interface VolumeMount {
     /**
      * Named shared volume. Two services mounting the same `name` share one

package/dist/index.js

@@ -4,6 +4,7 @@
 // The daemon loads this file on boot and the control plane talks to it
 // over HTTP.
 import { strict as nodeAssert } from "node:assert";
+import { readFileSync } from "node:fs";
 import { recordAssertion, safeSerialize } from "./recorder.js";
 import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
 // `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
@@ -41,6 +42,7 @@ import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_
 import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
+import { resolveExistingProjectPath } from "./project-files.js";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
@@ -216,6 +218,65 @@ function expandServiceGroups(input) {
     }
     return out;
 }
+/** A Dockerfile `ARG` name: what `docker build --build-arg` accepts as a key. */
+const BUILD_ARG_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function validateBuildArgs(serviceName, buildArgs) {
+    if (buildArgs === undefined)
+        return;
+    if (typeof buildArgs !== "object" || buildArgs === null || Array.isArray(buildArgs)) {
+        throw new Error(`service "${serviceName}" image buildArgs must be a { NAME: "value" } record`);
+    }
+    for (const [k, v] of Object.entries(buildArgs)) {
+        if (!BUILD_ARG_NAME_RE.test(k)) {
+            throw new Error(`service "${serviceName}" image buildArgs key ${JSON.stringify(k)} is not a valid ARG name (letters, digits, underscore)`);
+        }
+        if (typeof v !== "string") {
+            throw new Error(`service "${serviceName}" image buildArgs ${k} must be a string (a build arg is text; got ${typeof v})`);
+        }
+    }
+}
+/**
+ * Resolve a service's `image` to the form the harness builds: a `path`
+ * Dockerfile is read from the repo and becomes `content`. The wire config
+ * therefore never carries `path` — the control plane and the daemon's build
+ * code only ever see Dockerfile bytes, and the warm-template hash covers
+ * them because the file is part of the project tree.
+ *
+ * Runs at config time (`defineEnvironment`, and the daemon's runtime
+ * `startService` twin), inside the VM, where the repo sits at the project
+ * root. The read goes through the project-file resolver, so the same rules
+ * as `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
+ * instead of read stale).
+ */
+export function resolveServiceImage(serviceName, image) {
+    if (image.type !== "dockerfile")
+        return image;
+    validateBuildArgs(serviceName, image.buildArgs);
+    const hasPath = typeof image.path === "string";
+    const hasContent = typeof image.content === "string";
+    if (hasPath && hasContent) {
+        throw new Error(`service "${serviceName}" image sets both \`path\` and \`content\` — point at the Dockerfile in your repo with \`path\`, or inline it with \`content\`, not both`);
+    }
+    if (!hasPath && !hasContent) {
+        throw new Error(`service "${serviceName}" image { type: "dockerfile" } needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``);
+    }
+    if (!hasPath)
+        return image;
+    const file = resolveExistingProjectPath(image.path, `service "${serviceName}" Dockerfile`);
+    let content;
+    try {
+        content = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        throw new Error(`service "${serviceName}" Dockerfile ${JSON.stringify(image.path)} could not be read: ${e.message}`);
+    }
+    const lowered = { type: "dockerfile", content };
+    if (image.exclude !== undefined)
+        lowered.exclude = image.exclude;
+    if (image.buildArgs !== undefined)
+        lowered.buildArgs = image.buildArgs;
+    return lowered;
+}
 function validateEnvironmentConfig(config) {
     const entries = Object.entries(config.services);
     const serviceNames = new Set(entries.map(([n]) => n));
@@ -325,7 +386,10 @@ export function defineEnvironment(input) {
     const { fakes, services: rawServices, ...rest } = input;
     const expanded = expandServiceGroups(rawServices);
     for (const [key, svc] of Object.entries(expanded)) {
-        expanded[key] = applyCoverageAdapters(key, svc);
+        expanded[key] = applyCoverageAdapters(key, {
+            ...svc,
+            image: resolveServiceImage(key, svc.image),
+        });
     }
     const config = {
         ...rest,

package/package.json

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

package/src/daemon.ts

@@ -31,6 +31,7 @@ import {
   lowerIngress,
   dnsName as makeDnsDecl,
   isWildcard,
+  resolveServiceImage,
   proxy as makeProxyDecl,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
@@ -68,6 +69,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 import {
   DEFAULT_DOCKERIGNORE,
   GENERATED_DOCKERIGNORE_HEADER,
+  buildArgFlags,
   buildContentKey as computeBuildContentKey,
   imageTag,
   isGeneratedDockerignore,
@@ -96,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,
@@ -149,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,
@@ -189,6 +197,9 @@ import type {
   FakeContext,
   FakeDefinition,
   FileMount,
+  InterceptHandler,
+  Interception,
+  InterceptedRequest,
   Project,
   ProjectSetupContext,
   ReadyCheck,
@@ -1097,7 +1108,13 @@ const BUILD_DEDUP = new Map<
   { name: string; promise: Promise<{ tag: string; buildSteps?: BuildStep[] }> }
 >();
 
-function buildContentKey(image: { content: string; exclude?: readonly string[] }): string {
+type DockerfileBuild = {
+  content: string;
+  exclude?: readonly string[];
+  buildArgs?: Readonly<Record<string, string>>;
+};
+
+function buildContentKey(image: DockerfileBuild): string {
   return computeBuildContentKey(() => new Bun.CryptoHasher("sha256") as any, image);
 }
 
@@ -1142,7 +1159,7 @@ async function prepareServiceImage(
   // (/workspace) is an input too — a runtime service started mid-test
   // after setup/test code mutated /workspace must rebuild, not share a
   // pre-mutation image.
-  const image = svc.image;
+  const image = dockerfileContent(svc);
   if (opts?.dedup) {
     const key = buildContentKey(image);
     const inflight = BUILD_DEDUP.get(key);
@@ -1232,6 +1249,17 @@ RUN P='[spectest-ca]'; \\
 `;
 }
 
+/** The built form of a dockerfile image. `resolveServiceImage` read a
+ *  `path` into `content` at config time, so a service that still carries
+ *  `path` here skipped that step — a programming error, not user input. */
+function dockerfileContent(svc: NamedService): DockerfileBuild {
+  const image = svc.image;
+  if (image.type !== "dockerfile" || typeof image.content !== "string") {
+    throw new Error(`service "${svc.name}" image was not resolved to Dockerfile contents`);
+  }
+  return image;
+}
+
 /**
  * Build a dockerfile service's image.
  *
@@ -1246,7 +1274,7 @@ RUN P='[spectest-ca]'; \\
  */
 async function buildServiceImage(
   name: string,
-  image: { content: string; exclude?: readonly string[] },
+  image: DockerfileBuild,
   tag: string,
 ): Promise<{ tag: string; buildSteps?: BuildStep[] }> {
   const suffix = await caTrustSuffix();
@@ -1291,7 +1319,7 @@ async function imageRunsAsRoot(tag: string): Promise<boolean> {
 
 async function runServiceBuild(
   name: string,
-  image: { content: string; exclude?: readonly string[] },
+  image: DockerfileBuild,
   tag: string,
   caSuffix: string | null,
 ): Promise<{ ok: boolean; folded: boolean; log: string; buildSteps?: BuildStep[] }> {
@@ -1322,6 +1350,9 @@ async function runServiceBuild(
     const useBuildKit = useRemote || (await hasBuildx());
     const buildEnv: Record<string, string> = {};
     let buildArgs: string[];
+    // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
+    // so every builder — host buildkitd, in-VM BuildKit, legacy — takes it.
+    const argFlags = buildArgFlags(image.buildArgs);
     if (useRemote) {
       // Build on the host-side shared buildkitd (persistent cross-VM cache);
       // `--load` brings the finished image back into the in-VM dockerd so
@@ -1332,13 +1363,14 @@ async function runServiceBuild(
         "--builder", REMOTE_BUILDER_NAME,
         "--load",
         "--progress=plain",
+        ...argFlags,
         "-t", tag, "-f", dfPath, WORKSPACE,
       ];
     } else if (useBuildKit) {
-      buildArgs = ["build", "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
+      buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
       buildEnv.DOCKER_BUILDKIT = "1";
     } else {
-      buildArgs = ["build", "-t", tag, "-f", dfPath, WORKSPACE];
+      buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, WORKSPACE];
     }
     progressService(name, { status: "building", detail: "starting build" });
     const build = await shxStream("docker", buildArgs, 1_800_000, buildEnv, (line) => {
@@ -2426,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);
 }
 
@@ -2732,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
@@ -2814,9 +2981,11 @@ const RUNTIME_SERVICES = new Map<string, NamedService>();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec: RuntimeServiceSpec): NamedService {
   const { name, ...rest } = spec;
-  // A runtime spec skipped `defineEnvironment`, so its coverage adapters
-  // get their config-time pass here.
-  return { name, ...applyCoverageAdapters(name, rest as ServiceConfig) };
+  // A runtime spec skipped `defineEnvironment`, so its config-time passes
+  // run here: a `path` Dockerfile is read into `content`, and coverage
+  // adapters get their configure step.
+  const svc = { ...(rest as ServiceConfig), image: resolveServiceImage(name, rest.image) };
+  return { name, ...applyCoverageAdapters(name, svc) };
 }
 
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
@@ -4278,6 +4447,7 @@ async function spectestContext(scope: ContextScope = {}): Promise<SpectestContex
     certificate: mintCertificate,
     startService: startRuntimeService,
     stopService: stopRuntimeService,
+    intercept: registerInterceptor as SpectestContext["intercept"],
   };
 }
 
@@ -5228,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;
@@ -5259,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