@specific.dev/spectest 0.61.0 → 0.63.0

package/src/dockerfile-path.test.ts

@@ -0,0 +1,87 @@
+// `image: { type: "dockerfile", path }` — a Dockerfile in the repo is read
+// into `content` when the environment loads, so the harness only ever sees
+// bytes. The project root is `SPECTEST_WORKSPACE` (the VM's /workspace).
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// Set before the SDK reads it (module-load time), so no top-level import.
+let root = "";
+beforeEach(() => {
+  root = mkdtempSync(path.join(tmpdir(), "spectest-dockerfile-"));
+  process.env.SPECTEST_WORKSPACE = root;
+  process.env.SPECTEST_APP_DIR = path.join(root, "app-copy");
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+const load = async () => await import("./index");
+
+describe("dockerfile path", () => {
+  test("a repo-relative path is read into content, exclude kept", async () => {
+    mkdirSync(path.join(root, "apps/api"), { recursive: true });
+    writeFileSync(path.join(root, "apps/api/Dockerfile"), "FROM node:20\nCOPY . /app\n");
+    const { defineEnvironment } = await load();
+    const env = defineEnvironment({
+      name: "p",
+      services: {
+        api: {
+          image: {
+            type: "dockerfile",
+            path: "apps/api/Dockerfile",
+            exclude: ["docs/**"],
+            buildArgs: { NODE_ENV: "test" },
+          },
+        },
+      },
+    });
+    expect(env.config.services.api.image).toEqual({
+      type: "dockerfile",
+      content: "FROM node:20\nCOPY . /app\n",
+      exclude: ["docs/**"],
+      buildArgs: { NODE_ENV: "test" },
+    });
+  });
+
+  test("a missing file fails the load and names the path", async () => {
+    const { defineEnvironment } = await load();
+    expect(() =>
+      defineEnvironment({
+        name: "p",
+        services: { api: { image: { type: "dockerfile", path: "nope/Dockerfile" } } },
+      }),
+    ).toThrow(/service "api" Dockerfile "nope\/Dockerfile" is not in the VM/);
+  });
+
+  test("path and content together, or neither, is an error", async () => {
+    const { resolveServiceImage } = await load();
+    expect(() =>
+      resolveServiceImage("api", { type: "dockerfile", path: "Dockerfile", content: "FROM x" } as never),
+    ).toThrow(/both `path` and `content`/);
+    expect(() => resolveServiceImage("api", { type: "dockerfile" } as never)).toThrow(
+      /needs `path`/,
+    );
+  });
+
+  test("buildArgs keys must be ARG names and values strings", async () => {
+    const { resolveServiceImage } = await load();
+    expect(() =>
+      resolveServiceImage("api", { type: "dockerfile", content: "FROM x", buildArgs: { "NO-DASH": "1" } }),
+    ).toThrow(/not a valid ARG name/);
+    expect(() =>
+      resolveServiceImage("api", {
+        type: "dockerfile",
+        content: "FROM x",
+        buildArgs: { PORT: 3000 } as never,
+      }),
+    ).toThrow(/must be a string/);
+  });
+
+  test("content and registry images pass through untouched", async () => {
+    const { resolveServiceImage } = await load();
+    const inline = { type: "dockerfile", content: "FROM x\n" } as const;
+    expect(resolveServiceImage("a", inline)).toBe(inline);
+    const reg = { type: "registry", reference: "nginx" } as const;
+    expect(resolveServiceImage("a", reg)).toBe(reg);
+  });
+});

package/src/harness/build-context.ts

@@ -130,7 +130,7 @@ export interface Hasher {
 
 export function buildContentKey(
   createHasher: () => Hasher,
-  image: { content: string; exclude?: readonly string[] },
+  image: { content: string; exclude?: readonly string[]; buildArgs?: Readonly<Record<string, string>> },
 ): string {
   return (
     createHasher()
@@ -141,6 +141,19 @@ export function buildContentKey(
       // genuinely different builds would collapse into one.
       .update("\0")
       .update(JSON.stringify(image.exclude ?? []))
+      // Build args are an input to the image (an ARG picks the base image,
+      // the NODE_ENV of an install step…), so two services on one
+      // Dockerfile with different args must not share a build. Sorted, so
+      // key order in the user's object doesn't split identical builds.
+      .update("\0")
+      .update(JSON.stringify(buildArgFlags(image.buildArgs)))
       .digest("hex")
   );
 }
+
+/** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
+export function buildArgFlags(buildArgs: Readonly<Record<string, string>> | undefined): string[] {
+  return Object.entries(buildArgs ?? {})
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .flatMap(([k, v]) => ["--build-arg", `${k}=${v}`]);
+}

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);
+}