@jterrazz/test 16.1.0 → 17.0.0

package/docs/guides/spec-documents.md

@@ -0,0 +1,189 @@
+# Spec documents (`<case>.spec.yaml`)
+
+A terminal session that is data is written as data: one `<case>.spec.yaml` per test, beside the spec it belongs to, stating what the session stands on, the commands it runs and what each left behind. The format is the cli specification's; an api or a job case is a TypeScript spec, its whole result written in place ([Assertions](../reference/assertions.md#one-verb-compares-a-whole-result-and-its-argument-says-where-the-expectation-lives)). This page owns the format, from the key a document opens with to the door that runs it.
+
+- [One file, one test](#one-file-one-test): the unit, and the golden of the whole session
+- [Paths](#paths): `fixture:` names the disk the way `file()` and `directory()` do
+- [A cli document](#a-cli-document): the ground, the runs, what they left behind
+- [The schema and the format](#the-schema-and-the-format)
+- [The three doors, one runner](#the-three-doors-one-runner): the plugin, the bridge, the chain
+- [Failure and update](#failure-and-update) · [When to reach for code](#when-to-reach-for-code)
+
+## One file, one test
+
+A document is ONE test: its `description:` is the vitest title, and nothing in it lists cases. There is no `cases:` key, no `extends:` and no `kind:`. A case inheriting its given from another file is a given no reader sees, and a document describes a cli session and nothing else. What several cases share is composed visibly instead: `fixture:` takes one path or a list, applied in order, so the pool's base and the leaf's delta both stand on the line (`fixture: [../../__fixtures__/shop/, ./__fixtures__/sold-out/]`).
+
+**The assertion is the whole session**: every run's exit code and both its streams, byte for byte, `files:` for what it left on disk. Nothing here is new capability: a document is the chain's semantics in the shape of a data file an editor validates: `fixture:` is `.fixture()`, a run is `.exec()`. The keys, in their canonical order, are `description`, `fixture`, `env`, `serve`, `runs`; `description:` and `runs:` are mandatory.
+
+## Paths
+
+`fixture:` takes a path relative to the document, spelled in full (`./...`, `../...`), and is judged by the four guards a `file()` call is (chapter [Assertions](../reference/assertions.md#one-verb-compares-a-whole-result-and-its-argument-says-where-the-expectation-lives)):
+
+- **Role:** a path whose first ground folder is not `__fixtures__/` is refused by the grammar, on its line, so the checker (`document-follows-its-grammar`) and the runner refuse the same document (`verb-reads-its-ground-folder`'s law, for data).
+- **Locality:** a path leaves its leaf only by climbing: into the ground of a folder that encloses it, or the specs root's shared `<specs>/__fixtures__/` (`no-reach-into-sibling-ground`).
+- **Existence:** every path names an entry git does not ignore, of the kind it names, a directory with its trailing `/` and a file without (`named-path-exists`); at run time a missing one is refused with what it resolved to.
+- **Liveness:** a fixture a document names is referenced, exactly as a `file()` literal references it (`no-unused-ground`, `ground-shared-or-inline`).
+
+## A cli document
+
+A terminal session is already a specification: a command, its exit code, what it printed, what it left on disk. A cli document writes it as that, never under `__expected__/`, which holds goldens, not scenarios.
+
+```yaml
+description: refuses to guess when it is run outside the checkout
+fixture: ../../__fixtures__/repositories-stub/
+env:
+    - frozen
+    - SHOPLY_ORIGIN=http://127.0.0.1:9
+serve:
+    - mcp: { MCP_STUB_WITHHOLD: get-article }
+
+runs:
+    - command: repositories
+      exit: 1
+      stderr: |
+          Error: no directory with home/ and apps/ above the current directory
+          Hint: run inside the shoply checkout
+    - command: repositories --json
+      exit: 0
+      stdout: |
+          {
+              "data": []
+          }
+```
+
+### The ground
+
+| Key        | Shape                                         | Meaning                                                                                                                                                                                                                                                                                                                    |
+| ---------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fixture:` | string or list                                | The two forms the chain's `file()` and `directory()` take; the trailing `/` says which: `./__fixtures__/shop/` spreads a directory's contents, `./__fixtures__/config.toml` copies one file under its own name; a path whose `/` disagrees with the disk is refused. Executable bits preserved. A list **layers** in order |
+| `env:`     | string or list                                | Each entry is either a **bare word** naming an env set registered in code, or `KEY=value` inline (`$WORKDIR` expands, as in `.env()`)                                                                                                                                                                                      |
+| `serve:`   | string, list of strings, or `- name: { ... }` | Servers registered in code, started once **per file** before the first run and shared by all of them. The mapping form adds env to that server                                                                                                                                                                             |
+
+The words `env:` and `serve:` name are registered once per app, in the options of `specification.cli()` ([CLI specs § Registration](cli-specs.md#registration-once-per-app)).
+
+### The runs
+
+`runs:` is a list of at least one run, executed **in order**, all in ONE working directory, and **every** one asserted. This is where the format goes past `.exec([...])`, which stops at the first non-zero exit and keeps only the last output: here a non-zero exit does not end the session, because each exit code is part of what the document states.
+
+**A run is judged the moment it ends**, before the next command starts: its exit code, its streams and its `files:` all read at that one instant. A run that disagrees throws there and then, and the runs below it do not execute: once the sequence has diverged, what the rest would print is a consequence, not a fact about the program.
+
+| Key        | Shape                         | Meaning                                                                                                                                                                                                                                               |
+| ---------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `command:` | **mandatory**                 | The argv AFTER the binary, exactly what `.exec('...')` takes. The binary is the runner's (`specification.cli(bin)`), so naming it here would pass it to itself as the first argument. The line goes through the shell, so quoting behaves identically |
+| `stdin:`   | optional block scalar         | Written to the child, which then reads EOF. Absent keeps the immediately-closed pipe; a TTY is never given                                                                                                                                            |
+| `timeout:` | optional integer              | Milliseconds before the run is killed, its whole process group with it (exit code 124)                                                                                                                                                                |
+| `waitFor:` | optional, **last run only**   | Long-running form: resolve as soon as this text appears, as `.exec(args, { waitFor })` does                                                                                                                                                           |
+| `exit:`    | **mandatory** literal integer | The exit code the command must return                                                                                                                                                                                                                 |
+| `stdout:`  | optional block scalar         | Expected stdout, **byte-exact**. Absent asserts an EMPTY stream                                                                                                                                                                                       |
+| `stderr:`  | optional block scalar         | Expected stderr, byte-exact. Absent asserts an EMPTY stream                                                                                                                                                                                           |
+| `files:`   | optional mapping              | On-disk assertions under the working directory, read the moment THIS run ends (below)                                                                                                                                                                 |
+
+**`|` and `|-` are the whole newline story.** A block scalar written `|` keeps the final newline of its text; `|-` drops it. The comparison is byte-exact against that, so a command whose output ends with `\n` is written `|`, and one that ends mid-line is written `|-`.
+
+### `files:`: what the run left behind
+
+Each key is a path relative to the working directory (never absolute, never escaping it). Each value is one of four forms:
+
+```yaml
+files:
+    .spwn/agent.yaml: { contains: 'name: bot' } # one needle, or a list of them
+    out/report.txt:
+        equals: | # exact text, block scalar allowed
+            ok
+    .spwn/lock: absent # nothing at that path
+    out/src: exists # something at that path
+```
+
+`contains` and `equals` are token-aware: `{ contains: 'wrote {{path}}' }` finds the line whatever the path turned out to be. Each run's mapping is read against the working directory **as that run left it**, so a file may be `absent` for one run and there for the next, which is how a lock, a cache or a build output is described:
+
+```yaml
+description: the lock appears with the first apply and is released by the second
+runs:
+    - command: status
+      exit: 0
+      files:
+          .spwn/lock: absent
+    - command: apply --hold
+      exit: 0
+      files:
+          .spwn/lock: { contains: 'pid: {{int}}' }
+```
+
+## The schema and the format
+
+The document's JSON Schema ships with the package at `schema/spec.schema.json`, published as the `@jterrazz/test/schema` export, and is generated from the grammar's own constants, so it cannot describe a shape the parser does not read. It closes a document on its keys and states every presence law of the grammar (the keys a mapping cannot do without, the keys that cannot stand together) from `PRESENCE`, the one table the parser refuses with. A meta-test holds the other direction: a JSON Schema validator runs it over every document of this repository, each one the parser reads, it validates, and each one the parser refuses, it refuses (except for what no keyword compares: a `waitFor:` on a run before the last, where the schema holds only that one run at most waits), and it breaks every presence law, for both readers alike. Point an editor at it:
+
+```yaml
+# yaml-language-server: $schema=./node_modules/@jterrazz/test/schema/spec.schema.json
+```
+
+A schema says which keys exist, not which ORDER they come in, nor how a stream is written. Both are the document's format, and a formatter owns it, as oxfmt owns a source file's: the canonical order (`description, fixture, env, serve, runs` at the top, then `command, stdin, timeout, waitFor, exit, stdout, stderr, files` in a run) and every stream (`stdout`, `stderr`, `stdin`, `files.*.equals`) as a block scalar, `|` keeping the trailing newline and `|-` dropping it. `typescript fix` (`typescript fix`) writes it; a check run names each document out of it and fails, and no baseline holds one: it is never debt, since the formatter always settles it. The document family of rules is in [Linting](../reference/linting.md).
+
+The whole [token vocabulary](../reference/tokens.md) works in what a document ASSERTS (a run's streams and `files:` texts) and **never** in `description`, `command` or `stdin`, which are prose and inputs.
+
+## The three doors, one runner
+
+| Door       | Use it when                                                                                   |
+| ---------- | --------------------------------------------------------------------------------------------- |
+| **plugin** | The document IS the test, the common case                                                     |
+| **bridge** | The document is the scenario, but one assertion needs code                                    |
+| **chain**  | Everything the format cannot say; see [when to reach for code](#when-to-reach-for-code) below |
+
+**The plugin.** `literate()` from `@jterrazz/test/vitest` adds the `.spec.yaml` glob to a project's include and transforms each document into a one-test module that runs it through the bound specification's `cli`. The runner shows the document's path as the test file and `description:` as the title, so a failing case opens where it is written. The `cli()` project helper wires it:
+
+| `literate`                 | Collects                                                                      |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| omitted                    | every `specs/cli/**/*.spec.yaml`, bound to `./specs/cli/cli.specification.ts` |
+| `{ runner: './other.ts' }` | the same documents, bound to another runner                                   |
+| `{ include: [...] }`       | a narrower glob                                                               |
+| `false`                    | no documents at all, a suite written entirely in code                         |
+
+The `runner` is **stated, never guessed** beyond that convention: a repository may declare several cli runners, and nothing could pick the right one without silently binding a case to the wrong app. The door is the `literate` option of the one `cli` project that collects those documents.
+
+**The bridge.** `cli.run(file('./<case>.spec.yaml'))` runs a document from a spec and resolves with the LAST run's result, so code adds what the document cannot express.
+
+```typescript
+test('scaffolds a shop and leaves the tree we expect', async () => {
+    // Given - the whole session, stated in the document
+    const result = await cli.run(file('./scaffold.spec.yaml'));
+
+    // Then - one assertion the format has no vocabulary for
+    await expect(result.directory('my-shop')).toMatch(directory('./__expected__/shop-scaffold/'));
+});
+```
+
+`.run()` is a DOOR, not a fallback: it stays for a document whose result needs one assertion the grammar has no vocabulary for, or for a document the plugin's glob cannot collect: generated at test time, or an input under `__fixtures__/` whose refusal is the subject of a negative spec. `{ frozen: true }` opts one document out of the update rewrite, the guard `toMatch(file(...), { frozen: true })` is for a golden.
+
+## Failure and update
+
+On a mismatch the failure renders the description, the command that ran, everything the comparison rejected (the exit code, the stream diff, the `files:` entry), and where to open the document, at the run's own line.
+
+A line the comparison ACCEPTED is rendered as equal, with its token, so the marked lines are the mismatch and nothing else. The stack carries one frame: the document's own line.
+
+`TEST_UPDATE=1` rewrites what the run produced and nothing else: each run's `exit`, `stdout` and `stderr`. The ground, the commands and `files:` are stated by hand and never touched, and neither are comments or key order: the YAML document is edited, not re-emitted. Placeholders survive by **pattern match**, so a token stays a token wherever the line moved to: see [update mode](../reference/tokens.md#update-mode-tokens-are-preserved).
+
+## When to reach for code
+
+The format states one subject and one linear story. Reach for the chain when the spec needs:
+
+- **logic:** a loop, a computed value, reasoning across two calls the document cannot relate;
+- **containers:** `docker`-aware runs, `await using`, `result.container(name)`;
+- **parallel fan-out:** several commands that must run at once, or an interleaving;
+- **host shell-outs** the binary under test is not: a `git` call, a build step staged by hand;
+- **structural JSON of a cli run:** `result.json` compared whole to its value;
+- **a refusal of the chain itself:** a directory handed as a body, a database the record lacks.
+
+A document that starts wanting a conditional is a chain wearing a header. Write it in code.
+
+## Pitfalls
+
+- **Putting a `<case>.spec.yaml` under `__expected__/`.** A document is the CASE, not a golden; it lives beside the spec it belongs to (`no-document-in-ground`).
+- **Writing a token in a `description:`, a `command:` or a `stdin:`.** Those are prose and inputs; placeholders work in what is asserted.
+- **Quoting a stream instead of writing a block scalar.** `stdout: "a\nb\n"` is a golden no diff can show. It is out of [the format](#the-schema-and-the-format), and `typescript fix` rewrites it.
+- **A `fixture:` naming a golden's folder.** It reads `__fixtures__/`; `./__expected__/shop/` is refused on its line.
+- **Listing cases in one file, or inheriting a given.** One file is one test, and the given is visible: a list of paths layers, `extends:` does not exist.
+- **Writing an api or a job case as a document.** The format is a cli session's; an api or job case is a spec, its whole result in place; `kind:` is an unknown key.
+
+## Related
+
+[CLI specs](cli-specs.md) · [Assertions](../reference/assertions.md) · [Tokens](../reference/tokens.md) · [Linting](../reference/linting.md)

package/docs/guides/website-specs.md

@@ -0,0 +1,413 @@
+# Website specs (`specification.website`)
+
+`specification.website()` tests a rendered website (its raw HTTP surface: redirects, robots.txt, headers; and its rendered surface: title, head metadata, JSON-LD, console, and full user scenarios) through a real Chromium. It starts the site itself, or targets one already running.
+
+Use it when the subject under test is a browser-rendered page. For a JSON/HTTP API surface use [api](api-specs.md); for a binary use [cli](cli-specs.md).
+
+## What it specifies
+
+A website spec answers one question: **given this backend and this visitor, what does the served site put on the screen, and what does it report to the console?** The subject is the assembled product met through an address (a running server the runner started, or a deployment already up), and everything it reads is what a visitor can see: the rendered text, the accessibility tree, the document head, the console. A single rendered unit inside that page is a component spec ([Component specs](component-specs.md)); a route module or a loader behind it is a module test ([Module tests](module-tests.md)).
+
+## The constructor
+
+Exactly one of `server` (start the site locally) or `url` (target a running site) is required; passing both, or neither, throws immediately.
+
+```typescript
+// specs/website/website.specification.ts
+import { specification } from '@jterrazz/test';
+import { afterAll } from 'vitest';
+
+export const { cleanup, website } = await specification.website({
+    server: { command: 'npm run start', ready: '/' },
+});
+
+afterAll(cleanup);
+```
+
+`command` is how you start the site in production or in preview (`npm run start`, `next start`, `astro preview`), run from the project root, and `ready` is a path the site answers once it is up, usually `/`. The command reads its port from `PORT` ([below](#options)).
+
+```typescript
+// targeting a deployed preview instead of starting one
+export const { cleanup, website } = await specification.website({
+    url: 'https://preview-1234.my-site.pages.dev',
+});
+```
+
+### Options
+
+| Option      | Description                                                                                                                                                                                                                                                       |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server`    | How the site is started locally: a `process()`, the `ProcessOptions` object itself, or `(services) => ...` returning either. Exactly one of `server` / `url`                                                                                                      |
+| `url`       | Target an already-running site (deployed, preview, dev server). Exactly one of `server` / `url`                                                                                                                                                                   |
+| `services`  | A named record started BEFORE the site and stopped with it: a database it reads, a `process()` backend it calls. See [Services beside the site](#services-beside-the-site)                                                                                        |
+| `backend`   | `{ env, port? }`: start a declared stub backend and inject its URL into the server child. Requires `server` mode; see [Declared backend](#declared-backend)                                                                                                       |
+| `external`  | `'allow' \| 'block'`: cross-origin policy for `.visit()`. Default `'block'` with `server`, `'allow'` with `url`; see [Cross-origin policy](#cross-origin-policy-external)                                                                                         |
+| `root`      | **Project-root override** (rule `no-redundant-root`): the cwd of the `server` command. Auto-discovered from the calling file when absent. Not a fixtures root                                                                                                     |
+| `transform` | **Escape hatch only** (rule `no-transform-duplicating-tokens`): a normaliser applied to every compared reading (the head projection and the json-ld among them) before the comparison, for framework noise no token can name. It never mutates what the page said |
+
+`server` is a `ProcessOptions`, whatever of the three forms states it: `command`, `ready`, `port`, `cwd`, `env`, `before`, `timeout`. That shape has one owner, and it is not this page: [Services § `process()`](../reference/services.md#process-the-one-shape-an-external-process-takes) holds every field, because a website's server is an external process like any other the framework owns.
+
+The chosen port is injected as `PORT`; the command reads it the same way it would in production. If the process never answers on `ready` within `timeout`, or exits first, `specification.website()` fails with the command's captured output attached. On teardown the child is ended the way every `process()` is ([Services § `process()`](../reference/services.md#process-the-one-shape-an-external-process-takes)), its own children with it.
+
+The handle destructures to `{ website, cleanup, url }` (rule `no-runner-alias`), no `docker`: a browser is not a container. `url` is the resolved base URL: the one the server started on, or the `url` option with its trailing slash trimmed.
+
+### Services beside the site
+
+A site under test is rarely alone: it reads a database, or it calls an API that must be up before the first page is requested. `services` is that record (the same one every other specification takes, see [Services](../reference/services.md)), started before the site, in declaration order, and stopped with the specification.
+
+That is why `server` may be a FUNCTION of the record: the site is handed the URL of the thing it was started beside, resolved once that thing is listening rather than guessed at config time. The example (a `next dev` beside the API it calls and that API's database) is [Services § `process()`](../reference/services.md#process-the-one-shape-an-external-process-takes)'s.
+
+A declared database is not seeded by the chain; a website chain has no `.seed()`. It is seeded by whatever owns it: the service's own `docker/<service>/init.sql`, or a `before:` command on the `process()` that migrates it.
+
+## The chain
+
+### Two terminal actions: `.fetch()` and `.visit()`
+
+#### `.fetch(path, { method })`: one raw HTTP exchange
+
+`.fetch(path)` performs a single GET, and `.fetch(path, { method: 'POST' })` another method (`DELETE`, `HEAD`, `OPTIONS`, `PATCH`, `PUT`), and never follows redirects: the redirect itself is the result, not something to chase:
+
+```typescript
+test('surfaces a permanent redirect without following it', async () => {
+    // Given - the legacy path
+    const result = await website.fetch('/old');
+
+    // Then - the 308 IS the result, with its target readable
+    expect(result.status).toBe(308);
+    expect(result.location).toBe('/');
+});
+
+test('serves robots.txt as plain text', async () => {
+    // Given - the robots surface
+    const result = await website.fetch('/robots.txt');
+
+    // Then - the whole file matches one golden
+    expect(result.headers['content-type']).toBe('text/plain');
+    expect(result.body).toMatch(file('./__expected__/robots.txt'));
+});
+```
+
+`FetchResult` accessors:
+
+| Member            | Type                  | Description                                                                |
+| ----------------- | --------------------- | -------------------------------------------------------------------------- |
+| `result.status`   | `number`              | HTTP status; 3xx surfaces exactly as sent, never followed                  |
+| `result.location` | `string \| undefined` | The `location` header, or undefined                                        |
+| `result.headers`  | flat map              | Response headers, lower-cased keys                                         |
+| `result.body`     | `TextAccessor`        | Raw response body: `toMatch(file('./__expected__/robots.txt'))`, `.grep()` |
+| `result.json`     | `JsonAccessor`        | Response body parsed as JSON                                               |
+
+#### `.visit(path, scenario?)`: a rendered page
+
+`.visit()` renders the page in a real chromium and resolves with the captured document. There is **one browser process per vitest worker**, shared by every runner the worker hosts and launched lazily on the first `.visit()`, so a spec file that only calls `.fetch()` never pays the browser-launch cost. It is Playwright's headless shell, named explicitly, the lighter of its two Chromium builds. Each visit gets a fresh, isolated browser context, and records no video and no trace: a scenario that fails leaves one screenshot ([Evidence on failure](#evidence-on-failure)).
+
+```typescript
+test('captures the full head surface of a rendered page', async () => {
+    // Given - the fixture homepage
+    const result = await website.visit('/');
+
+    // Then - one golden covers title, canonical, alternates, and metas
+    expect(result.status).toBe(200);
+    expect(result.head).toMatch(file('./__expected__/home.head.json'));
+});
+```
+
+### Visit scenarios: the When
+
+A scenario is the interaction that happens **before** the capture, the visit's When. The capture always reflects the **final** page state, after the scenario ran:
+
+```typescript
+test('subscribes through the form and captures the final state', async () => {
+    // Given - a visitor on the homepage
+    const result = await website.visit('/', async (visitor) => {
+        // When - they fill the form and subscribe
+        await visitor.fill(field('Email'), 'visitor@site.test');
+        await visitor.click(button('Subscribe'));
+        await visitor.see(content('Thanks for subscribing'));
+    });
+
+    // Then - the capture reflects the page after the interaction
+    expect(result.content.text).toContain('Thanks for subscribing');
+    expect(result.errors.text).toBe('');
+});
+```
+
+**No `expect()` inside a scenario (rule `no-expect-in-scenario`).** A scenario is pure interaction; assertions live in the Then, on the returned result. Splitting interaction from assertion keeps the grammar of setup, then action, then result intact, and keeps scenarios replayable independent of what they're checked against.
+
+The visitor's verbs and the words it names elements with are [The visitor](../reference/visitor.md)'s, whole: `click` `fill` `press` `select` `check` `hover` `goto` `see` `gone`, the targets and the landmarks, the `focused` / `disabled` / `selected` / `valued` modifiers, `within()`, exact names and `testId()`. One vocabulary, three surfaces: this page adds none of its own and redefines none of them. Two things are website-specific and stated there: `goto(path)` navigates within the site under test, and the ARIA landmarks are this specification's and the component specification's, never the device's.
+
+Designating exactly one element is rule `target-matches-one-element`, and the refusal it prints (the candidates, the accessible name each matched on, and what each suggested fix LEAVES) is [The visitor § Designating exactly one element](../reference/visitor.md#designating-exactly-one-element).
+
+Navigating within a scenario changes what the capture describes:
+
+```typescript
+test('navigates to another page and captures where it landed', async () => {
+    // Given - a visitor on the homepage
+    const result = await website.visit('/', async (visitor) => {
+        // When - they follow the articles link
+        await visitor.click(link('Articles'));
+    });
+
+    // Then - the result is the destination page
+    expect(result.url).toContain('/articles');
+    expect(result.content.text).toContain('All articles');
+});
+```
+
+### Setup: `.headers()`
+
+`.headers({...})` sets HTTP headers for both terminal actions: the raw `.fetch()` exchange and the browser context behind `.visit()`. Repeated calls merge. The main use case is a User-Agent override, e.g. asserting on what an AI crawler sees:
+
+```typescript
+test('sends chain headers on the raw exchange', async () => {
+    // Given - an AI crawler user agent
+    const result = await website.headers({ 'User-Agent': 'GPTBot/1.0' }).fetch('/robots.txt');
+
+    // Then - the exchange succeeds like any other client
+    expect(result.status).toBe(200);
+    expect(result.body.text).toContain('Allow: /');
+});
+```
+
+### Setup: `website.with({ clock, headers })`
+
+The clock and the headers a whole FILE shares are stated once, on a view of the specification whose every chain starts with them (`const french = website.with({ headers: { 'Accept-Language': 'fr' } })`), and a chain's own setup merges over it ([Conventions](../concepts/conventions.md#what-a-file-shares)).
+
+### Setup: `.clock()`
+
+`.clock('2026-03-04T09:30:00Z')` pins the calendar of the PAGE (what the site's own scripts read when they call `new Date()`) before the first byte is parsed, so a stamp rendered on load is the stated instant and not the moment the navigation happened to start. It is released with the visit.
+
+```typescript
+test('stamps the moment the page was opened', async () => {
+    // Given - the page's calendar pinned for this visit
+    const result = await website.clock('2026-03-04T09:30:00Z').visit('/clock');
+
+    // Then - the rendered stamp is the stated instant
+    expect(result.content.text).toContain('2026-03-04T09:30:00.000Z');
+});
+```
+
+A `.fetch()` opens no page, so it has no clock to pin: the chain refuses the pairing rather than ignoring it. Assert the moment of a raw exchange with a `{{iso8601}}` token in its golden. The primitive behind the setup is [Time and doubles § The clock](../reference/time-and-doubles.md#the-clock).
+
+`.clock()` pins the page, never the SERVER: a window the server computes with its own clock (a feed of the last hour, a token's expiry) is read off the real one. Declare the stub relative to now, so the window holds whenever the spec runs, `http.json({ publishedAt: new Date(Date.now() - 60_000).toISOString() })`, and assert the stamp the page renders by shape, capturing it with a token, `{{iso8601#published}}`, which every later occurrence in the spec must equal; the instant itself is never written.
+
+## The result
+
+| Member              | Type                  | Description                                                                                                               |
+| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `result.status`     | `number`              | HTTP status of the main document response                                                                                 |
+| `result.url`        | `string`              | Final URL, after redirects and any scenario navigation                                                                    |
+| `result.title`      | `TextAccessor`        | `document.title`                                                                                                          |
+| `result.head`       | `JsonAccessor`        | `{ title, canonical, alternates, metas }`: the one-golden-per-page SEO surface                                            |
+| `result.jsonLd`     | `JsonAccessor`        | Every `application/ld+json` block, parsed, as one array                                                                   |
+| `result.meta(name)` | `string \| undefined` | Content of a named meta: `.meta('description')`, `.meta('og:image')`                                                      |
+| `result.canonical`  | `string \| null`      | The canonical `<link>` href, or null                                                                                      |
+| `result.alternates` | flat map              | Hreflang alternates, keyed by language code                                                                               |
+| `result.links`      | array                 | `<link>` elements of the head, in DOM order                                                                               |
+| `result.content`    | `TextAccessor`        | Rendered body text (`document.body.innerText`)                                                                            |
+| `result.html`       | `TextAccessor`        | Full serialized DOM (`document.documentElement.outerHTML`)                                                                |
+| `result.console`    | `TextAccessor`        | Every console message, one `[type] text` line per message, and every uncaught exception as an `[error] Uncaught ...` line |
+| `result.errors`     | `TextAccessor`        | Console errors only, plus any uncaught page error (`Uncaught Error: ...`)                                                 |
+| `result.tree`       | `TextAccessor`        | The ARIA snapshot of the rendered `<body>`: the page's outline, as a golden                                               |
+
+### `result.tree`: the outline, as the accessibility tree draws it
+
+```typescript
+test('lays the article out as a reader walks it', async () => {
+    // Given - the fixture article page
+    const result = await website.visit('/articles/hexagonal');
+
+    // Then - the outline is what a screen reader would walk
+    expect(result.tree).toMatch(file('./__expected__/article.aria.yaml'));
+});
+```
+
+It is produced by the same Playwright `ariaSnapshot()` the component specification calls, so a page's outline and a component's outline are the same kind of golden and comparable to each other. Deterministic where a screenshot is not, and it says what the markup MEANS rather than what it is made of.
+
+### The `head` golden: one per page
+
+`result.head` is the **stable, assertion-friendly projection** of the document head: title, canonical, hreflang alternates, and named metas collapsed into one object. It is the one golden a page needs for its SEO surface:
+
+```typescript
+test('exposes canonical, alternates, and named metas directly', async () => {
+    // Given - the fixture homepage
+    const result = await website.visit('/');
+
+    // Then - the accessors read the head without a golden...
+    expect(result.canonical).toBe('https://site.test/');
+    expect(result.alternates['x-default']).toBe('https://site.test/');
+    expect(result.meta('og:title')).toBe('Fixture: Home');
+
+    // ...or snapshot the whole surface at once
+    expect(result.head).toMatch(file('./__expected__/home.head.json'));
+});
+```
+
+**A meta the FRAMEWORK owns is dropped by the runner, not absorbed by the golden.** A view-transitions router writes its own metas into every head; a golden that swallows them says the site declares something it never did, and every page's golden grows the same two lines. `transform` is the door: the same option `specification.cli()` has, for the same reason (rule `no-transform-duplicating-tokens`):
+
+```typescript
+export const { cleanup, website } = await specification.website({
+    server: { command: 'npm run preview', ready: '/' },
+    // the router's own metas, which no `{{token}}` can name
+    transform: (text) => text.replaceAll(/,?"astro-view-transitions-[a-z]+":\s*"[^"]*"/gu, ''),
+});
+```
+
+It applies to every COMPARED reading of a result (the head projection, the json-ld, the content, the console), so it answers for whatever it is handed; what the page said is still read whole through `meta()`, `canonical`, `alternates` and the rest. Prefer a `{{token}}` wherever the noise has a shape the grammar already names.
+
+Structured data gets the same treatment: every `ld+json` block on the page, in one golden:
+
+```typescript
+test('parses every json-ld block into one array', async () => {
+    const result = await website.visit('/');
+
+    expect(result.jsonLd).toMatch(file('./__expected__/home.jsonld.json'));
+});
+```
+
+### Console assertions
+
+The console splits into the full stream and the error-only stream, the same shape as `stdout`/`stderr` on a cli result:
+
+```typescript
+test('keeps a clean page silent on both streams', async () => {
+    // Given - the healthy homepage
+    const result = await website.visit('/');
+
+    // Then - no console output at all
+    expect(result.console.text).toBe('');
+    expect(result.errors.text).toBe('');
+});
+
+test('separates console errors from the full stream', async () => {
+    // Given - a page that logs and errors
+    const result = await website.visit('/noisy');
+
+    // Then - the full stream carries both, the error stream only the error
+    expect(result.console).toMatch(file('./__expected__/noisy.console.txt'));
+    expect(result.errors.text).toContain('boom');
+});
+```
+
+## Unique here
+
+### Declared backend
+
+A site under test usually talks to an API. The `backend` option starts a small **stub backend** (plain `node:http`, no extra dependency) BEFORE the server command and injects its URL into the server child's environment under `backend.env`; the site reads it the same way it would in production:
+
+```typescript
+// specs/website/website.specification.ts
+export const { cleanup, website } = await specification.website({
+    server: { command: 'npm run start', ready: '/' },
+    backend: { env: 'API_URL' },
+});
+
+afterAll(cleanup);
+```
+
+| `backend` field | Description                                                                      |
+| --------------- | -------------------------------------------------------------------------------- |
+| `env`           | Env var receiving the stub's URL in the server child (e.g. `'API_URL'`)          |
+| `port`          | Fixed port; pins a stable stub URL across runs. Default: a free OS-assigned port |
+
+`backend` requires `server` mode: with `url` it refuses (the type already forbids the combination): a deployed site cannot be pointed at a local stub. The **ownership boundary**: the framework owns the server child, so it injects the env var itself, and that is the whole wiring.
+
+What the stub serves is declared per chain, as [stubs](../reference/stubs.md): the feature's `__setup__/stubs/` facade, exactly the form `api`/`job` use:
+
+```typescript
+import newsroom from './__setup__/stubs/newsroom.stubs.js';
+
+describe('declared backend', () => {
+    test('renders the events feed from the declared backend', async () => {
+        // Given - the backend under stub for this chain
+        const result = await website.intercept(newsroom).visit('/events');
+
+        // Then - the page rendered what the stub declared
+        expect(result.content.text).toContain('Jazz night at the harbour');
+        expect(result.errors.text).toBe('');
+    });
+});
+```
+
+The stub backend **resets between chains** the way databases do: one chain = one terminal action, and its stubs replace the previous chain's wholesale. Selection is the shared one: the first declared stub that matches and is not exhausted wins, and a stub with no `times` is unlimited, so a page re-fetching the same endpoint (re-render, retry) replays it.
+
+Strictness is the analog of `external: 'block'`: a request matching no declared stub is answered **501** (a JSON body naming the path and listing the declared routes) and **recorded**; when the `.visit()` completes, the action **throws** an error enumerating every unmatched request (method, path, count). The failure evidence (screenshot on a scenario error) is captured first, as always. A chain with **zero** intercepts leaves the stub unguarded, the same boundary as MSW never mounting without an `.intercept()`.
+
+Two pieces of plumbing are handled for you:
+
+- **CORS:** the stub answers the `OPTIONS` preflight and stamps permissive `Access-Control-Allow-*` headers on every response, so client-side fetches from the site's origin just work.
+- **`external: 'block'`:** the stub's origin is allow-listed automatically; declared-backend fetches are never aborted as third-party noise.
+
+### Storage
+
+`.storage({ local, session })` fills `localStorage` and `sessionStorage` before the page's first script runs, so a page that reads a preference on load sees it; `.storage('throws')` makes every read of either store throw the `SecurityError` a browser that blocks site data throws. A later call replaces the earlier, and a key the page already holds is kept, since the script runs again on each navigation. A chain ending in `.fetch()` is refused: no page opens, so nothing could read the storage.
+
+```ts
+const result = await website.storage({ local: { theme: 'dark' } }).visit('/settings');
+```
+
+### Cross-origin policy (`external`)
+
+`external: 'block'` aborts every request leaving the site under test during a `.visit()`: analytics beacons, third-party CDNs, ad scripts never fire, so a visit stays deterministic. `'allow'` lets them through.
+
+The default follows the mode: `'block'` with `server` (you own the deployment, third-party noise is not the point), `'allow'` with `url` (a deployed site legitimately loads third-party assets). Override with the top-level `external` option when a spec needs the opposite of its mode's default.
+
+A request the policy aborts is the runner's doing, not the site's: the browser's console error for it (`Failed to load resource`) stays out of `.errors`, and one for a request the policy let through stays in.
+
+### Evidence on failure
+
+When a scenario throws (an element never becomes visible, a `see()` times out), the error carries a full-page screenshot of the state the scenario died in, referenced by its path in the error message. It is written under `.artifacts/vitest/evidence/`, in the folder of the run that took it, so it outlives the run and its temp root, until the next run starts, which sweeps every run's evidence but a living one's. The original error is never masked; the screenshot is attached evidence, not a replacement.
+
+### Playwright: the optional peer
+
+Playwright is not a hard dependency: `.fetch()`-only spec files never need it. `.visit()` imports it lazily, and needs it installed:
+
+```bash
+npm install -D playwright && npx playwright install chromium
+```
+
+Calling `.visit()` without playwright installed throws exactly that guidance; there is nothing else to search for.
+
+Provisioning the environment is not this package's job. In CI, the shared validate workflow does it: `browsers: true` (jterrazz-actions) installs cached chromium, versioned from the caller's lockfile, between Build and Test. On a workstation, `j install` provisions `playwright-browsers` once.
+
+### Folder layout
+
+```text
+specs/website/
+├── website.specification.ts    # runner at the specification ROOT (rule `specs-at-declared-depth`)
+└── <domain>/
+    ├── <aspect>.spec.ts
+    ├── __expected__/              # ALL expected fixtures, FLAT (*.head.json, *.jsonld.json, *.console.txt, ...)
+    └── __setup__/stubs/           # the stubs declaring what the backend serves, with the `backend` option
+        ├── newsroom.stubs.ts
+        └── http/...
+```
+
+No `__seeds__/` or `__requests__/`: a website chain has no `.seed()` setup and no request-file format, whatever its runner declares under `services`; `.fetch()`/`.visit()` calls are inline, and the golden is always `__expected__/<name>`.
+
+**Where a page's golden goes.** A website spec reads its subject page by page, one spec file per page, and a golden read by one file is that file's: written in place while it is short (`ground-shared-or-inline`), else beside its one reader. A domain folder may not nest (`specs-at-declared-depth`), so a domain that would hold one page's golden among many pages' specs becomes a domain of its own (jterrazz-web's `metadata/`, `sitemap/`, `feed/` and `not-found/` sit beside `journeys/` and `redirects/`), and a domain of one spec per surface keeps each golden with its one reader, in place up to the cap and in the domain's `__expected__/` past it.
+
+**A subject and its oracle are derived together, or pinned together.** A spec that visits a path a helper computes ("the newest article", "a school project") and compares it with a golden pinning that page's literal values fails against a page nobody chose the day the corpus moves the helper's pick. Either derive both (the path and the expectation from the same subject) or pin both: a literal path and its golden. A derived subject with a pinned golden is the one pairing to refuse in review.
+
+**A table of pages is the one sanctioned exception, and the checker cannot see it.** `one-subject-per-spec` refuses a spec visiting several pages by literal paths; a `test.each` whose rows feed `visit()` computed paths passes both it and `no-unused-ground` unseen: the checker reads literals, not tables. A site that keeps one such table (every redirect rule, every legacy slug) declares it in its own test guide, prints each row as a line (`status source -> destination`) and compares the whole table with a value written in place, never a mapping of the source's own table into the expectation, which restates the code and lets a wrong row pass.
+
+**The production build belongs to the site's gate, not to each spec.** `server.command` starts what the build left (`astro preview`, `next start`); the Makefile's `test: build` (or a stamp file the build touches, rebuilt when a source is newer) owns rebuilding it, so no website spec walks the source tree for mtimes before it starts.
+
+## Pitfalls
+
+- **Passing both `server` and `url`, or neither.** The options type makes the invalid combinations inexpressible; the compiler rejects them before anything runs.
+- **Using `expect()` inside a scenario callback.** Forbidden (rule `no-expect-in-scenario`): the scenario is the When; assertions belong on the result the `.visit()` promise resolves to.
+- **Reaching for `testId()` first, or to escape an ambiguity.** It is the last rung, and `test-id-states-what-is-missing` refuses it without the line naming what the element lacks; an ambiguity is scoped with `within()`, `target-matches-one-element`'s fix (see [The visitor § `testId()`](../reference/visitor.md#testid-the-one-escape-hatch)).
+- **Using `see()` to prove something went away.** It cannot: an element that never appeared and one that disappeared read the same to it. `gone(element)` is the absence primitive.
+- **Snapshotting the tree to prove focus.** The tree carries none; [The visitor § Modifiers](../reference/visitor.md#modifiers) says what does, and what a golden may pin instead.
+- **Calling `.visit()` without playwright installed.** The error names the exact fix (`npm install -D playwright && npx playwright install chromium`); there is no silent fallback.
+- **Expecting `.fetch()` to follow redirects.** It never does: the 3xx status and `location` header ARE the result; chase the target with a second `.fetch()` if the spec needs to.
+- **Assuming `external` defaults the same way in both modes.** It flips with the constructor mode: `'block'` with `server`, `'allow'` with `url`. Pass it explicitly to override.
+- **Reading `result.head` field-by-field instead of snapshotting it.** It is designed as the one golden per page (`toMatch(file('./__expected__/home.head.json'))`); use the direct accessors (`canonical`, `alternates`, `meta()`) only for a single targeted probe.
+- **Calling `.intercept()` without the `backend` option.** It throws immediately, naming the fix: add `backend: { env: '...' }` to the `specification.website()` options; a chain's `.http` exchanges need a stub to serve them.
+- **Combining `backend` with `url` mode.** The type forbids it and the runtime refuses: a deployed site reads its API URL at its own deploy time; there is nothing a local stub could inject into.
+- **A site that loads `next/font/google`.** Its build downloads the fonts: the suite becomes network-bound, and fails offline or behind a proxy. Load the family from a file in the repository (`next/font/local`) so the suite needs no network.
+
+## Related
+
+[Set up a project](../start/set-up-a-project.md) · [Assertions](../reference/assertions.md) · [Tokens](../reference/tokens.md) · [Mobile specs](mobile-specs.md) · [Component specs](component-specs.md)