@specific.dev/spectest 0.47.0 → 0.48.0

package/dist/browser.d.ts

@@ -359,4 +359,5 @@ export interface RecordableFields {
     attempts: number;
     artifactId: string;
     attribute: string;
+    files: string[];
 }

package/dist/daemon.js

@@ -34,6 +34,7 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
@@ -52,7 +53,6 @@ function namedServices(cfg) {
 }
 const DEFAULT_TEST_TIMEOUT_MS = 60_000;
 const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
-const WORKSPACE = process.env.SPECTEST_WORKSPACE ?? "/workspace";
 // Stable hostname every service container resolves to the host (the
 // `spectest-br0` gateway) — so apps that build or pull images at runtime
 // can point a builder at `spectest-host:5000` (the zot Docker Hub mirror)
@@ -77,7 +77,9 @@ function hostCacheGateway() {
     }
     return _hostCacheGateway;
 }
-const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+// WORKSPACE (/workspace) and APP_DIR (/opt/spectest/app) both live in
+// project-files.ts, next to the rule that decides which copy of a project
+// file is the current one.
 // The bun the base snapshot installs (base.rs::BASE_SETUP_SH). The daemon
 // runs under it, and eval's dependency install shells out to it.
 const BUN_BIN = "/usr/local/bin/bun";
