@jterrazz/test 15.2.0 → 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/artifacts.js

@@ -2,7 +2,7 @@ import { i as SpecSyntaxError, l as updateSpecFile, s as readSpecFile } from "./
 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, relative, resolve, sep } from "node:path";
-import { execSync, spawn } from "node:child_process";
+import { execSync, spawn, spawnSync } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import { createServer } from "node:net";
 //#region src/specification/facets/_common/result/grep.ts
@@ -123,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;
@@ -1259,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. */
@@ -1316,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) }
 			},
@@ -1384,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;
@@ -1702,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 { 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, UPDATE_HINT as s, COVERAGE_DIR as t, formatResponseDiff as u, discoverRoot as v, diffDirectories as w, resolveRoot as x, expandWorkdir 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 };