@jterrazz/test 15.1.1 → 15.3.0

package/README.md

@@ -147,19 +147,22 @@ test('shows the events feed behind its deep link', async () => {
 });
 ```
 
-Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()`, `.fetch()`, `.visit()`, `.open()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
+Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()`, `.call()`, `.fetch()`, `.visit()`, `.open()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
 
-## The five constructors
+## The six constructors
 
 One constructor per tested interface, each returning a record destructured with its canonical name:
 
-| Constructor                       | Returns                                  | Terminal actions                                             |
-| --------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
-| `specification.api(options)`      | `{ api, cleanup, docker, orchestrator }` | `.request(file)`, `.get()`, `.post()`, `.put()`, `.delete()` |
-| `specification.jobs(options)`     | `{ jobs, cleanup, orchestrator }`        | `.trigger(name)`                                             |
-| `specification.cli(bin, options)` | `{ cli, cleanup, docker, orchestrator }` | `.exec(args, { waitFor?, timeout? }?)`                       |
-| `specification.website(options)`  | `{ website, cleanup, url }`              | `.fetch(path)`, `.visit(path, scenario?)`                    |
-| `specification.mobile(options)`   | `{ mobile, cleanup, udid }`              | `.open(deepLink?, scenario?)`                                |
+| Constructor                        | Returns                                  | Terminal actions                                             |
+| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
+| `specification.api(options)`       | `{ api, cleanup, docker, orchestrator }` | `.request(file)`, `.get()`, `.post()`, `.put()`, `.delete()` |
+| `specification.jobs(options)`      | `{ jobs, cleanup, orchestrator }`        | `.trigger(name)`                                             |
+| `specification.cli(bin, options)`  | `{ cli, cleanup, docker, orchestrator }` | `.exec(args, { waitFor?, timeout? }?)`                       |
+| `specification.integration(opts?)` | `{ integration, cleanup }`               | `.call((services) => …)`                                     |
+| `specification.website(options)`   | `{ website, cleanup, url }`              | `.fetch(path)`, `.visit(path, scenario?)`                    |
+| `specification.mobile(options)`    | `{ mobile, cleanup, udid }`              | `.open(deepLink?, scenario?)`                                |
+
+A rendered component has no constructor: it starts nothing, so it is reached through the `component` chain directly (docs/16).
 
 ### `specification.api({ services, server, mode?, root? })`
 
@@ -292,16 +295,17 @@ Every artefact a run produces lands under `.artifacts/<tool>/` — one `.gitigno
 
 ### Setup (chainable)
 
-| Method                                  | Facets       | Description                                                                                                 |
-| --------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
-| `.seed("file.sql", { database? })`      | all          | Load SQL from `_seeds/` — `database` is the record key (mandatory with ≥ 2 databases, forbidden with 1)     |
-| `.fixture("file")`                      | cli          | Copy the feature-local `_fixtures/file` into the working directory                                          |
-| `.fixture("$FIXTURES/name/")`           | cli          | Spread the shared `specs/_fixtures/<name>/` project into the cwd (trailing `/` = contents; layers)          |
-| `.env({ KEY: "value" })`                | cli          | Set env vars on the child (`null` unsets, `$WORKDIR` expands, calls merge)                                  |
-| `.headers({ "Accept-Language": "fr" })` | api, website | Set HTTP request headers (merge on top of `.http` file headers, or on the browser context)                  |
-| `.intercept(contracts)`                 | all but cli  | Declare the world: a `defineContracts(...)` composite — MSW on api/jobs, the stub backend on website/mobile |
-| `.intercept(contract)` / `([a, b])`     | all but cli  | A single contract, or an ordered list                                                                       |
-| `.intercept(request, response)`         | all but cli  | Inline pair, for one-off plumbing                                                                           |
+| Method                                  | Facets                          | Description                                                                                                 |
+| --------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `.seed("file.sql", { database? })`      | all                             | Load SQL from `_seeds/` — `database` is the record key (mandatory with ≥ 2 databases, forbidden with 1)     |
+| `.fixture("file")`                      | cli                             | Copy the feature-local `_fixtures/file` into the working directory                                          |
+| `.fixture("$FIXTURES/name/")`           | cli                             | Spread the shared `specs/_fixtures/<name>/` project into the cwd (trailing `/` = contents; layers)          |
+| `.env({ KEY: "value" })`                | cli                             | Set env vars on the child (`null` unsets, `$WORKDIR` expands, calls merge)                                  |
+| `.headers({ "Accept-Language": "fr" })` | api, website                    | Set HTTP request headers (merge on top of `.http` file headers, or on the browser context)                  |
+| `.intercept(contracts)`                 | all but cli                     | Declare the world: a `defineContracts(...)` composite — MSW on api/jobs, the stub backend on website/mobile |
+| `.intercept(contract)` / `([a, b])`     | all but cli                     | A single contract, or an ordered list                                                                       |
+| `.intercept(request, response)`         | all but cli                     | Inline pair, for one-off plumbing                                                                           |
+| `.clock("2026-03-04T09:30:00Z")`        | api, jobs, integration, website | Pin the calendar for this chain — the page's on website, this process's elsewhere                           |
 
 ### Actions (terminal)
 
