@specific.dev/spectest 0.60.2 → 0.62.0

package/dist/daemon.js

@@ -21,7 +21,7 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, resolveServiceImage, proxy as makeProxyDecl, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, nodeCoverageToolsAvailable, nodeCoverageToolsDir, NODE_COVERAGE_TOOLS_CONTAINER_DIR, } from "./coverage.js";
@@ -32,7 +32,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
 // exact-then-longest-suffix rule and the one-label certificate rule are
 // each easy to restate subtly differently.
-import { buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
+import { buildArgFlags, buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
@@ -114,7 +114,7 @@ let loaded = null;
 /** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
  *  keep the call sites reading off the suite. */
 function casesMetadata(suite) {
-    return catalogueCases(suite?.tests);
+    return catalogueCases(suite?.tests, APP_DIR);
 }
 function groupsMetadata(suite) {
     return catalogueGroups(suite?.tests);
@@ -831,7 +831,7 @@ async function prepareServiceImage(svc, opts) {
     // (/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);
@@ -922,6 +922,16 @@ RUN P='[spectest-ca]'; \\
     fi
 `;
 }
+/** 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) {
+    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.
  *
@@ -997,6 +1007,9 @@ async function runServiceBuild(name, image, tag, caSuffix) {
         const useBuildKit = useRemote || (await hasBuildx());
         const buildEnv = {};
         let buildArgs;
+        // 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
@@ -1007,15 +1020,16 @@ async function runServiceBuild(name, image, tag, caSuffix) {
                 "--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) => {
@@ -2323,9 +2337,11 @@ const RUNTIME_SERVICES = new Map();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec) {
     const { name, ...rest } = spec;
-    // A runtime spec skipped `defineEnvironment`, so its coverage adapters
-    // get their config-time pass here.
-    return { name, ...applyCoverageAdapters(name, rest) };
+    // 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, image: resolveServiceImage(name, rest.image) };
+    return { name, ...applyCoverageAdapters(name, svc) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
  *  Prepares the image (pulling on first use through the host cache), runs

package/dist/harness/build-context.d.ts

@@ -79,4 +79,7 @@ export interface Hasher {
 export declare function buildContentKey(createHasher: () => Hasher, image: {
     content: string;
     exclude?: readonly string[];
+    buildArgs?: Readonly<Record<string, string>>;
 }): string;
+/** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
+export declare function buildArgFlags(buildArgs: Readonly<Record<string, string>> | undefined): string[];

package/dist/harness/build-context.js

@@ -109,5 +109,17 @@ export function buildContentKey(createHasher, image) {
         // 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) {
+    return Object.entries(buildArgs ?? {})
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([k, v]) => ["--build-arg", `${k}=${v}`]);
+}

package/dist/harness/catalogue.d.ts

@@ -21,6 +21,8 @@ export interface CatalogueCase {
             id: string;
         };
     };
+    /** Absolute path of the file that registered the test, if known. */
+    file?: string;
 }
 export interface CaseMeta {
     id: string;
@@ -30,6 +32,9 @@ export interface CaseMeta {
     /** The group this case is shown in, if any. Display only — a group never
      *  changes the DAG, which `dependsOn` still describes in full. */
     groupId?: string;
+    /** Project-relative path (`spectest/tests/…`) of the file that defines
+     *  the test, when the SDK recorded one and it lies under `appDir`. */
+    file?: string;
 }
 /** A display-only test group (`env.group(...)`), for the CLI tree and the
  *  dashboard. `dependsOn` is the group's own level: every member of the
@@ -39,7 +44,12 @@ export interface GroupMeta {
     name: string;
     dependsOn?: string;
 }
-export declare function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[];
+export declare function casesMetadata(cases: readonly CatalogueCase[] | undefined, appDir?: string): CaseMeta[];
+/** `file` relative to `appDir` (the app dir holds the project's `spectest/`
+ *  directory, so the result reads `spectest/tests/x.ts`). A file outside it
+ *  — or no `appDir` — is reported as nothing: the selector then treats a
+ *  change to a test file as unknown, which is the safe reading. */
+export declare function relativeTestFile(file: string | undefined, appDir: string | undefined): string | undefined;
 /**
  * The groups the suite uses, in the order their first member appears —
  * which is the order both surfaces render in.

package/dist/harness/catalogue.js

@@ -5,7 +5,7 @@
  * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
  * `cases`) return this, so the mapping lives in one place.
  */
-export function casesMetadata(cases) {
+export function casesMetadata(cases, appDir) {
     if (!cases)
         return [];
     return cases.map((t) => ({
@@ -14,8 +14,21 @@ export function casesMetadata(cases) {
         dependsOn: t.dependsOn?.id,
         timeoutMs: t.timeoutMs,
         groupId: t.group?.id,
+        file: relativeTestFile(t.file, appDir),
     }));
 }
+/** `file` relative to `appDir` (the app dir holds the project's `spectest/`
+ *  directory, so the result reads `spectest/tests/x.ts`). A file outside it
+ *  — or no `appDir` — is reported as nothing: the selector then treats a
+ *  change to a test file as unknown, which is the safe reading. */
+export function relativeTestFile(file, appDir) {
+    if (!file || !appDir)
+        return undefined;
+    const root = appDir.endsWith("/") ? appDir : appDir + "/";
+    if (!file.startsWith(root))
+        return undefined;
+    return file.slice(root.length);
+}
 /**
  * The groups the suite uses, in the order their first member appears —
  * which is the order both surfaces render in.

package/dist/index.d.ts

@@ -658,17 +658,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
@@ -903,6 +953,11 @@ export interface TestCase<T = unknown, S extends ServicesMap = ServicesMap, F ex
     readonly group?: TestGroup<unknown, S, F>;
     /** Override the default per-test timeout (default 60s). */
     readonly timeoutMs?: number;
+    /** @internal — absolute path of the file that called `env.test(...)`,
+     *  read off the call stack at registration. The catalogue reports it
+     *  project-relative so a change to a test file can select exactly the
+     *  cases it defines (subset runs). Absent when the stack gave none. */
+    readonly file?: string;
     /** @internal — the body that the in-sandbox daemon invokes. */
     readonly run: TestFn<T, unknown, S, F>;
 }

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,
@@ -470,9 +534,36 @@ maybeFn) {
         dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
         group: opts.group,
         timeoutMs: opts.timeoutMs,
+        file: callerFile(),
         run: fn,
     };
 }
+/**
+ * The file of the nearest stack frame outside this module — the test file
+ * that called `env.test(...)`. Frames look like `at fn (/abs/path.ts:1:2)`
+ * or `at /abs/path.ts:1:2`; the first one whose path is not this module's
+ * is the caller. `undefined` when the stack is unavailable.
+ */
+function callerFile() {
+    const stack = new Error().stack;
+    if (!stack)
+        return undefined;
+    let self;
+    for (const line of stack.split("\n")) {
+        const m = /\(?((?:\/|[A-Za-z]:\\)[^\s()]+?):\d+:\d+\)?\s*$/.exec(line);
+        if (!m)
+            continue;
+        const file = m[1];
+        // The first path on the stack is this module (callerFile itself).
+        if (self === undefined) {
+            self = file;
+            continue;
+        }
+        if (file !== self)
+            return file;
+    }
+    return undefined;
+}
 function validateSuite(suite) {
     const seenIds = new Map();
     for (const t of suite.tests) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.60.2",
+  "version": "0.62.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,
@@ -286,7 +288,7 @@ let loaded: Loaded | null = null;
 /** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
  *  keep the call sites reading off the suite. */
 function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
-  return catalogueCases(suite?.tests);
+  return catalogueCases(suite?.tests, APP_DIR);
 }
 
 function groupsMetadata(suite: TestSuite | undefined): GroupMeta[] {
@@ -1097,7 +1099,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 +1150,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 +1240,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 +1265,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 +1310,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 +1341,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 +1354,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) => {
@@ -2814,9 +2837,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`.

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/catalogue.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { casesMetadata, groupsMetadata, type CatalogueCase } from "./catalogue";
+import { casesMetadata, groupsMetadata, relativeTestFile, type CatalogueCase } from "./catalogue";
 
 const billing = { id: "billing", name: "Billing" };
 const errors = {
@@ -59,3 +59,11 @@ describe("groupsMetadata", () => {
     expect(groupsMetadata(undefined)).toEqual([]);
   });
 });
+
+test("relativeTestFile reports a test file relative to the app dir, or nothing", () => {
+  expect(relativeTestFile("/opt/spectest/app/spectest/tests/a.ts", "/opt/spectest/app")).toBe("spectest/tests/a.ts");
+  expect(relativeTestFile("/opt/spectest/app/spectest/tests/a.ts", "/opt/spectest/app/")).toBe("spectest/tests/a.ts");
+  expect(relativeTestFile("/elsewhere/a.ts", "/opt/spectest/app")).toBeUndefined();
+  expect(relativeTestFile(undefined, "/opt/spectest/app")).toBeUndefined();
+  expect(relativeTestFile("/opt/spectest/app/spectest/tests/a.ts", undefined)).toBeUndefined();
+});

package/src/harness/catalogue.ts

@@ -14,6 +14,8 @@ export interface CatalogueCase {
   dependsOn?: { id: string };
   timeoutMs?: number;
   group?: { id: string; name: string; dependsOn?: { id: string } };
+  /** Absolute path of the file that registered the test, if known. */
+  file?: string;
 }
 
 export interface CaseMeta {
@@ -24,6 +26,9 @@ export interface CaseMeta {
   /** The group this case is shown in, if any. Display only — a group never
    *  changes the DAG, which `dependsOn` still describes in full. */
   groupId?: string;
+  /** Project-relative path (`spectest/tests/…`) of the file that defines
+   *  the test, when the SDK recorded one and it lies under `appDir`. */
+  file?: string;
 }
 
 /** A display-only test group (`env.group(...)`), for the CLI tree and the
@@ -35,7 +40,10 @@ export interface GroupMeta {
   dependsOn?: string;
 }
 
-export function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[] {
+export function casesMetadata(
+  cases: readonly CatalogueCase[] | undefined,
+  appDir?: string,
+): CaseMeta[] {
   if (!cases) return [];
   return cases.map((t) => ({
     id: t.id,
@@ -43,9 +51,21 @@ export function casesMetadata(cases: readonly CatalogueCase[] | undefined): Case
     dependsOn: t.dependsOn?.id,
     timeoutMs: t.timeoutMs,
     groupId: t.group?.id,
+    file: relativeTestFile(t.file, appDir),
   }));
 }
 
+/** `file` relative to `appDir` (the app dir holds the project's `spectest/`
+ *  directory, so the result reads `spectest/tests/x.ts`). A file outside it
+ *  — or no `appDir` — is reported as nothing: the selector then treats a
+ *  change to a test file as unknown, which is the safe reading. */
+export function relativeTestFile(file: string | undefined, appDir: string | undefined): string | undefined {
+  if (!file || !appDir) return undefined;
+  const root = appDir.endsWith("/") ? appDir : appDir + "/";
+  if (!file.startsWith(root)) return undefined;
+  return file.slice(root.length);
+}
+
 /**
  * The groups the suite uses, in the order their first member appears —
  * which is the order both surfaces render in.

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
@@ -1043,18 +1045,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.
 
@@ -1407,6 +1512,11 @@ export interface TestCase<
   readonly group?: TestGroup<unknown, S, F>;
   /** Override the default per-test timeout (default 60s). */
   readonly timeoutMs?: number;
+  /** @internal — absolute path of the file that called `env.test(...)`,
+   *  read off the call stack at registration. The catalogue reports it
+   *  project-relative so a change to a test file can select exactly the
+   *  cases it defines (subset runs). Absent when the stack gave none. */
+  readonly file?: string;
   /** @internal — the body that the in-sandbox daemon invokes. */
   readonly run: TestFn<T, unknown, S, F>;
 }
@@ -2199,7 +2309,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,
@@ -2375,10 +2488,35 @@ function buildTestCase(
     dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
     group: opts.group,
     timeoutMs: opts.timeoutMs,
+    file: callerFile(),
     run: fn,
   };
 }
 
+/**
+ * The file of the nearest stack frame outside this module — the test file
+ * that called `env.test(...)`. Frames look like `at fn (/abs/path.ts:1:2)`
+ * or `at /abs/path.ts:1:2`; the first one whose path is not this module's
+ * is the caller. `undefined` when the stack is unavailable.
+ */
+function callerFile(): string | undefined {
+  const stack = new Error().stack;
+  if (!stack) return undefined;
+  let self: string | undefined;
+  for (const line of stack.split("\n")) {
+    const m = /\(?((?:\/|[A-Za-z]:\\)[^\s()]+?):\d+:\d+\)?\s*$/.exec(line);
+    if (!m) continue;
+    const file = m[1]!;
+    // The first path on the stack is this module (callerFile itself).
+    if (self === undefined) {
+      self = file;
+      continue;
+    }
+    if (file !== self) return file;
+  }
+  return undefined;
+}
+
 /** The two option shapes as one, for the untyped runtime implementation.
  *  The public overloads keep them apart — see {@link TestOpts}. */
 interface AnyTestOpts {