@specific.dev/spectest 0.61.0 → 0.63.0

package/src/index.ts

@@ -5,6 +5,7 @@
 // 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";
@@ -144,6 +145,7 @@ export {
   type ServiceCoverage,
 } from "./coverage.js";
 import { applyCoverageAdapters, validateCoverage, type ServiceCoverage } 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
@@ -166,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";
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -512,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.
    *
@@ -1043,18 +1105,121 @@ 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>>;
     };
 
+/** 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: string, buildArgs: Readonly<Record<string, string>> | undefined): void {
+  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: string, image: ServiceImage): ServiceImage {
+  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 as string, `service "${serviceName}" Dockerfile`);
+  let content: string;
+  try {
+    content = readFileSync(file, "utf8");
+  } catch (e) {
+    throw new Error(
+      `service "${serviceName}" Dockerfile ${JSON.stringify(image.path)} could not be read: ${(e as Error).message}`,
+    );
+  }
+  const lowered: ServiceImage = { type: "dockerfile", content };
+  if (image.exclude !== undefined) lowered.exclude = image.exclude;
+  if (image.buildArgs !== undefined) lowered.buildArgs = image.buildArgs;
+  return lowered;
+}
+
 // Coverage adapters live in `coverage.ts`; the type is re-declared here
 // through the import below so `ServiceConfig.coverage` reads in one place.
 
@@ -2204,7 +2369,10 @@ export function defineEnvironment<
   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: EnvironmentConfig<S> = {
     ...rest,