@@ -444,23 +448,28 @@ test('deploy spawns a labelled container', async () => {
 
 `sqlite()` caches its schema template inside the project — `.artifacts/vitest/sqlite/template-<key>.sqlite` — so two checkouts never share one, and workers racing for a cold cache wait for the one that is building rather than all building at once. Details: [docs/11-services.md](docs/11-services.md#where-the-template-lives).
 
-## Mocking utilities
+## Also exported
 
-```typescript
-import { mockOf, mockOfDate } from '@jterrazz/test';
-```
+Everything below comes from the package root (rule F1) — except the project helpers, which are `@jterrazz/test/vitest`'s. One line each; the chapter owns the detail.
 
-| Export        | Description                                                  |
-| ------------- | ------------------------------------------------------------ |
-| `mockOf<T>()` | Deep mock of any interface (wraps `vitest-mock-extended`)    |
-| `mockOfDate`  | Freeze/reset the global Date via `.set(date)` and `.reset()` |
+| Export                                                                                 | Is                                                                                                                  | Chapter                                                                         |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `clock.at(iso)` · `.run(iso?)` · `.advance(ms)`                                        | The one time primitive — a `using` scope that pins `Date`, replacing `vi.useFakeTimers()` and `mockOfDate`          | [docs/12](docs/12-conventions.md#time--one-primitive-two-depths)                |
+| `intercept(…)`                                                                         | The same network double with no chain: `await using _ = await intercept(…)` in a module test                        | [docs/10](docs/10-contracts.md#intercept--the-same-double-with-no-chain)        |
+| `process({ command, ready?, … })`                                                      | The one shape an external process takes — a dev server, an API, a bundler, owned by the runner                      | [docs/11](docs/11-services.md#process--the-one-shape-an-external-process-takes) |
+| `http.stream(chunks, init?)` · `http.sse(events)`                                      | A chunked or server-sent response body a contract replies with                                                      | [docs/10](docs/10-contracts.md)                                                 |
+| `mockOf<T>()` · `mockOf<T>({ deep: false })`                                           | Deep double of a port (a member never stubbed answers with another double), or the flat one                         | [docs/12](docs/12-conventions.md#the-doubles-ladder)                            |
+| `mockOfDate`                                                                           | Freeze/reset the global `Date` via `.set(date)` / `.reset()` — `clock` is what replaces it                          | [docs/12](docs/12-conventions.md#time--one-primitive-two-depths)                |
+| `required(value, why)`                                                                 | The value, or a failure naming what was missing and why it mattered — instead of `!`                                | [docs/08](docs/08-assertions.md#two-helpers-that-are-not-matchers)              |
+| `waitUntil(predicate, { timeout?, interval?, why? })`                                  | Wait on a CONDITION, never a duration, on a real-time budget a pinned clock cannot starve                           | [docs/08](docs/08-assertions.md#two-helpers-that-are-not-matchers)              |
+| `unit()` `component()` `api()` `jobs()` `cli()` `integration()` `website()` `mobile()` | The vitest project helpers, each taking `{ include, exclude, timeout, serial }` on top of the project it already is | [docs/02](docs/02-developing.md#vitest-config-the-preset)                       |
 
 ## Conventions
 
 Normative rules live in the constitution ([docs/12-conventions.md](docs/12-conventions.md)); the generated per-rule catalogue is [docs/13-linting.md](docs/13-linting.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
 
 ```
-specs/<facet>/                  # api | jobs | cli | integrations | lint
+specs/<facet>/                  # api | jobs | cli | integration | website | mobile
 ├── <facet>.specification.ts    # runner(s) at the facet ROOT (rule C1)
 └── <domain>/                   # a product command/area — 1..n test files
     ├── <aspect>.test.ts
@@ -485,7 +494,7 @@ These conventions are not just prose: the package ships an oxlint plugin (`@jter
 - **vitest** - peer dependency
 - **playwright** - optional peer dependency, only needed for `.visit()`: `npm install -D playwright && npx playwright install chromium`
 - **appium + webdriverio** - optional peer dependencies, only needed for `specification.mobile()`: `npm install -D appium webdriverio && npx appium driver install xcuitest` — plus Xcode, a simulator, and the app installed on it
-- **msw** - bundled as a direct dependency (powers `.intercept()`); no separate install
+- **msw** - bundled as a direct dependency (powers `.intercept()` on a chain and `intercept()` in module scope, under node and in a page); no separate install
 - **hono** (or any web framework) - supplied by your project for in-process apps; the adapter only needs an object with a `request()` method, so it is not a peer
 
 ## Docs

package/dist/ambiguity.js

@@ -19,14 +19,20 @@ const CONSTRUCTORS = {
 	button: "button",
 	complementary: "complementary",
 	contentinfo: "contentinfo",
+	dialog: "dialog",
 	field: "field",
 	form: "form",
 	heading: "heading",
 	link: "link",
+	listitem: "listitem",
 	main: "main",
 	navigation: "navigation",
+	option: "option",
 	region: "region",
+	row: "row",
 	search: "search",
+	status: "status",
+	table: "table",
 	testId: "testId",
 	text: "content"
 };
@@ -62,12 +68,22 @@ function formatBare(element) {
 /** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
 function formatMatch(match, index) {
 	const attribute = match.detail ? ` ${quoteDetail(match)}` : "";
+	const named = match.accessibleName ? `  named ${JSON.stringify(match.accessibleName)}` : "";
 	const context = match.context ? `  in <${match.context}>` : "";
-	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${context}`;
+	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${named}${context}`;
 }
 function quoteDetail(match) {
 	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
 }
+/** Each landmark the candidates sit in, and how many of them it holds. */
+function landmarkCounts(matches) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		const landmark = match.context === void 0 ? void 0 : CONTEXT_LANDMARKS[match.context];
+		if (landmark !== void 0) counts.set(landmark, (counts.get(landmark) ?? 0) + 1);
+	}
+	return [...counts].toSorted(([, a], [, b]) => a - b);
+}
 /**
 * The rewrites worth offering, in the order they should be tried. Scoping is
 * always available; `exact` only when it would actually narrow the set, and
@@ -76,9 +92,12 @@ function quoteDetail(match) {
 */
 function formatFixes(element, matches) {
 	const fixes = [];
-	const landmarks = [...new Set(matches.map((match) => match.context && CONTEXT_LANDMARKS[match.context]).filter((landmark) => Boolean(landmark)))];
-	if (landmarks.length > 0 && !element.scope) fixes.push(`scope it       within(${landmarks[0]}, ${formatBare(element)})${landmarks.length > 1 ? `   [also here: ${landmarks.slice(1).join(", ")}]` : ""}`);
-	else if (!element.scope) fixes.push(`scope it       within(main(), ${formatBare(element)})`);
+	const narrowing = landmarkCounts(matches).filter(([, count]) => count < matches.length);
+	if (!element.scope) {
+		const [first, ...rest] = narrowing;
+		const alsoHere = rest.length > 0 ? `   [also here: ${rest.map(([name]) => name).join(", ")}]` : "";
+		fixes.push(first === void 0 ? `scope it       within(<a container holding only this one>, ${formatBare(element)})` : `scope it       within(${first[0]}, ${formatBare(element)})   [leaves ${first[1]} of ${matches.length}]${alsoHere}`);
+	}
 	if (!element.exact && element.name !== void 0) {
 		const remaining = matches.filter((match) => match.text === element.name).length;
 		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${formatBare({

package/dist/artifacts.js

@@ -1,82 +1,10 @@
 import { i as SpecSyntaxError, l as updateSpecFile, s as readSpecFile } from "./spec-document.js";
 import { a as copyPlan, n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
 import { cpSync, existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { execSync, spawn } from "node:child_process";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { execSync, spawn, spawnSync } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import { createServer } from "node:net";
-//#region src/specification/facets/_common/caller.ts
-/** Sibling module tests are callers, not internals (CONVENTIONS I2). */
-const TEST_FILE = /\.test\.[cm]?[jt]s$/u;
-/** Where this very module sits inside the framework's SOURCE tree. */
-const SOURCE_LOCATION = join("specification", "facets", "_common");
-/** The real path of `path`, or `path` itself when it cannot be resolved. */
-function realPath(path) {
-	try {
-		return realpathSync(path);
-	} catch {
-		return path;
-	}
-}
-/**
-* Directory of the running framework module itself. From the built package
-* this is `<package root>/dist`, whatever the resolution path — including a
-* `file:` link, where the real path carries neither `node_modules` nor
-* `/src/…` and would otherwise be mistaken for a caller frame.
-*/
-const FRAMEWORK_DIR = realPath(import.meta.dirname);
-/**
-* The directory holding the framework's OWN modules: `<package>/dist` for a
-* built install (everything is bundled there), `<repo>/src` when the framework
-* runs from source — this module's known location inside that tree is what
-* tells the two apart.
-*/
-const FRAMEWORK_TREE = FRAMEWORK_DIR.endsWith(`${sep}${SOURCE_LOCATION}`) ? resolve(FRAMEWORK_DIR, "../../..") : FRAMEWORK_DIR;
-/** Is `path` inside `directory` (strictly — a directory is not inside itself)? */
-function isInside(directory, path) {
-	const rest = relative(directory, path);
-	return rest !== "" && !rest.startsWith("..") && !isAbsolute(rest);
-}
-/**
-* Is this stack frame a module of the framework itself, rather than of the code
-* calling it?
-*
-* Answered by IDENTITY: the frame is inside the framework's own directory.
-* Answering it by substring — `/src/core/`, `/src/integrations/`, `/src/vitest/`
-* — was answering a different question, "does this path look like the framework's
-* layout", and a consumer that happens to have its own `src/core/` matched it.
-* Its files were then skipped as framework internals, and fixture resolution
-* anchored on the wrong directory (or fell through to the cwd) with nothing
-* reported.
-*
-* @internal
-*/
-function isFrameworkFrame(filePath, frameworkTree = FRAMEWORK_TREE) {
-	if (TEST_FILE.test(filePath)) return false;
-	return isInside(realPath(frameworkTree), realPath(filePath));
-}
-/**
-* Detect the directory of the first stack frame that lives outside this
-* package. Used to anchor fixture resolution (`_seeds/`, `_requests/`,
-* `_expected/`, …) on the calling test / specification file.
-*
-* @internal
-*/
-function getCallerDir() {
-	const { stack } = /* @__PURE__ */ new Error("caller detection");
-	if (!stack) throw new Error("Cannot detect caller directory: no stack trace");
-	const lines = stack.split("\n");
-	for (const line of lines) {
-		const match = /at\s+(?:.*?\()?(?:file:\/\/)?(?<filePath>[^:)]+):\d+:\d+/u.exec(line);
-		if (!match?.groups?.filePath) continue;
-		const { filePath } = match.groups;
-		if (filePath.includes("node_modules")) continue;
-		if (isFrameworkFrame(filePath)) continue;
-		return resolve(filePath, "..");
-	}
-	return process.cwd();
-}
-//#endregion
 //#region src/specification/facets/_common/result/grep.ts
 /**
 * Extract text blocks from output that contain a pattern.
@@ -163,26 +91,6 @@ var TextAccessor = class TextAccessor {
 		return this.text;
 	}
 };
-/**
-* Wrap an arbitrary string into a {@link TextAccessor} anchored on the calling
-* test's directory — the same caller-detection the builders use.
-*
-* The product surface of a test framework is its own error messages, checker
-* output, and reports; those deserve the same goldening as any other output.
-* `text()` makes an ad-hoc string a first-class snapshot subject:
-*
-* ```typescript
-* const message = await catchMessage(() => expect(result.response).toMatch('wrong-body.http'));
-* expect(text(message)).toMatch('wrong-body-error.txt'); // resolves to _expected/
-* ```
-*
-* ANSI is stripped before every comparison (the raw form stays on `.text`),
-* the `{{token}}` grammar applies to the fixture, and `.grep()` composition
-* works exactly as on any stream accessor.
-*/
-function text(value) {
-	return new TextAccessor(value, "text", getCallerDir());
-}
 //#endregion
 //#region src/specification/facets/_common/result/json.ts
 /**
@@ -215,7 +123,13 @@ var JsonAccessor = class {
 		this.transform = transform;
 		this.captures = captures ?? new CaptureScope();
 	}
-	/** The parsed JSON value. Throws if the text is not valid JSON. */
+	/**
+	* The parsed JSON value. Throws if the text is not valid JSON.
+	*
+	* `Value` is `unknown` unless the subject that produced this accessor
+	* knows better — `.call<T>()` does, and hands its T straight through so a
+	* one-field reading needs no cast in the test.
+	*/
 	get value() {
 		const stripped = stripAnsiCodes(this.rawText);
 		const source = this.transform ? this.transform(stripped) : stripped;
@@ -228,45 +142,35 @@ var JsonAccessor = class {
 	}
 };
 //#endregion
-//#region src/integrations/docker/docker-lookup.ts
+//#region src/specification/facets/_common/result/table.ts
 /**
-* Thin synchronous wrappers around the `docker` CLI used by the docker() spec
-* mode. Sync is deliberate — the calls are fast, run only on the host, and
-* keep the dispose path straightforward (`Symbol.asyncDispose` can still be
-* async without needing these to be).
+* Read-only accessor for a database table after a specification run.
+*
+* Assertions go through `expect()` (async — they query the database):
+*
+*     await expect(result.table('users', { database: 'db' })).toMatchRows({
+*         columns: ['name'],
+*         rows: [['Alice']],
+*     });
+*     await expect(result.table('users', { database: 'db' })).toBeEmpty();
 */
-const DEFAULT_TIMEOUT = 1e4;
-/** Return all container IDs (running or stopped) that carry `key=value`. */
-function findContainersByLabel(key, value) {
-	try {
-		return execSync(`docker ps -aq -f label=${key}=${value}`, {
-			encoding: "utf8",
-			timeout: DEFAULT_TIMEOUT
-		}).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
-	} catch {
-		return [];
+var TableAccessor = class {
+	/** @internal Ref-capture scope shared by the current spec execution. */
+	captures;
+	/** @internal */
+	db;
+	/** The table name this accessor reads. */
+	name;
+	constructor(name, db, captures) {
+		this.name = name;
+		this.db = db;
+		this.captures = captures ?? new CaptureScope();
 	}
-}
-/** Return the raw `docker inspect` payload (object, not array) for a container. */
-function inspectContainer(id) {
-	const raw = execSync(`docker inspect ${id}`, {
-		encoding: "utf8",
-		timeout: DEFAULT_TIMEOUT
-	});
-	const parsed = JSON.parse(raw);
-	return Array.isArray(parsed) ? parsed[0] : parsed;
-}
-/** Force-remove the given container IDs in a single call. Errors are swallowed. */
-function removeContainers(ids) {
-	if (ids.length === 0) return;
-	try {
-		execSync(`docker rm -f ${ids.join(" ")}`, {
-			encoding: "utf8",
-			stdio: "pipe",
-			timeout: DEFAULT_TIMEOUT
-		});
-	} catch {}
-}
+	/** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
+	async query(columns) {
+		return await this.db.query(this.name, columns);
+	}
+};
 //#endregion
 //#region src/specification/matching/structural.ts
 /**
@@ -605,6 +509,46 @@ function mergeTextPreservingPlaceholders(previous, actual, scope) {
 	return merged.join("\n");
 }
 //#endregion
+//#region src/integrations/docker/docker-lookup.ts
+/**
+* Thin synchronous wrappers around the `docker` CLI used by the docker() spec
+* mode. Sync is deliberate — the calls are fast, run only on the host, and
+* keep the dispose path straightforward (`Symbol.asyncDispose` can still be
+* async without needing these to be).
+*/
+const DEFAULT_TIMEOUT = 1e4;
+/** Return all container IDs (running or stopped) that carry `key=value`. */
+function findContainersByLabel(key, value) {
+	try {
+		return execSync(`docker ps -aq -f label=${key}=${value}`, {
+			encoding: "utf8",
+			timeout: DEFAULT_TIMEOUT
+		}).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	} catch {
+		return [];
+	}
+}
+/** Return the raw `docker inspect` payload (object, not array) for a container. */
+function inspectContainer(id) {
+	const raw = execSync(`docker inspect ${id}`, {
+		encoding: "utf8",
+		timeout: DEFAULT_TIMEOUT
+	});
+	const parsed = JSON.parse(raw);
+	return Array.isArray(parsed) ? parsed[0] : parsed;
+}
+/** Force-remove the given container IDs in a single call. Errors are swallowed. */
+function removeContainers(ids) {
+	if (ids.length === 0) return;
+	try {
+		execSync(`docker rm -f ${ids.join(" ")}`, {
+			encoding: "utf8",
+			stdio: "pipe",
+			timeout: DEFAULT_TIMEOUT
+		});
+	} catch {}
+}
+//#endregion
 //#region src/specification/facets/_common/result/directory.ts
 const DEFAULT_IGNORES = [
 	".git",
@@ -811,36 +755,6 @@ function expandWorkdir(env, workDir) {
 	return expanded;
 }
 //#endregion
-//#region src/specification/facets/_common/result/table.ts
-/**
-* Read-only accessor for a database table after a specification run.
-*
-* Assertions go through `expect()` (async — they query the database):
-*
-*     await expect(result.table('users', { database: 'db' })).toMatchRows({
-*         columns: ['name'],
-*         rows: [['Alice']],
-*     });
-*     await expect(result.table('users', { database: 'db' })).toBeEmpty();
-*/
-var TableAccessor = class {
-	/** @internal Ref-capture scope shared by the current spec execution. */
-	captures;
-	/** @internal */
-	db;
-	/** The table name this accessor reads. */
-	name;
-	constructor(name, db, captures) {
-		this.name = name;
-		this.db = db;
-		this.captures = captures ?? new CaptureScope();
-	}
-	/** @internal Query the table — used by the toMatchRows / toBeEmpty matchers. */
-	async query(columns) {
-		return await this.db.query(this.name, columns);
-	}
-};
-//#endregion
 //#region src/specification/facets/_common/result/result.ts
 /**
 * Base result - common accessors available after any action type.
@@ -1351,6 +1265,16 @@ function shouldUpdateSnapshots() {
 }
 /** Standard hint appended to missing-fixture errors. */
 const UPDATE_HINT = "Run with TEST_UPDATE=1 (or vitest -u) to create it.";
+/**
+* The hint a FROZEN golden gets instead. `{ frozen }` is the switch that tells
+* update mode to leave this file alone, so sending its author to `TEST_UPDATE=1`
+* would send them to a run that does nothing.
+*/
+const FROZEN_HINT = "This golden is `{ frozen }`: update mode never writes it. Write the file by hand, or drop `{ frozen }` for one TEST_UPDATE=1 run and put it back.";
+/** The hint a missing golden earns, given whether it is frozen. */
+function missingHint(frozen) {
+	return frozen ? FROZEN_HINT : UPDATE_HINT;
+}
 //#endregion
 //#region src/specification/facets/website/serve.adapter.ts
 /** Grace period between SIGTERM and the SIGKILL escalation. */
@@ -1408,14 +1332,16 @@ var ServeAdapter = class {
 	}
 	/** Start the server and resolve with its base URL once it is ready. */
 	async start() {
+		this.runBefore();
 		const banner = this.options.ready instanceof RegExp ? this.options.ready : null;
 		const port = banner ? null : this.options.port ?? await findFreePort();
 		const timeout = this.options.timeout ?? DEFAULT_READY_TIMEOUT;
 		this.child = spawn(this.options.command, [], {
-			cwd: this.root,
+			cwd: this.workingDirectory(),
 			detached: process.platform !== "win32",
 			env: {
 				...process.env,
+				...typeof this.options.env === "function" ? {} : this.options.env,
 				...this.extraEnv,
 				...port === null ? {} : { PORT: String(port) }
 			},
@@ -1476,6 +1402,25 @@ var ServeAdapter = class {
 			}
 		}
 	}
+	/** Where the child runs: the stated `cwd` under the root, or the root. */
+	workingDirectory() {
+		return this.options.cwd === void 0 ? this.root : resolve(this.root, this.options.cwd);
+	}
+	/**
+	* The one-shot command, run before the process is spawned. It must exit 0:
+	* a build that failed is not a spec that failed later on a missing file,
+	* and the difference is what this reports.
+	*/
+	runBefore() {
+		const { before } = this.options;
+		if (before === void 0) return;
+		const outcome = spawnSync(before, [], {
+			cwd: this.workingDirectory(),
+			encoding: "utf8",
+			shell: true
+		});
+		if (outcome.status !== 0) throw new Error(`specification.${this.facet}(): \`before\` exited ${outcome.status ?? "without a status"}.\nCommand: ${before}\nOutput:\n${(outcome.stdout ?? "") + (outcome.stderr ?? "")}`);
+	}
 	/** Terminate the server process group (idempotent). */
 	async stop() {
 		const { child } = this;
@@ -1794,4 +1739,4 @@ const COVERAGE_DIR = `${VITEST_ARTIFACTS_DIR}/coverage`;
 /** Where `sqlite()` caches the schema template it copies per worker. */
 const SQLITE_TEMPLATE_DIR = `${VITEST_ARTIFACTS_DIR}/sqlite`;
 //#endregion
-export { placeholderPatternSource as A, text as B, FilesystemAccessor as C, hasPlaceholders as D, walkDirectory as E, findContainersByLabel as F, inspectContainer as I, removeContainers as L, structuralEquals as M, structuralSubset as N, mergePreservingPlaceholders as O, textEquals as P, JsonAccessor as R, resolveRoot as S, diffDirectories as T, getCallerDir as V, validateDatabaseOption as _, specDescription as a, expandWorkdir as b, shouldUpdateSnapshots as c, formatStartupReport as d, formatStdoutDiff as f, BaseResult as g, CliResult as h, runSpecDocument as i, renderExpected as j, mergeTextPreservingPlaceholders as k, formatDirectoryDiff as l, ContainerAccessor as m, SQLITE_TEMPLATE_DIR as n, ServeAdapter as o, formatTableDiff as p, VITEST_ARTIFACTS_DIR as r, UPDATE_HINT as s, COVERAGE_DIR as t, formatResponseDiff as u, TableAccessor as v, DirectoryAccessor as w, resolveCommand as x, discoverRoot as y, TextAccessor as z };
+export { mergePreservingPlaceholders as A, DirectoryAccessor as C, inspectContainer as D, findContainersByLabel as E, structuralSubset as F, textEquals as I, TableAccessor as L, placeholderPatternSource as M, renderExpected as N, removeContainers as O, structuralEquals as P, JsonAccessor as R, FilesystemAccessor as S, walkDirectory as T, validateDatabaseOption as _, specDescription as a, resolveCommand as b, shouldUpdateSnapshots as c, formatStartupReport as d, formatStdoutDiff as f, BaseResult as g, CliResult as h, runSpecDocument as i, mergeTextPreservingPlaceholders as j, hasPlaceholders as k, formatDirectoryDiff as l, ContainerAccessor as m, SQLITE_TEMPLATE_DIR as n, ServeAdapter as o, formatTableDiff as p, VITEST_ARTIFACTS_DIR as r, missingHint as s, COVERAGE_DIR as t, formatResponseDiff as u, discoverRoot as v, diffDirectories as w, resolveRoot as x, expandWorkdir as y, TextAccessor as z };