@@ -1028,7 +1030,7 @@ async function probeTcp(host, port) {
     return new Promise((resolve) => {
         const sock = net.createConnection({ host, port });
         let settled = false;
-        const finish = (v) => {
+        const finish = (ok, detail) => {
             if (settled)
                 return;
             settled = true;
@@ -1038,26 +1040,30 @@ async function probeTcp(host, port) {
             catch {
                 /* ignore */
             }
-            resolve(v);
+            resolve({ ok, detail });
         };
         sock.setTimeout(2000);
-        sock.once("connect", () => finish(true));
-        sock.once("error", () => finish(false));
-        sock.once("timeout", () => finish(false));
+        sock.once("connect", () => finish(true, `connected to ${host}:${port}`));
+        sock.once("error", (err) => finish(false, `connect to ${host}:${port} failed: ${err.message}`));
+        sock.once("timeout", () => finish(false, `connect to ${host}:${port} got no reply within 2000ms`));
     });
 }
 async function probeHttp(host, port, urlPath, headers, expectStatus) {
+    const url = `http://${host}:${port}${urlPath}`;
     const ctrl = new AbortController();
     const to = setTimeout(() => ctrl.abort(), 5000);
     try {
-        const res = await fetch(`http://${host}:${port}${urlPath}`, {
-            signal: ctrl.signal,
-            headers,
-        });
-        return expectStatus !== undefined ? res.status === expectStatus : res.ok;
+        const res = await fetch(url, { signal: ctrl.signal, headers });
+        const ok = expectStatus !== undefined ? res.status === expectStatus : res.ok;
+        const want = expectStatus !== undefined ? String(expectStatus) : "2xx";
+        return { ok, detail: `GET ${url} → ${res.status} (wanted ${want})` };
     }
-    catch {
-        return false;
+    catch (err) {
+        const e = err;
+        const detail = e?.name === "AbortError"
+            ? `GET ${url} got no reply within 5000ms`
+            : `GET ${url} failed: ${e?.message ?? String(err)}`;
+        return { ok: false, detail };
     }
     finally {
         clearTimeout(to);
@@ -1065,28 +1071,64 @@ async function probeHttp(host, port, urlPath, headers, expectStatus) {
 }
 async function probeExec(name, command) {
     const r = await docker(["exec", name, "sh", "-c", command], 10_000);
-    return r.code === 0;
+    if (r.code === 0)
+        return { ok: true, detail: `\`${command}\` exited 0` };
+    // 124 is shx's own kill (see `shx`): the exec never answered, which says
+    // the docker daemon is wedged or starved rather than anything about the
+    // command's verdict.
+    const why = r.code === 124
+        ? `was killed after 10000ms with no reply`
+        : `exited ${r.code}`;
+    const output = firstLine(r.stderr) || firstLine(r.stdout);
+    return {
+        ok: false,
+        detail: `\`${command}\` ${why}${output ? `: ${output}` : ""}`,
+    };
+}
+/** First non-empty line, trimmed and capped — probe output goes into an
+ *  error message, not a log file. */
+function firstLine(s) {
+    const line = s.split("\n").find((l) => l.trim().length > 0)?.trim() ?? "";
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
 }
 async function waitForReady(svc) {
     const check = svc.readyCheck;
     if (!check)
         return;
     const timeoutSecs = check.timeoutSecs ?? 60;
+    let last;
     const probe = async () => {
         if (check.type === "tcp")
-            return probeTcp(svc.name, check.port);
-        if (check.type === "http") {
-            return probeHttp(svc.name, check.port, check.path ?? "/", check.headers, check.expectStatus);
+            last = await probeTcp(svc.name, check.port);
+        else if (check.type === "http") {
+            last = await probeHttp(svc.name, check.port, check.path ?? "/", check.headers, check.expectStatus);
         }
-        return probeExec(svc.name, check.command);
+        else
+            last = await probeExec(svc.name, check.command);
+        return last.ok;
     };
     // Scheduling (the ramp, and not sleeping past the deadline) lives in
     // `harness/ready-poll.ts`; this supplies the probe and the diagnosis.
-    const { ready } = await pollUntilReady(probe, { kind: check.type, timeoutSecs });
+    const { ready, attempts, elapsedMs } = await pollUntilReady(probe, {
+        kind: check.type,
+        timeoutSecs,
+    });
     if (ready)
         return;
+    // The attempt count is half the diagnosis: a probe with a 10s timeout of
+    // its own can only run a handful of times in 60s, so "6 attempts" says the
+    // probes were hanging where "80 attempts" says they ran and kept saying no.
+    let msg = `service ${svc.name} not ready within ${timeoutSecs}s ` +
+        `(${attempts} ${check.type} probe${attempts === 1 ? "" : "s"} over ${Math.round(elapsedMs / 100) / 10}s).`;
+    if (last)
+        msg += `\nLast probe: ${last.detail}`;
     const logs = await docker(["logs", "--tail=200", svc.name], 30_000);
-    throw new Error(`service ${svc.name} not ready within ${timeoutSecs}s. Recent container logs:\n${logs.stdout}\n${logs.stderr}`);
+    const output = `${logs.stdout}\n${logs.stderr}`.trim();
+    // A service that logs nothing (`sleep infinity`, a quiet daemon) used to
+    // get an empty "Recent container logs:" heading, which reads as if the
+    // logs were the evidence and there simply weren't any.
+    msg += output ? `\nRecent container logs:\n${output}` : `\n(the container logged nothing)`;
+    throw new Error(msg);
 }
 /** Validate the `dependsOn` graph and return the name→service map used to
  *  walk it. Rules live in `harness/service-graph.ts`. */
@@ -2926,7 +2968,8 @@ async function spectestContext(scope = {}) {
     const execTimeoutMs = scope.service ? COMPONENT_EXEC_DEFAULT_TIMEOUT_MS : undefined;
     return {
         projectRoot: WORKSPACE,
-        readProjectFile: (p) => fs.readFile(path.isAbsolute(p) ? p : path.join(WORKSPACE, p), "utf8"),
+        readProjectFile: (p) => fs.readFile(resolveProjectPath(p), "utf8"),
+        readProjectFileBytes: async (p) => new Uint8Array(await fs.readFile(resolveProjectPath(p))),
         exec: (service, command, opts) => componentExec(service, command, opts, execTimeoutMs),
         // Read `globalThis.fetch` at call time: the wrapper is installed for
         // the duration of a test / eval / project setup, so a context built
@@ -3342,22 +3385,31 @@ async function pollCall(description, fn, opts) {
     let value;
     let success = false;
     let predicateError;
-    // Record all iterations normally. Falsy iterations get truncated
-    // from the recorder so the timeline doesn't fill with polling
-    // noise; the LAST iteration's events stay, then get marked as
-    // children of the wait event so the UI can render them nested.
+    // Record all iterations normally, but keep only the newest one: a new
+    // attempt drops the events the previous attempt emitted, so the timeline
+    // never fills with polling noise. Whichever attempt is last when the loop
+    // ends — the winning one, or the final failed one — stays, and gets marked
+    // as a child of the wait event so the UI can render it nested.
+    //
+    // The failed attempt is kept deliberately. A poll that times out reports
+    // only "timed out after 120000ms (60 attempts)", which says nothing about
+    // WHY: an ingress answering an instant 404 for two minutes and a backend
+    // that never returns look identical in that message. The last attempt's
+    // events carry the status, the body and the duration, which is the whole
+    // difference between "the route was never programmed" and "the app hung".
     const beforePollIdx = recorderEventCount();
     let lastIterStartIdx = beforePollIdx;
-    let keptIterStartIdx = beforePollIdx;
     while (Date.now() - start < timeoutMs) {
         attempts += 1;
+        // Drop the *previous* attempt's events, not this one's — its events are
+        // the ones worth keeping until a newer attempt replaces them.
+        recorderTruncate(lastIterStartIdx);
         lastIterStartIdx = recorderEventCount();
         try {
             const v = await fn();
             if (v !== null && v !== undefined && v !== false) {
                 value = v;
                 success = true;
-                keptIterStartIdx = lastIterStartIdx;
                 break;
             }
         }
@@ -3365,17 +3417,10 @@ async function pollCall(description, fn, opts) {
             predicateError = err;
             break;
         }
-        // Failed iteration — drop the events it emitted.
-        recorderTruncate(lastIterStartIdx);
         if (Date.now() - start + intervalMs > timeoutMs)
             break;
         await new Promise((r) => setTimeout(r, intervalMs));
     }
-    if (!success) {
-        // Timeout or predicate error: drop every attempt's events. The
-        // wait event we emit below is the only trace.
-        recorderTruncate(beforePollIdx);
-    }
     const errMsg = predicateError !== undefined
         ? (predicateError?.message ?? String(predicateError))
         : success
@@ -3388,11 +3433,11 @@ async function pollCall(description, fn, opts) {
         passed: success,
         ...(errMsg !== undefined ? { error: errMsg } : {}),
     }, resv);
-    if (success && seq !== undefined) {
+    if (seq !== undefined) {
         // Group the kept iteration's events under the wait so the UI can
         // render them inside the wait card. The wait event itself is the
         // very last entry; markChildren skips it via the seq match.
-        recorderMarkChildren(keptIterStartIdx, seq);
+        recorderMarkChildren(lastIterStartIdx, seq);
     }
     if (predicateError !== undefined)
         throw predicateError;

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
 import type { Browser, BrowserOptions } from "./browser.js";
-export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, } from "./locator.js";
+export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, FilePayload, InputFiles, } from "./locator.js";
 import type { Locator } from "./locator.js";
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
@@ -215,6 +215,10 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
     /** Read a project file as UTF-8. Relative paths resolve against
      *  {@link projectRoot}; absolute paths are read as-is. */
     readProjectFile(path: string): Promise<string>;
+    /** Read a project file as bytes — a fixture to post, hash, or compare
+     *  against what the app under test received. Same path rules as
+     *  {@link readProjectFile}. */
+    readProjectFileBytes(path: string): Promise<Uint8Array>;
     /**
      * Run a command inside a service container. Pass an **array** for exact
      * argv with no shell (`["psql", "-f", "-"]`), or a **string** to run via

package/dist/locator.d.ts

@@ -40,6 +40,19 @@ export interface ClickOptions {
     };
     modifiers?: Array<"Alt" | "Control" | "Meta" | "Shift">;
 }
+/** A file built in the test rather than read from the repo — the argument
+ *  shape playwright's `setInputFiles` takes, with `buffer` widened to a plain
+ *  `Uint8Array`/string and `mimeType` optional. */
+export interface FilePayload {
+    name: string;
+    /** Defaults to `application/octet-stream`. */
+    mimeType?: string;
+    /** Bytes, or text (encoded UTF-8). */
+    buffer: Uint8Array | string;
+}
+/** What `setInputFiles` accepts: repo-relative (or absolute) paths, built
+ *  files, or `[]` to clear the input. */
+export type InputFiles = string | string[] | FilePayload | FilePayload[];
 export interface TimeoutOption {
     timeout?: number;
 }
@@ -240,6 +253,25 @@ export interface Locator {
         value?: string;
         index?: number;
     }, opts?: TimeoutOption): Promise<Wrapped<string[]>>;
+    /**
+     * Give an `<input type="file">` its files — the upload primitive, since a
+     * browser refuses a script-set value on a file input. Targets the control a
+     * `<label>` points at, and does **not** require the input to be visible, so
+     * the hidden input behind a drop zone or a styled "Choose file" button is
+     * the thing to select.
+     *
+     * A string is a path in your repo, relative to `ctx.projectRoot` (absolute
+     * paths are taken as-is) — keep fixtures in `spectest/tests/fixtures/`, which
+     * is out of the environment cache key, so adding one still gives a warm
+     * start. Pass a {@link FilePayload} instead for a file the test builds, and
+     * `[]` to clear the input.
+     *
+     * ```ts
+     * await b.locator("#file").setInputFiles("spectest/tests/fixtures/invoice.pdf");
+     * await b.getByLabel("Avatar").setInputFiles({ name: "a.txt", buffer: "hi" });
+     * ```
+     */
+    setInputFiles(files: InputFiles, opts?: TimeoutOption): Promise<void>;
     hover(opts?: TimeoutOption): Promise<void>;
     focus(opts?: TimeoutOption): Promise<void>;
     blur(opts?: TimeoutOption): Promise<void>;

package/dist/locator.js

@@ -21,6 +21,8 @@
 // (actions, reads, `waitFor`) run inside `backend.pageOp`, so each
 // author-facing call is exactly one recorded browser event (with its rrweb
 // drain), whatever playwright work it composes underneath.
+import { Buffer } from "node:buffer";
+import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 /** Default deadline for a locator action/read's target to become actionable.
  *  Playwright's own default is 30s — far too slow-failing for tests; 5s
@@ -264,6 +266,28 @@ async function stampActionPoint(loc, rec, position) {
         /* Element not ready / gone / strict violation — the action reports it. */
     }
 }
+/** Fold a {@link InputFiles} argument into the one playwright takes: repo
+ *  paths resolved to their in-VM location (see project-files.ts), built files
+ *  given a default mime type and a real `Buffer`. The names come back too —
+ *  they are what the timeline step shows, and the bytes never go near it. */
+function lowerInputFiles(files) {
+    const many = Array.isArray(files) ? files : [files];
+    // `[]` clears the input, and every() is true for it — so an empty call
+    // lands here and lowers to an empty path list, which is what clears.
+    if (many.every((f) => typeof f === "string")) {
+        const paths = many.map((f) => resolveExistingProjectPath(f, "fixture"));
+        return { arg: paths, names: paths.map((p) => p.split("/").pop() ?? p) };
+    }
+    if (many.some((f) => typeof f === "string")) {
+        throw new Error("setInputFiles: pass either repo paths or built files — not both in one call");
+    }
+    const payloads = many.map((f) => ({
+        name: f.name,
+        mimeType: f.mimeType ?? "application/octet-stream",
+        buffer: typeof f.buffer === "string" ? Buffer.from(f.buffer, "utf8") : Buffer.from(f.buffer),
+    }));
+    return { arg: payloads, names: payloads.map((f) => f.name) };
+}
 // ────────────────────────────────────────────────────────────────────────
 // Factory
 // ────────────────────────────────────────────────────────────────────────
@@ -340,6 +364,10 @@ export function makeLocator(backend, strategy, chain) {
         uncheck: (opts) => act("uncheck", {}, (l) => l.uncheck({ timeout: opts?.timeout })),
         setChecked: (checked, opts) => act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
         selectOption: (values, opts) => read("selectOption", (l) => l.selectOption(values, { timeout: opts?.timeout })),
+        setInputFiles: (files, opts) => {
+            const { arg, names } = lowerInputFiles(files);
+            return act("setInputFiles", { files: names }, (l) => l.setInputFiles(arg, { timeout: opts?.timeout }));
+        },
         hover: (opts) => act("hover", {}, (l) => l.hover({ timeout: opts?.timeout })),
         focus: (opts) => act("focus", {}, (l) => l.focus({ timeout: opts?.timeout })),
         blur: (opts) => act("blur", {}, (l) => l.blur({ timeout: opts?.timeout })),

package/dist/project-files.d.ts

@@ -0,0 +1,18 @@
+/** The extracted repo — `ctx.projectRoot`. */
+export declare const WORKSPACE: string;
+/** The app dir; the user's `spectest/` sits directly under it. */
+export declare const APP_DIR: string;
+/**
+ * Absolute in-VM path for a path in the user's repo. Absolute input is
+ * returned as-is. A relative path resolves against the project, preferring the
+ * copy that a warm start refreshes (see the header).
+ *
+ * A file that is missing everywhere resolves to its /workspace candidate, so
+ * the caller's own `fs` error names a real path — `readProjectFile` keeps
+ * reporting ENOENT the way it always has.
+ */
+export declare function resolveProjectPath(p: string): string;
+/** {@link resolveProjectPath}, but a missing file is an error that names every
+ *  place we looked. For inputs a user hands us by name — a fixture — where an
+ *  ENOENT on one guessed path reads as a spectest bug rather than a typo. */
+export declare function resolveExistingProjectPath(p: string, what?: string): string;

package/dist/project-files.js

@@ -0,0 +1,97 @@
+// Where a path in the user's repo lands inside the VM.
+//
+// The project exists in the guest TWICE, and the two copies are not refreshed
+// at the same time (see `env.rs`):
+//
+//   /workspace                    the whole repo. Written by a cold or delta
+//                                 start only — a warm start never re-uploads it.
+//   /opt/spectest/app/spectest    the user's `spectest/` directory. Re-uploaded
+//                                 on EVERY start, warm ones included.
+//
+// A warm start happens only when the warm-template hash matches, so /workspace
+// is correct for every file that is IN that hash. It can be behind for the two
+// kinds of file the hash excludes: `spectest/tests/**` (excluded so a test-only
+// edit keeps the fast start) and anything a project lists in
+// `spectest/.envignore`.
+//
+// Hence the rule below: a path under `spectest/` resolves against the app copy
+// first, because that copy is always current — this is what lets a fixture live
+// in `spectest/tests/fixtures/` and still be found after it was added. Any
+// other path resolves against /workspace, which the hash keeps current.
+//
+// The remaining hole is a file that `.envignore` excludes AND that sits outside
+// `spectest/`: /workspace holds whatever the cold start uploaded, so a later
+// edit is invisible. Nothing can repair those bytes at read time, so we refuse
+// to read them instead of returning stale content. The control plane writes the
+// exact path list it excluded (env.rs) into ENV_IGNORED_FILE.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/** The extracted repo — `ctx.projectRoot`. */
+export const WORKSPACE = process.env.SPECTEST_WORKSPACE ?? "/workspace";
+/** The app dir; the user's `spectest/` sits directly under it. */
+export const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+/** Paths (repo-relative) the warm-template hash skipped because of
+ *  `spectest/.envignore`. Written by the control plane at env start; absent
+ *  when the project ships no `.envignore`. */
+const ENV_IGNORED_FILE = "/run/spectest-env-ignored.json";
+let _envIgnored;
+function envIgnored() {
+    if (_envIgnored)
+        return _envIgnored;
+    let paths = [];
+    try {
+        const raw = JSON.parse(readFileSync(ENV_IGNORED_FILE, "utf8"));
+        paths = raw.paths ?? [];
+    }
+    catch {
+        /* No file (no .envignore, or an older env) — nothing to refuse. */
+    }
+    _envIgnored = new Set(paths);
+    return _envIgnored;
+}
+/** Repo-relative form of `p`: no leading `./`, POSIX separators. */
+function relative(p) {
+    return path.normalize(p).replace(/^\.\//, "").replace(/^\/+/, "");
+}
+/**
+ * Absolute in-VM path for a path in the user's repo. Absolute input is
+ * returned as-is. A relative path resolves against the project, preferring the
+ * copy that a warm start refreshes (see the header).
+ *
+ * A file that is missing everywhere resolves to its /workspace candidate, so
+ * the caller's own `fs` error names a real path — `readProjectFile` keeps
+ * reporting ENOENT the way it always has.
+ */
+export function resolveProjectPath(p) {
+    if (path.isAbsolute(p))
+        return p;
+    const rel = relative(p);
+    if (rel.startsWith("spectest/")) {
+        const app = path.join(APP_DIR, rel);
+        if (existsSync(app))
+            return app;
+    }
+    if (envIgnored().has(rel)) {
+        throw new Error(`project file "${p}" is excluded by spectest/.envignore, so the copy in the VM ` +
+            `is whatever a cold start uploaded and can be out of date. Move it under ` +
+            `spectest/tests/ (still cache-free, and always re-uploaded), or drop the pattern.`);
+    }
+    return path.join(WORKSPACE, rel);
+}
+/** {@link resolveProjectPath}, but a missing file is an error that names every
+ *  place we looked. For inputs a user hands us by name — a fixture — where an
+ *  ENOENT on one guessed path reads as a spectest bug rather than a typo. */
+export function resolveExistingProjectPath(p, what = "file") {
+    const resolved = resolveProjectPath(p);
+    if (existsSync(resolved))
+        return resolved;
+    const rel = relative(p);
+    const looked = path.isAbsolute(p)
+        ? [p]
+        : rel.startsWith("spectest/")
+            ? [path.join(APP_DIR, rel), path.join(WORKSPACE, rel)]
+            : [path.join(WORKSPACE, rel)];
+    throw new Error(`${what} "${p}" is not in the VM (looked in ${looked.join(", ")}). Paths are ` +
+        `relative to your repo root. Check that the file is committed and not ` +
+        `excluded by .gitignore/.spectestignore.`);
+}

package/dist/recorder.d.ts

@@ -394,6 +394,9 @@ export interface BrowserEvent extends BaseEvent {
     key?: string;
     /** Attribute name (getAttribute). */
     attribute?: string;
+    /** File names given to an `<input type="file">` (setInputFiles). Names
+     *  only — a built file's bytes stay out of the timeline. */
+    files?: string[];
     /** Scroll/click coordinates. */
     dx?: number;
     dy?: number;

package/package.json

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

package/src/browser.ts

@@ -2092,4 +2092,5 @@ export interface RecordableFields {
   attempts: number;
   artifactId: string;
   attribute: string;
+  files: string[];
 }

package/src/daemon.ts

@@ -57,6 +57,7 @@ import {
   sanitizeSegment,
 } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import {
   isTextualContentType,
   looksBinary,
@@ -180,7 +181,6 @@ function namedServices(cfg: EnvironmentConfig): NamedService[] {
 
 const DEFAULT_TEST_TIMEOUT_MS = 60_000;
 const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
-const WORKSPACE = process.env.SPECTEST_WORKSPACE ?? "/workspace";
 
 // Stable hostname every service container resolves to the host (the
 // `spectest-br0` gateway) — so apps that build or pull images at runtime
@@ -207,7 +207,9 @@ function hostCacheGateway(): string | null {
   }
   return _hostCacheGateway;
 }
-const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+// WORKSPACE (/workspace) and APP_DIR (/opt/spectest/app) both live in
+// project-files.ts, next to the rule that decides which copy of a project
+// file is the current one.
 // The bun the base snapshot installs (base.rs::BASE_SETUP_SH). The daemon
 // runs under it, and eval's dependency install shells out to it.
 const BUN_BIN = "/usr/local/bin/bun";
@@ -1328,11 +1330,23 @@ async function runContainer(
   }
 }
 
-async function probeTcp(host: string, port: number): Promise<boolean> {
+/** What a readiness probe saw. `detail` is what the plain boolean used to
+ *  throw away, and it is the difference between the two ways a probe fails:
+ *  it ran and said no (a service that isn't up yet, a file a build never
+ *  produced) versus it never got to run (a docker daemon or a guest too
+ *  starved to answer inside the probe's own timeout). The failure message
+ *  carries the last one, since a `sleep infinity` service has no container
+ *  logs to fall back on. */
+interface ProbeOutcome {
+  ok: boolean;
+  detail: string;
+}
+
+async function probeTcp(host: string, port: number): Promise<ProbeOutcome> {
   return new Promise((resolve) => {
     const sock = net.createConnection({ host, port });
     let settled = false;
-    const finish = (v: boolean) => {
+    const finish = (ok: boolean, detail: string) => {
       if (settled) return;
       settled = true;
       try {
@@ -1340,12 +1354,16 @@ async function probeTcp(host: string, port: number): Promise<boolean> {
       } catch {
         /* ignore */
       }
-      resolve(v);
+      resolve({ ok, detail });
     };
     sock.setTimeout(2000);
-    sock.once("connect", () => finish(true));
-    sock.once("error", () => finish(false));
-    sock.once("timeout", () => finish(false));
+    sock.once("connect", () => finish(true, `connected to ${host}:${port}`));
+    sock.once("error", (err: Error) =>
+      finish(false, `connect to ${host}:${port} failed: ${err.message}`),
+    );
+    sock.once("timeout", () =>
+      finish(false, `connect to ${host}:${port} got no reply within 2000ms`),
+    );
   });
 }
 
@@ -1355,52 +1373,92 @@ async function probeHttp(
   urlPath: string,
   headers?: Record<string, string>,
   expectStatus?: number,
-): Promise<boolean> {
+): Promise<ProbeOutcome> {
+  const url = `http://${host}:${port}${urlPath}`;
   const ctrl = new AbortController();
   const to = setTimeout(() => ctrl.abort(), 5000);
   try {
-    const res = await fetch(`http://${host}:${port}${urlPath}`, {
-      signal: ctrl.signal,
-      headers,
-    });
-    return expectStatus !== undefined ? res.status === expectStatus : res.ok;
-  } catch {
-    return false;
+    const res = await fetch(url, { signal: ctrl.signal, headers });
+    const ok = expectStatus !== undefined ? res.status === expectStatus : res.ok;
+    const want = expectStatus !== undefined ? String(expectStatus) : "2xx";
+    return { ok, detail: `GET ${url} → ${res.status} (wanted ${want})` };
+  } catch (err) {
+    const e = err as Error;
+    const detail =
+      e?.name === "AbortError"
+        ? `GET ${url} got no reply within 5000ms`
+        : `GET ${url} failed: ${e?.message ?? String(err)}`;
+    return { ok: false, detail };
   } finally {
     clearTimeout(to);
   }
 }
 
-async function probeExec(name: string, command: string): Promise<boolean> {
+async function probeExec(name: string, command: string): Promise<ProbeOutcome> {
   const r = await docker(["exec", name, "sh", "-c", command], 10_000);
-  return r.code === 0;
+  if (r.code === 0) return { ok: true, detail: `\`${command}\` exited 0` };
+  // 124 is shx's own kill (see `shx`): the exec never answered, which says
+  // the docker daemon is wedged or starved rather than anything about the
+  // command's verdict.
+  const why =
+    r.code === 124
+      ? `was killed after 10000ms with no reply`
+      : `exited ${r.code}`;
+  const output = firstLine(r.stderr) || firstLine(r.stdout);
+  return {
+    ok: false,
+    detail: `\`${command}\` ${why}${output ? `: ${output}` : ""}`,
+  };
+}
+
+/** First non-empty line, trimmed and capped — probe output goes into an
+ *  error message, not a log file. */
+function firstLine(s: string): string {
+  const line = s.split("\n").find((l) => l.trim().length > 0)?.trim() ?? "";
+  return line.length > 200 ? `${line.slice(0, 200)}…` : line;
 }
 
 async function waitForReady(svc: NamedService): Promise<void> {
   const check: ReadyCheck | undefined = svc.readyCheck;
   if (!check) return;
   const timeoutSecs = check.timeoutSecs ?? 60;
+  let last: ProbeOutcome | undefined;
   const probe = async (): Promise<boolean> => {
-    if (check.type === "tcp") return probeTcp(svc.name, check.port);
-    if (check.type === "http") {
-      return probeHttp(
+    if (check.type === "tcp") last = await probeTcp(svc.name, check.port);
+    else if (check.type === "http") {
+      last = await probeHttp(
         svc.name,
         check.port,
         check.path ?? "/",
         check.headers,
         check.expectStatus,
       );
-    }
-    return probeExec(svc.name, check.command);
+    } else last = await probeExec(svc.name, check.command);
+    return last.ok;
   };
   // Scheduling (the ramp, and not sleeping past the deadline) lives in
   // `harness/ready-poll.ts`; this supplies the probe and the diagnosis.
-  const { ready } = await pollUntilReady(probe, { kind: check.type, timeoutSecs });
+  const { ready, attempts, elapsedMs } = await pollUntilReady(probe, {
+    kind: check.type,
+    timeoutSecs,
+  });
   if (ready) return;
+  // The attempt count is half the diagnosis: a probe with a 10s timeout of
+  // its own can only run a handful of times in 60s, so "6 attempts" says the
+  // probes were hanging where "80 attempts" says they ran and kept saying no.
+  let msg =
+    `service ${svc.name} not ready within ${timeoutSecs}s ` +
+    `(${attempts} ${check.type} probe${attempts === 1 ? "" : "s"} over ${
+      Math.round(elapsedMs / 100) / 10
+    }s).`;
+  if (last) msg += `\nLast probe: ${last.detail}`;
   const logs = await docker(["logs", "--tail=200", svc.name], 30_000);
-  throw new Error(
-    `service ${svc.name} not ready within ${timeoutSecs}s. Recent container logs:\n${logs.stdout}\n${logs.stderr}`,
-  );
+  const output = `${logs.stdout}\n${logs.stderr}`.trim();
+  // A service that logs nothing (`sleep infinity`, a quiet daemon) used to
+  // get an empty "Recent container logs:" heading, which reads as if the
+  // logs were the evidence and there simply weren't any.
+  msg += output ? `\nRecent container logs:\n${output}` : `\n(the container logged nothing)`;
+  throw new Error(msg);
 }
 
 /** Validate the `dependsOn` graph and return the name→service map used to
@@ -3634,8 +3692,9 @@ async function spectestContext(scope: ContextScope = {}): Promise<SpectestContex
   const execTimeoutMs = scope.service ? COMPONENT_EXEC_DEFAULT_TIMEOUT_MS : undefined;
   return {
     projectRoot: WORKSPACE,
-    readProjectFile: (p: string) =>
-      fs.readFile(path.isAbsolute(p) ? p : path.join(WORKSPACE, p), "utf8"),
+    readProjectFile: (p: string) => fs.readFile(resolveProjectPath(p), "utf8"),
+    readProjectFileBytes: async (p: string) =>
+      new Uint8Array(await fs.readFile(resolveProjectPath(p))),
     exec: (service, command, opts) =>
       componentExec(service, command, opts, execTimeoutMs),
     // Read `globalThis.fetch` at call time: the wrapper is installed for
@@ -4117,41 +4176,42 @@ async function pollCall<T>(
   let success = false;
   let predicateError: unknown;
 
-  // Record all iterations normally. Falsy iterations get truncated
-  // from the recorder so the timeline doesn't fill with polling
-  // noise; the LAST iteration's events stay, then get marked as
-  // children of the wait event so the UI can render them nested.
+  // Record all iterations normally, but keep only the newest one: a new
+  // attempt drops the events the previous attempt emitted, so the timeline
+  // never fills with polling noise. Whichever attempt is last when the loop
+  // ends — the winning one, or the final failed one — stays, and gets marked
+  // as a child of the wait event so the UI can render it nested.
+  //
+  // The failed attempt is kept deliberately. A poll that times out reports
+  // only "timed out after 120000ms (60 attempts)", which says nothing about
+  // WHY: an ingress answering an instant 404 for two minutes and a backend
+  // that never returns look identical in that message. The last attempt's
+  // events carry the status, the body and the duration, which is the whole
+  // difference between "the route was never programmed" and "the app hung".
   const beforePollIdx = recorderEventCount();
   let lastIterStartIdx = beforePollIdx;
-  let keptIterStartIdx = beforePollIdx;
 
   while (Date.now() - start < timeoutMs) {
     attempts += 1;
+    // Drop the *previous* attempt's events, not this one's — its events are
+    // the ones worth keeping until a newer attempt replaces them.
+    recorderTruncate(lastIterStartIdx);
     lastIterStartIdx = recorderEventCount();
     try {
       const v = await fn();
       if (v !== null && v !== undefined && v !== false) {
         value = v as T;
         success = true;
-        keptIterStartIdx = lastIterStartIdx;
         break;
       }
     } catch (err) {
       predicateError = err;
       break;
     }
-    // Failed iteration — drop the events it emitted.
-    recorderTruncate(lastIterStartIdx);
     if (Date.now() - start + intervalMs > timeoutMs) break;
     await new Promise((r) => setTimeout(r, intervalMs));
   }
 
-  if (!success) {
-    // Timeout or predicate error: drop every attempt's events. The
-    // wait event we emit below is the only trace.
-    recorderTruncate(beforePollIdx);
-  }
-
   const errMsg =
     predicateError !== undefined
       ? ((predicateError as Error)?.message ?? String(predicateError))
@@ -4166,11 +4226,11 @@ async function pollCall<T>(
     ...(errMsg !== undefined ? { error: errMsg } : {}),
   }, resv);
 
-  if (success && seq !== undefined) {
+  if (seq !== undefined) {
     // Group the kept iteration's events under the wait so the UI can
     // render them inside the wait card. The wait event itself is the
     // very last entry; markChildren skips it via the seq match.
-    recorderMarkChildren(keptIterStartIdx, seq);
+    recorderMarkChildren(lastIterStartIdx, seq);
   }
 
   if (predicateError !== undefined) throw predicateError;

package/src/index.ts

@@ -58,6 +58,8 @@ export type {
   FilterOptions,
   ClickOptions,
   BoundingBox,
+  FilePayload,
+  InputFiles,
 } from "./locator.js";
 import type { Locator } from "./locator.js";
 import {
@@ -312,6 +314,10 @@ export interface SpectestContext<
   /** Read a project file as UTF-8. Relative paths resolve against
    *  {@link projectRoot}; absolute paths are read as-is. */
   readProjectFile(path: string): Promise<string>;
+  /** Read a project file as bytes — a fixture to post, hash, or compare
+   *  against what the app under test received. Same path rules as
+   *  {@link readProjectFile}. */
+  readProjectFileBytes(path: string): Promise<Uint8Array>;
   /**
    * Run a command inside a service container. Pass an **array** for exact
    * argv with no shell (`["psql", "-f", "-"]`), or a **string** to run via

package/src/locator.ts

@@ -22,9 +22,11 @@
 // author-facing call is exactly one recorded browser event (with its rrweb
 // drain), whatever playwright work it composes underneath.
 
+import { Buffer } from "node:buffer";
 import type { Page, Locator as PWLocator } from "playwright-core";
 import type { RecordableFields } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
+import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 
 /** Default deadline for a locator action/read's target to become actionable.
@@ -79,6 +81,21 @@ export interface ClickOptions {
   modifiers?: Array<"Alt" | "Control" | "Meta" | "Shift">;
 }
 
+/** A file built in the test rather than read from the repo — the argument
+ *  shape playwright's `setInputFiles` takes, with `buffer` widened to a plain
+ *  `Uint8Array`/string and `mimeType` optional. */
+export interface FilePayload {
+  name: string;
+  /** Defaults to `application/octet-stream`. */
+  mimeType?: string;
+  /** Bytes, or text (encoded UTF-8). */
+  buffer: Uint8Array | string;
+}
+
+/** What `setInputFiles` accepts: repo-relative (or absolute) paths, built
+ *  files, or `[]` to clear the input. */
+export type InputFiles = string | string[] | FilePayload | FilePayload[];
+
 export interface TimeoutOption {
   timeout?: number;
 }
@@ -454,6 +471,34 @@ async function stampActionPoint(
   }
 }
 
+/** Fold a {@link InputFiles} argument into the one playwright takes: repo
+ *  paths resolved to their in-VM location (see project-files.ts), built files
+ *  given a default mime type and a real `Buffer`. The names come back too —
+ *  they are what the timeline step shows, and the bytes never go near it. */
+function lowerInputFiles(files: InputFiles): {
+  arg: string[] | { name: string; mimeType: string; buffer: Buffer }[];
+  names: string[];
+} {
+  const many = Array.isArray(files) ? files : [files];
+  // `[]` clears the input, and every() is true for it — so an empty call
+  // lands here and lowers to an empty path list, which is what clears.
+  if (many.every((f) => typeof f === "string")) {
+    const paths = (many as string[]).map((f) => resolveExistingProjectPath(f, "fixture"));
+    return { arg: paths, names: paths.map((p) => p.split("/").pop() ?? p) };
+  }
+  if (many.some((f) => typeof f === "string")) {
+    throw new Error(
+      "setInputFiles: pass either repo paths or built files — not both in one call",
+    );
+  }
+  const payloads = (many as FilePayload[]).map((f) => ({
+    name: f.name,
+    mimeType: f.mimeType ?? "application/octet-stream",
+    buffer: typeof f.buffer === "string" ? Buffer.from(f.buffer, "utf8") : Buffer.from(f.buffer),
+  }));
+  return { arg: payloads, names: payloads.map((f) => f.name) };
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // The Locator interface
 // ────────────────────────────────────────────────────────────────────────
@@ -513,6 +558,25 @@ export interface Locator {
     values: string | string[] | { label?: string; value?: string; index?: number },
     opts?: TimeoutOption,
   ): Promise<Wrapped<string[]>>;
+  /**
+   * Give an `<input type="file">` its files — the upload primitive, since a
+   * browser refuses a script-set value on a file input. Targets the control a
+   * `<label>` points at, and does **not** require the input to be visible, so
+   * the hidden input behind a drop zone or a styled "Choose file" button is
+   * the thing to select.
+   *
+   * A string is a path in your repo, relative to `ctx.projectRoot` (absolute
+   * paths are taken as-is) — keep fixtures in `spectest/tests/fixtures/`, which
+   * is out of the environment cache key, so adding one still gives a warm
+   * start. Pass a {@link FilePayload} instead for a file the test builds, and
+   * `[]` to clear the input.
+   *
+   * ```ts
+   * await b.locator("#file").setInputFiles("spectest/tests/fixtures/invoice.pdf");
+   * await b.getByLabel("Avatar").setInputFiles({ name: "a.txt", buffer: "hi" });
+   * ```
+   */
+  setInputFiles(files: InputFiles, opts?: TimeoutOption): Promise<void>;
   hover(opts?: TimeoutOption): Promise<void>;
   focus(opts?: TimeoutOption): Promise<void>;
   blur(opts?: TimeoutOption): Promise<void>;
@@ -663,6 +727,12 @@ export function makeLocator(
       act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
     selectOption: (values, opts) =>
       read("selectOption", (l) => l.selectOption(values as never, { timeout: opts?.timeout })),
+    setInputFiles: (files, opts) => {
+      const { arg, names } = lowerInputFiles(files);
+      return act("setInputFiles", { files: names }, (l) =>
+        l.setInputFiles(arg, { timeout: opts?.timeout }),
+      );
+    },
     hover: (opts) => act("hover", {}, (l) => l.hover({ timeout: opts?.timeout })),
     focus: (opts) => act("focus", {}, (l) => l.focus({ timeout: opts?.timeout })),
     blur: (opts) => act("blur", {}, (l) => l.blur({ timeout: opts?.timeout })),

package/src/project-files.ts

@@ -0,0 +1,103 @@
+// Where a path in the user's repo lands inside the VM.
+//
+// The project exists in the guest TWICE, and the two copies are not refreshed
+// at the same time (see `env.rs`):
+//
+//   /workspace                    the whole repo. Written by a cold or delta
+//                                 start only — a warm start never re-uploads it.
+//   /opt/spectest/app/spectest    the user's `spectest/` directory. Re-uploaded
+//                                 on EVERY start, warm ones included.
+//
+// A warm start happens only when the warm-template hash matches, so /workspace
+// is correct for every file that is IN that hash. It can be behind for the two
+// kinds of file the hash excludes: `spectest/tests/**` (excluded so a test-only
+// edit keeps the fast start) and anything a project lists in
+// `spectest/.envignore`.
+//
+// Hence the rule below: a path under `spectest/` resolves against the app copy
+// first, because that copy is always current — this is what lets a fixture live
+// in `spectest/tests/fixtures/` and still be found after it was added. Any
+// other path resolves against /workspace, which the hash keeps current.
+//
+// The remaining hole is a file that `.envignore` excludes AND that sits outside
+// `spectest/`: /workspace holds whatever the cold start uploaded, so a later
+// edit is invisible. Nothing can repair those bytes at read time, so we refuse
+// to read them instead of returning stale content. The control plane writes the
+// exact path list it excluded (env.rs) into ENV_IGNORED_FILE.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/** The extracted repo — `ctx.projectRoot`. */
+export const WORKSPACE = process.env.SPECTEST_WORKSPACE ?? "/workspace";
+/** The app dir; the user's `spectest/` sits directly under it. */
+export const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+
+/** Paths (repo-relative) the warm-template hash skipped because of
+ *  `spectest/.envignore`. Written by the control plane at env start; absent
+ *  when the project ships no `.envignore`. */
+const ENV_IGNORED_FILE = "/run/spectest-env-ignored.json";
+
+let _envIgnored: Set<string> | undefined;
+function envIgnored(): Set<string> {
+  if (_envIgnored) return _envIgnored;
+  let paths: string[] = [];
+  try {
+    const raw = JSON.parse(readFileSync(ENV_IGNORED_FILE, "utf8")) as { paths?: string[] };
+    paths = raw.paths ?? [];
+  } catch {
+    /* No file (no .envignore, or an older env) — nothing to refuse. */
+  }
+  _envIgnored = new Set(paths);
+  return _envIgnored;
+}
+
+/** Repo-relative form of `p`: no leading `./`, POSIX separators. */
+function relative(p: string): string {
+  return path.normalize(p).replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+/**
+ * Absolute in-VM path for a path in the user's repo. Absolute input is
+ * returned as-is. A relative path resolves against the project, preferring the
+ * copy that a warm start refreshes (see the header).
+ *
+ * A file that is missing everywhere resolves to its /workspace candidate, so
+ * the caller's own `fs` error names a real path — `readProjectFile` keeps
+ * reporting ENOENT the way it always has.
+ */
+export function resolveProjectPath(p: string): string {
+  if (path.isAbsolute(p)) return p;
+  const rel = relative(p);
+  if (rel.startsWith("spectest/")) {
+    const app = path.join(APP_DIR, rel);
+    if (existsSync(app)) return app;
+  }
+  if (envIgnored().has(rel)) {
+    throw new Error(
+      `project file "${p}" is excluded by spectest/.envignore, so the copy in the VM ` +
+        `is whatever a cold start uploaded and can be out of date. Move it under ` +
+        `spectest/tests/ (still cache-free, and always re-uploaded), or drop the pattern.`,
+    );
+  }
+  return path.join(WORKSPACE, rel);
+}
+
+/** {@link resolveProjectPath}, but a missing file is an error that names every
+ *  place we looked. For inputs a user hands us by name — a fixture — where an
+ *  ENOENT on one guessed path reads as a spectest bug rather than a typo. */
+export function resolveExistingProjectPath(p: string, what = "file"): string {
+  const resolved = resolveProjectPath(p);
+  if (existsSync(resolved)) return resolved;
+  const rel = relative(p);
+  const looked = path.isAbsolute(p)
+    ? [p]
+    : rel.startsWith("spectest/")
+      ? [path.join(APP_DIR, rel), path.join(WORKSPACE, rel)]
+      : [path.join(WORKSPACE, rel)];
+  throw new Error(
+    `${what} "${p}" is not in the VM (looked in ${looked.join(", ")}). Paths are ` +
+      `relative to your repo root. Check that the file is committed and not ` +
+      `excluded by .gitignore/.spectestignore.`,
+  );
+}

package/src/recorder.ts

@@ -445,6 +445,9 @@ export interface BrowserEvent extends BaseEvent {
   key?: string;
   /** Attribute name (getAttribute). */
   attribute?: string;
+  /** File names given to an `<input type="file">` (setInputFiles). Names
+   *  only — a built file's bytes stay out of the timeline. */
+  files?: string[];
   /** Scroll/click coordinates. */
   dx?: number;
   dy?: number;