@jterrazz/test 16.1.0 → 17.0.0

package/docs/reference/tokens.md

@@ -0,0 +1,258 @@
+# Tokens: dynamic values in fixtures
+
+Real systems generate UUIDs, timestamps, ports, and paths. The framework handles them with **one unified token grammar** (rule `no-unknown-token`): the same `{{token}}` vocabulary works in every fixture file, and the same vocabulary is available in code as `match.*`. The vocabulary is fixed (21 tokens, defined, tested, and documented in the package), and an unknown token in a fixture is an error, not a silent literal.
+
+## Where tokens work
+
+| Fixture kind   | Files                                                                               | Coverage                                                                                                                                                                                                                      |
+| -------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| HTTP responses | `__expected__/*.http`                                                               | **body and headers**                                                                                                                                                                                                          |
+| JSON snapshots | `__expected__/*.json`                                                               | any string value                                                                                                                                                                                                              |
+| Text snapshots | `__expected__/*.txt` (and other text files under `__expected__/`)                   | anywhere in the text                                                                                                                                                                                                          |
+| Spec documents | `<case>.spec.yaml`, beside the spec ([Spec documents](../guides/spec-documents.md)) | what a document asserts (a run's streams and `files:` texts, a response's status, headers and body, a table's cells, a job's `error:`), **never the description, a command, a request or a body**, which are prose and inputs |
+
+```http
+### __expected__/order-created.http: tokens in a header AND the body
+HTTP/1.1 201 Created
+Location: /orders/{{uuid#order}}
+
+{ "id": "{{uuid#order}}", "total": "{{number}}", "createdAt": "{{iso8601}}" }
+```
+
+```text
+### __expected__/help.txt: tokens in a TEXT snapshot
+shoply v{{semver}}
+Started at {{iso8601}} in {{workdir}}
+Done in {{duration}}
+```
+
+A token in a JSON body is written inside quotes (`"total": "{{number}}"`) because the file must stay JSON, and a quoted numeric token still matches a native JSON number as a whole value: `{{number}}`, `{{int}}`, `{{float}}` and `{{port}}` accept `42` as readily as `"42"`. `{{any}}` matches any type at all.
+
+Stream comparisons strip ANSI escape sequences **before** token matching, so fixtures never contain color codes: `.text` is the stripped text, `.raw` the capture as it was.
+
+## The vocabulary: all 21 tokens
+
+Every token matches one value of its family at its position. The normative definitions (the exact accepted grammar for each) are shipped and tested inside the package; the table below states each token's semantics and canonical accepted forms.
+
+### Identifiers
+
+| Token      | Matches                                        | Example value                          |
+| ---------- | ---------------------------------------------- | -------------------------------------- |
+| `{{uuid}}` | RFC 4122 UUID, `8-4-4-4-12` hexadecimal groups | `3f2c9b6e-8a41-4c8f-9d2a-1b7e5f0c4d3e` |
+| `{{ulid}}` | ULID, 26 Crockford base32 characters           | `01J2X3YV5T8Q4R9K7M6N1P0ZSD`           |
+
+### Time
+
+| Token          | Matches                                                       | Example value                |
+| -------------- | ------------------------------------------------------------- | ---------------------------- |
+| `{{iso8601}}`  | Full ISO 8601 timestamp (date + time, `Z` or offset)          | `2026-07-16T10:32:05.123Z`   |
+| `{{date}}`     | Calendar date, `YYYY-MM-DD`                                   | `2026-07-16`                 |
+| `{{time}}`     | Wall-clock time, `HH:MM[:SS]` (seconds and fraction optional) | `10:32:05`                   |
+| `{{duration}}` | Elapsed-time string as printed by tooling                     | `340ms`, `1.24s`, `2m`, `3h` |
+
+### Numbers
+
+| Token        | Matches                                | Example value |
+| ------------ | -------------------------------------- | ------------- |
+| `{{number}}` | Any numeric value (integer or decimal) | `109`, `4.5`  |
+| `{{int}}`    | Integer only                           | `42`          |
+| `{{float}}`  | Decimal with a fractional part         | `0.97`        |
+
+### Versions & hashes
+
+| Token        | Matches                                                            | Example value         |
+| ------------ | ------------------------------------------------------------------ | --------------------- |
+| `{{semver}}` | Semantic version (`major.minor.patch`, optional pre-release/build) | `9.0.0`, `9.1.0-rc.1` |
+| `{{sha}}`    | Commit/content hash digest (hexadecimal, git-style)                | `f690adf...`          |
+| `{{hex}}`    | Hexadecimal string                                                 | `deadbeef`            |
+| `{{base64}}` | Base64 string (padding included)                                   | `aGVsbG8=`            |
+
+### Network
+
+| Token       | Matches                          | Example value                         |
+| ----------- | -------------------------------- | ------------------------------------- |
+| `{{port}}`  | TCP/UDP port number (0 to 65535) | `54321`                               |
+| `{{ip}}`    | IP address                       | `127.0.0.1`                           |
+| `{{url}}`   | Absolute URL with scheme         | `https://rates.example.com/v1/latest` |
+| `{{email}}` | Email address                    | `contact@jterrazz.com`                |
+
+### Paths
+
+| Token         | Matches                                                                                                                               | Example value                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `{{path}}`    | Filesystem path                                                                                                                       | `/tmp/x/dist/index.js`                                         |
+| `{{workdir}}` | **The exact cwd of the current spec**: the framework knows the temp directory it created, so this is an equality check, not a pattern | `/tmp/jterrazz-test-runs-501/48213-Xk2pQa/spec-command-a1B2c3` |
+
+`{{workdir}}` holds the **resolved** cwd, the spelling a child process reports, after any symlink on the way (macOS's `$TMPDIR` sits under `/var`, a link to `/private/var`). The `$WORKDIR` token that `.env()` and a document's `env:` expand is that same resolved path, so a directory the runner hands to the binary comes back in its output matching the token: `.env({ CACHE_DIR: '$WORKDIR/cache' })` is asserted as `{{workdir}}/cache`.
+
+### Generic
+
+| Token        | Matches                                                                                                                                                                                                                                                          |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{{string}}` | Any string value                                                                                                                                                                                                                                                 |
+| `{{any}}`    | Anything: always-true **as a whole value** (matches any type: object, number, `null`). Embedded in a frame (`A {{any}} Z`) it only widens the middle; the surrounding literal still has to match, and text on both sides of it on its line holds it to that line |
+
+## `#ref` captures
+
+Any token becomes a capture by suffixing `#name`: `{{uuid#order}}`. The **first occurrence captures** the actual value; every subsequent occurrence of the same ref **must be equal**. Refs are scoped to the current spec: one namespace shared by all fixture files and code-side `match.ref()` within that spec, resetting between specs.
+
+```http
+### __expected__/order-created.http: {{uuid#order}} appears 3 times, all must be equal
+HTTP/1.1 201 Created
+Location: /orders/{{uuid#order}}
+
+{
+    "id": "{{uuid#order}}",
+    "paymentIntent": { "orderId": "{{uuid#order}}" }
+}
+```
+
+A ref that re-occurs with a different value fails with both values in the message: the captured one and the conflicting one.
+
+## `match.*`: the same vocabulary in code
+
+Every token has a code mirror for inline assertions (table rows, primarily):
+
+```typescript
+import { match } from '@jterrazz/test';
+
+await expect(result.table('orders', { database: 'db' })).toMatch([
+    [match.uuid(), 'pending', match.number(), match.iso8601()],
+]);
+```
+
+`match.uuid()`, `match.ulid()`, `match.iso8601()`, `match.date()`, `match.time()`, `match.duration()`, `match.number()`, `match.int()`, `match.float()`, `match.semver()`, `match.sha()`, `match.hex()`, `match.base64()`, `match.port()`, `match.ip()`, `match.url()`, `match.email()`, `match.path()`, `match.workdir()`, `match.string()`, `match.any()`, plus four code-only forms:
+
+| Code-only                         | Meaning                                                                                     |
+| --------------------------------- | ------------------------------------------------------------------------------------------- |
+| `match.regex(/.../)`              | Arbitrary pattern, the escape hatch when no token fits                                      |
+| `match.ref(name)`                 | Capture on first use, require equality afterwards (same namespace as `{{token#name}}` refs) |
+| `match.ref(name, { not: other })` | Additionally require **inequality** with another captured ref                               |
+| `match.includes(substring)`       | Containment: the value holds the substring; used mostly in a stub's request filter          |
+
+```typescript
+// intent.order_id === orders.id, but intent.id ≠ orders.id
+await expect(result.table('orders', { database: 'db' })).toMatch([[match.ref('order'), 'pending']]);
+await expect(result.table('payment_intents', { database: 'db' })).toMatch([
+    [match.ref('intent', { not: 'order' }), match.ref('order')],
+]);
+```
+
+## Update mode: tokens are preserved
+
+`TEST_UPDATE=1` (or `vitest -u`) rewrites fixtures from actual output, but it writes **tokens, not values** (rule `no-volatile-literal`):
+
+- Segments already covered by a placeholder are **preserved**: a fixture line `Done in {{duration}}` stays `Done in {{duration}}` after an update, no matter what duration the run printed.
+- Values the framework knows to be dynamic are substituted automatically: the spec's cwd becomes `{{workdir}}` in the written fixture without you doing anything.
+- A golden that does not exist yet, or holds nothing but whitespace, is **recorded** from the output: a `.http`, a `.json` and a text golden alike, and a document's `response:` file too: a run that records stands without the goldens it is about to write. A golden is started by naming it, never by stubbing it.
+
+Example, starting from actual output:
+
+```text
+shoply v9.1.0
+Started at 2026-07-17T09:12:44.031Z in /tmp/jterrazz-test-runs-501/48213-Xk2pQa/spec-command-x9Y8z7
+Done in 0.83s
+```
+
+with an existing fixture:
+
+```text
+shoply v{{semver}}
+Started at {{iso8601}} in {{workdir}}
+Done in {{duration}}
+```
+
+`TEST_UPDATE=1` leaves the fixture byte-identical: every changed segment was already covered by a token. If the CLI adds a new line `Cache dir: /tmp/shoply-spec-x9y8z7/.cache`, the update writes `Cache dir: {{workdir}}/.cache` (`{{workdir}}` is substituted automatically); a timestamp in a _new_ line would be written literally, for you to tokenize by hand (or it will fail on the next run, which is the signal).
+
+The same preservation and `{{workdir}}` substitution apply identically across every fixture kind: a value written in place (below), text snapshots (`__expected__/*.txt`), JSON goldens (`__expected__/*.json`), `.http` response bodies (`__expected__/*.http`), and the streams of a `<case>.spec.yaml` (whose ground, commands and `files:` an update never rewrites). A cwd embedded in a JSON string value is written back as `{{workdir}}` exactly as it is in a text line, so an updated JSON golden matches the next run's (different) cwd instead of pinning a run-specific temp path.
+
+### A value written in place is rewritten in the test
+
+A `toMatch(<value>)` is rewritten where it stands, in the test file, the gesture vitest's `toMatchInlineSnapshot` makes: the call is found from the stack of the assertion, and its argument (up to its comma or its closing parenthesis, whatever template, string or nested call it holds) is replaced by the actual result, merged with the tokens the old value had where the result still matches them. A text is written as a template literal indented one level deeper than its call, a json as its JSON, a table one row per line. An empty value, `toMatch('')`, is the one an author leaves to be recorded: outside update mode it fails naming the run that fills it. A value that matches is never touched, and neither is a `{ frozen: true }` one or a `.not`: a negation asserts a mismatch, and records nothing. Every rewrite of one file during a run is laid on the source the run loaded, so a second rewrite lands where its stack says even when a first one moved the lines below it. Under the preset the test file is written when the run ENDS, after its report: vitest frames a failure by reading the file on disk at the line the run loaded, so a file rewritten mid-run would frame a later failure at another test's code. The preset's global setup hands each project a pending folder under `.artifacts/vitest/in-place/` and writes what waits there once the report is printed (in watch mode, when the watcher exits); a run outside the preset writes each file at once. A component's value is rewritten the same way through a server command, the page's stack mapped back to the test's source by the browser server. What update mode writes comes out in the repository's style: an integer of five digits or more is grouped by threes (`1_775_034_000_000`, as the linter's numeric separators ask), and when the run ends each rewritten test file is laid out by the oxfmt the project installs, with the project's own config: its quotes, its keys, its trailing commas. Outside the preset, or where no oxfmt is installed, the file stays as written, and `npx typescript fix` formats it.
+
+This is why `transform` on `specification.cli` is only an escape hatch (rule `no-transform-duplicating-tokens`): the token grammar plus ANSI stripping covers the standard sources of nondeterminism, and a transform that merely re-implements standard tokens is refused by `no-transform-duplicating-tokens` ([no-transform-duplicating-tokens](linting.md#no-transform-duplicating-tokens)).
+
+### Frozen fixtures: opting a negative fixture out of the rewrite
+
+Update mode rewrites a mismatching fixture with the actual output. That is exactly wrong for a **deliberately-wrong fixture**, one whose _mismatch_ is the behaviour under test (a spec that asserts the diff, or that a missing fixture errors). Under `TEST_UPDATE=1` an unfrozen negative fixture is silently overwritten with the real output, and the assertion stops testing anything.
+
+Pass `{ frozen: true }` as the second argument to opt a single fixture out:
+
+```typescript
+// A deliberately-wrong fixture: its diff rendering is the subject.
+expect(() =>
+    expect(result.response).toMatch(file('./__expected__/wrong-body.http'), { frozen: true }),
+).toThrow(/Response mismatch/);
+```
+
+A frozen fixture is **never written** in update mode: a frozen mismatch still throws its diff, and a frozen _missing_ fixture still throws "does not exist" (never created). Its failure says so rather than pointing at update mode: write the file by hand, or drop `{ frozen }` for one `TEST_UPDATE=1` run and put it back. It is available on every golden subject (`result.response`, `result.stdout`/`result.stderr`, `result.json`, `result.directory`, `result.filesystem`). The static rule `negative-golden-frozen` flags a golden `toMatch(file(...))`/`toMatch(directory(...))` wrapped in `expect(() => ...).toThrow()` / `.rejects` that omits it.
+
+### The discipline: update mode writes, it does not judge
+
+A rewritten fixture is not a passing test: it is this run's output, made into the expectation. Three steps, in this order, and the middle one is the whole point.
+
+1. **Run it.** `TEST_UPDATE=1 npx vitest --run --project <kind>`, narrowed to the project whose goldens moved, never the whole suite, because a broad update rewrites files nobody looked at.
+2. **Read the diff.** `git diff` is the review: every line that changed is a behaviour that changed. A golden diff that nobody can explain is a bug that just became the expectation, and this is the only moment it is cheap to catch.
+3. **Run again, without the flag.** The second run is the one that proves anything. It reads the file as any other run would, and it is what a reviewer's machine will do.
+
+The round-trip is not a step the suite performs for you, and deliberately so: update mode writes the file from THIS run's actual value, so re-comparing inside the same run matches by construction and proves nothing. The real round-trip already exists: CI runs the same goldens on another machine, which is exactly the question "does this file still hold when the run is not the one that wrote it?"
+
+**The frozen two-pass.** A frozen fixture is never written, so changing one on purpose is two deliberate passes: drop `{ frozen: true }`, run once under `TEST_UPDATE=1`, read the diff, and put the option back in the same commit. The friction is the feature: a negative fixture should cost something to change.
+
+**What update mode never touches.** The ground of a `<case>.spec.yaml` (its `description:`, its commands, its `env:`/`serve:`/`fixture:` and its `files:`) is authored, never rewritten; only the expected streams move. Its `files:` are still judged under update, so a document that passes a recorded run is one a normal run passes.
+
+**What update mode refuses to record.** An expectation that cannot fail is no expectation. Update mode writes nothing over a result whose call threw: the value of a `.call()` that failed is `null`, and a recorded `toMatch(null)` stays green while every call fails: assert the error, or fix the call. It rewrites a literal only: a `toMatch(` handed a name or a call stands for values the rewrite would replace by the last one it saw (a table's rows are recorded by hand, one by one). And `toMatch('')` on a string (a stream's `.text`, a file's `.content`) is vitest's substring match, true of any text; the rule `no-empty-substring-match` refuses it. A `__requests__/*.http` is an input, not an expectation, and is never written either.
+
+## Known limitations
+
+The grammar is deliberately small; three edges are worth knowing:
+
+- **No escaping for literal `{{...}}` text.** There is no escape sequence. A `{{uuid}}` written in a fixture is _always_ interpreted as the token; you cannot assert a literal, un-substituted `{{uuid}}` string in expected output. (An unknown name like `{{widget}}` is caught by the conventions checker (rule `no-unknown-token`) as an error: the vocabulary is frozen, so an unknown token is never a usable literal escape.) For genuinely custom shapes, use `match.regex()` in code.
+- **Update-merge pairs one previous line with one actual line.** Placeholder preservation is by **pattern**: the aligned line is tried first, then what is left over is re-paired by matching each remaining placeholder line against each unresolved actual line, in file order. A mid-file insertion is therefore safe: the shifted `{{duration}}` line is recognised where it landed. What stays out of reach: a previous line is spent **once**, so when the output grows a SECOND line the same placeholder could cover, the first keeps the token and the new one is written as a raw value, for you to tokenize.
+- **`{{float}}` cannot require a decimal on a JSON number.** In JSON there is no distinction between `42` and `42.0`, so as a whole JSON value `{{float}}` accepts any finite number (an integer passes). The decimal requirement only holds in **text** contexts (`4.2` matches, `42` does not). This is a JSON limitation, not a token choice.
+
+## Appendix: canonical accepted forms (normative, as implemented)
+
+The exact grammar of each token, one tested regular expression per token
+(defined in [`src/expectations/tokens/structural.ts`](https://github.com/jterrazz/package-test/blob/main/src/expectations/tokens/structural.ts), the vocabulary list in `match.ts` beside it). In embedded positions the pattern is
+anchored to its surroundings; as a whole JSON value, numeric tokens also
+accept native JSON numbers.
+
+| Token          | Accepted form (regex)                                                                                                                                                                                      | Notes                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `{{uuid}}`     | `[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}`                                                                                                                              | any RFC 4122 variant                                                                        |
+| `{{ulid}}`     | `[0-9A-HJKMNP-TV-Z]{26}`                                                                                                                                                                                   | Crockford base32, uppercase                                                                 |
+| `{{iso8601}}`  | `\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z\|[+-]\d{2}:\d{2})`                                                                                                                                          | date + time, `Z` or offset required                                                         |
+| `{{date}}`     | `\d{4}-\d{2}-\d{2}`                                                                                                                                                                                        |                                                                                             |
+| `{{time}}`     | `\d{2}:\d{2}(:\d{2}(\.\d+)?)?`                                                                                                                                                                             | seconds and fraction optional                                                               |
+| `{{duration}}` | `\d+(\.\d+)?(ms\|s\|m\|h)`                                                                                                                                                                                 | strict: `ms`, `s`, `m`, `h` suffixes only                                                   |
+| `{{number}}`   | `-?\d+(\.\d+)?([eE][+-]?\d+)?`                                                                                                                                                                             | JSON numbers also accepted as whole values                                                  |
+| `{{int}}`      | `-?\d+`                                                                                                                                                                                                    | whole JSON value: `Number.isInteger`                                                        |
+| `{{float}}`    | `-?\d+\.\d+`                                                                                                                                                                                               | whole JSON value: any finite number                                                         |
+| `{{semver}}`   | `\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?`                                                                                                                                                       |                                                                                             |
+| `{{sha}}`      | `[0-9a-f]{7,64}`                                                                                                                                                                                           | 7 to 64 lowercase hex chars (short SHA up to SHA-512)                                       |
+| `{{hex}}`      | `[0-9a-fA-F]+`                                                                                                                                                                                             |                                                                                             |
+| `{{base64}}`   | `[A-Za-z0-9+/]+={0,2}`                                                                                                                                                                                     |                                                                                             |
+| `{{port}}`     | `\d{1,5}`                                                                                                                                                                                                  | range-checked to 0 to 65535 (embedded placeholders reject out-of-range values like `99999`) |
+| `{{ip}}`       | `(\d{1,3}\.){3}\d{1,3}`                                                                                                                                                                                    | IPv4 only for now                                                                           |
+| `{{url}}`      | `https?://[^\s"'<>]+`                                                                                                                                                                                      | http(s) schemes only                                                                        |
+| `{{email}}`    | `[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`                                                                                                                                                                     |                                                                                             |
+| `{{path}}`     | `\.{0,2}/[^\s"'<>]*`                                                                                                                                                                                       | absolute (`/...`) or relative (`./...`, `../...`)                                           |
+| `{{workdir}}`  | none (exact string equality with the spec's cwd, realpath form)                                                                                                                                            | never matches when the framework does not know the cwd                                      |
+| `{{string}}`   | any string; embedded: `[^\n]*?` (single line)                                                                                                                                                              |                                                                                             |
+| `{{any}}`      | anything; embedded: `[\s\S]*?` (crosses lines) where its line holds no text on one side of it (alone on a line, opening it or closing it); `[^\n]*?` where text frames it on its line (`"msg":"{{any}}",`) |                                                                                             |
+
+## Pitfalls
+
+- **Inventing a token.** The vocabulary is fixed; `{{timestamp}}` in a fixture is an error (rule `no-unknown-token`). Use `{{iso8601}}`, or `match.regex()` in code for genuinely custom shapes.
+- **Expecting `{{workdir}}` to be a pattern.** It matches the _exact_ cwd of the current spec; a path from another spec's cwd fails.
+- **Assuming refs span the suite.** Ref scope is the current spec; `{{uuid#order}}` in two different tests are unrelated captures.
+- **Using `{{any}}` where a precise token exists.** `{{any}}` matches garbage too; every widening of a fixture weakens the spec.
+- **Reading "always-true" as unframed.** `{{any}}` is only unconditional as the _whole_ value. Embedded (`A {{any}} Z`), the frame around it must still match, and a non-string/number actual cannot satisfy an embedded token at all.
+- **Hand-writing values that update mode would tokenize.** Run `TEST_UPDATE=1` first, then tighten: placeholders you wrote once are preserved forever after.
+- **Escaping into `transform` for tokenizable noise.** Only application noise _not_ covered by the grammar justifies a transform (rule `no-transform-duplicating-tokens`); one a token already names is refused by `no-transform-duplicating-tokens`.
+- **Leaving a deliberately-wrong fixture unfrozen.** A negative test whose golden matcher asserts a mismatch (wrapped in `expect(() => ...).toThrow()` / `.rejects`) must pass `{ frozen: true }`; otherwise `TEST_UPDATE=1` overwrites the wrong fixture with the real output and the assertion silently stops testing anything (rule `negative-golden-frozen`).
+
+## Related
+
+[Assertions](assertions.md) · [API specs](../guides/api-specs.md) · [CLI specs](../guides/cli-specs.md)

package/docs/reference/visitor.md

@@ -0,0 +1,221 @@
+# The visitor
+
+Three kinds of test drive something a person can see: a served page ([Website specs](../guides/website-specs.md)), a mounted component ([Component specs](../guides/component-specs.md)) and a screen on a simulator ([Mobile specs](../guides/mobile-specs.md)). Each hands its scenario a **visitor**, which acts on the surface the way a person would:
+
+```typescript
+await visitor.fill(field('Email'), 'visitor@site.test');
+await visitor.click(button('Subscribe'));
+await visitor.see(content('Thanks for subscribing'));
+```
+
+The visitor has one vocabulary on all three surfaces, and this page owns it: the **verbs** (`fill`, `click`, `see` ...), the **targets** they act on (`field()`, `button()`, `content()` ...), and the **matching** that turns a target into exactly one element. A target names what a person would name: a role and an accessible name. There is no CSS selector, no XPath and no raw predicate; the one escape hatch, `testId()`, must say in a comment what the element lacks (rule `test-id-states-what-is-missing`).
+
+## Verbs
+
+A scenario is the When: pure interaction, no `expect()` inside it (rule `no-expect-in-scenario`). Every verb auto-waits; there are no sleeps anywhere in the framework.
+
+| Verb                     | Does                                                               |
+| ------------------------ | ------------------------------------------------------------------ |
+| `click(target)`          | Click the element                                                  |
+| `tap(target)`            | Tap the element, the device's word for the same act                |
+| `fill(target, value)`    | Fill a form field                                                  |
+| `press(key)`             | Press a key (e.g. `'Enter'`)                                       |
+| `select(target, option)` | Select an option in a select field                                 |
+| `check(target)`          | Check a checkbox or radio                                          |
+| `hover(target)`          | Hover the element                                                  |
+| `goto(path)`             | Navigate to another path of the site under test                    |
+| `rerender(ui)`           | What a PARENT does: new props, same mount                          |
+| `unmount()`              | What a parent does when it takes the thing off the screen          |
+| `see(target)`            | **The synchronization primitive**: retries until visible           |
+| `gone(target)`           | The absence primitive: retries until hidden or out of the document |
+
+The website's and the component's visitors carry the same eight page verbs by construction (one declaration, `VisitorVerbs` in `src/visitor/verbs.ts`, each surface adding only its own words), and the device's visitor takes its `see` and `fill` from it. `goto()` does not exist on a component, because a component has no address. `rerender`/`unmount` exist nowhere else, because only a component has a parent inside the test. `gone()` is absent on mobile until the adapter can answer for absence honestly, which an XCUITest tree does not do yet.
+
+### `see()` and `gone()` are the synchronization
+
+`see()` is how a scenario waits. It resolves through render work (a deep link into a Metro cold bundle, a network round-trip, an animation, a suspended boundary), and it absorbs them all without a single sleep. `gone()` is the same primitive pointed the other way: it retries until the element is hidden or out of the document, which is how a dismissal is asserted without guessing at an animation's length.
+
+Both take a modifier, so `see(focused(button('Open')))` waits for the keyboard to land and `gone(disabled(button('Save')))` waits for a control to become usable again.
+
+`see()` ACTS ON NOTHING, and on the mobile specification that changes what `target-matches-one-element` asks of it: any visible match satisfies it, because an XCUITest tree legitimately exposes the same label twice (a container and its child both carry it), and a synchronization primitive refusing on that would punish honest screens. On the web and in a component, `see()` holds the same cardinality as every other verb.
+
+### The per-specification matrix
+
+Which surface declares which verb, target and modifier is generated from the code: [Test § The capability matrix](https://github.com/jterrazz/package-test/blob/main/docs/guides/test.md#the-capability-matrix), its **Verb** and **Target** sections, an `n/a` for a word the specification does not declare. `within()` and `{ exact: false }` reach every surface. A blank cell is not a hole to be filled by a CSS selector; it is a boundary the adapter refuses at runtime, with a message naming it.
+
+The ARIA landmarks are web-only: passing one to a mobile verb refuses at runtime with a message naming the boundary: an iOS screen has no ARIA regions, and inventing an equivalent would be a second vocabulary wearing the first one's words.
+
+## Targets
+
+The four every surface has:
+
+| Target          | Locates by                                                                           |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `button(name)`  | accessible name, button role                                                         |
+| `field(label)`  | accessible name, input roles, or the label that names it                             |
+| `content(text)` | any element whose text IS the text, whole (`{ exact: false }` to contain)            |
+| `testId(id)`    | `data-testid` on the web, the accessibility identifier on a device: the escape hatch |
+
+The two a browser adds, on the website and the component:
+
+| Target          | Locates by                    |
+| --------------- | ----------------------------- |
+| `link(name)`    | accessible name, link role    |
+| `heading(name)` | accessible name, heading role |
+
+Five more roles a visitor reads and acts on, each optionally named because a surface carries several of them and one of them usually carries no name at all:
+
+| Target            | Locates by                                              |
+| ----------------- | ------------------------------------------------------- |
+| `dialog(name?)`   | a `<dialog>` or `role="dialog"`. A closed one is absent |
+| `status(name?)`   | a live region announcing a result                       |
+| `table(name?)`    | a table, by its caption or accessible name              |
+| `row(name?)`      | a row of a table or grid, by the text of its cells      |
+| `listitem(name?)` | an item of a list, the answer to an unnamed `<li>`      |
+
+And one role that is read where it SITS rather than where it shows:
+
+| Target         | Locates by                                                                                           |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `option(name)` | an option of a select or a listbox, by its label, named inside the field holding it, with `within()` |
+
+`see(option('LinkedIn'))` asks whether the option is OFFERED, not whether it is on the screen: the options of a collapsed `<select>` are in the document and in the accessibility tree, and not one of them has a box until a visitor opens it. Which one the field is on is the `selected` modifier.
+
+The **landmarks** are the ARIA landmark set and nothing more: a closed vocabulary keeps `within()` from becoming a second selector language. Each takes an optional accessible name, for surfaces carrying several of the same region, and `region` and `form` want one in practice, since an unnamed `<section>` or `<form>` is no landmark at all:
+
+| Landmark               | Matches                                  |
+| ---------------------- | ---------------------------------------- |
+| `banner(name?)`        | the page header                          |
+| `navigation(name?)`    | a `<nav>`; name it when several          |
+| `main(name?)`          | the primary content                      |
+| `complementary(name?)` | an `<aside>`, a sidebar                  |
+| `contentinfo(name?)`   | the page footer                          |
+| `region(name?)`        | a `<section>` with an accessible name    |
+| `form(name?)`          | a named form landmark                    |
+| `search(name?)`        | a `<search>` element, or `role="search"` |
+
+### Modifiers
+
+Four, and none is a target of its own: each narrows a target by a STATE the vocabulary can already name the element of, and each is accepted by both `see` and `gone`.
+
+| Modifier                   | Asks                                                                         |
+| -------------------------- | ---------------------------------------------------------------------------- |
+| `focused(element)`         | Where the keyboard is                                                        |
+| `disabled(element)`        | Whether the control refuses input; `enabled(element)` is the other direction |
+| `selected(element)`        | Which option the field is on                                                 |
+| `valued(element, 'value')` | What the field holds: its live value, never its `value` attribute            |
+
+```typescript
+await visitor.press('Escape');
+await visitor.gone(dialog('Settings'));
+await visitor.see(focused(button('Open')));
+await visitor.see(disabled(button('Publish')));
+await visitor.see(selected(option('LinkedIn')));
+await visitor.see(valued(field('Title'), 'Launch teaser'));
+```
+
+FOCUS is a verb's business and never a golden's: the accessibility tree carries none, so a tree snapshot of a surface that handed the keyboard back and one that did not are byte-identical. ENABLEMENT the tree does carry (a disabled control reads `button "Publish" [disabled]`, a selected option `[selected]`), so a golden pins it for a whole outline and `see(disabled(...))` names the one control a test is about. The modifier also buys a direction a behavioural substitute cannot reach: clicking a disabled control is a timeout, not an answer.
+
+Scope an option to its field when a surface carries several selects, and NAME the target when you do: three constructors inside a verb is one call too deep for `unicorn/max-nested-calls`, and the name reads better besides.
+
+```typescript
+const channel = within(field('Channel'), selected(option('LinkedIn')));
+await visitor.see(channel);
+```
+
+### `within(scope, target)`
+
+Search inside a scope, the way a person would say _"the Articles link **in the nav**"_:
+
+```typescript
+await visitor.click(within(navigation(), link('Articles')));
+```
+
+Scopes compose outside-in, and any target works as one, including `testId()` when a container has no landmark role to stand on, which is every container on a device:
+
+```typescript
+await visitor.click(within(main(), within(region('Series'), link('Part 2'))));
+await visitor.tap(within(testId('event-list'), button('Bookmark')));
+```
+
+The scope is checked first, and every scope level must itself resolve to exactly one element: if the scope is the ambiguous level, the refusal names **it** rather than the target, so the fix lands on the right target.
+
+### `testId()`: the one escape hatch
+
+`testId(id)` reads `data-testid` on the web and the accessibility identifier on a device. It is the ONLY target that names something a user cannot perceive, and rule `test-id-states-what-is-missing` is an error on it: a `testId()` carries a `// testId: <what is missing>` comment on its own line or the one directly above.
+
+```typescript
+// testId: the row has no accessible name; the cells carry the data
+await visitor.click(within(testId('row-3'), button('Delete')));
+```
+
+The comment is an INVARIANT, not a rationale: it states the property of the markup that makes the escape hatch necessary, so the day the element gains a name the comment is false and the target changes with it. A `testId` with no such line is a selector, and a selector is what this vocabulary exists to refuse.
+
+## Matching
+
+A verb acts on one element, and matching is how a target becomes it: the target is resolved on the surface, every scope level first, and the result must be exactly one element whose accessible name is the name the target wrote.
+
+### Designating exactly one element
+
+**A target must match exactly one element (rule `target-matches-one-element`).** When several match, the framework refuses the action instead of taking the first one:
+
+```text
+found: Ambiguous element: link("Articles") matched 2 elements on http://site.test/ambiguous:
+  1. <a href="/articles">Articles</a>  in <nav>
+  2. <a href="/articles">Articles</a>  in <footer>
+why: A verb acts on exactly ONE element: a target that matches several is refused, never settled by the first.
+fix: designate one of them:
+  • scope it       within(navigation(), link("Articles"))   [leaves 1 of 2]   [also here: contentinfo()]
+  • other element  a heading(), button() or field() may name one thing where this does not
+read: docs/reference/linting.md#target-matches-one-element
+```
+
+The refusal is a lesson in the four parts every message carries ([Linting](linting.md#what-a-finding-says)), one part per line.
+
+Every suggestion carries what it LEAVES, so a rewrite that would keep the spec ambiguous never reads as a fix: a landmark holding every candidate is not offered at all. A candidate inside a named `<section>` is offered its region by name (`within(region("Orders"), ...)`, the name read from the section's `aria-label` or from what its `aria-labelledby` points at), since a page holds several regions; an unnamed `<section>` is no region, so it stays evidence (`in <section>`) and is never offered. The evidence also names the ACCESSIBLE name a candidate matched on when that is not its text: a role target matches the name, so `button('Delete post')` finds an `aria-label="Delete Post a"` too, and printing only the text would send you after something that never matched.
+
+On a device the same refusal reads in the device's terms: there are no landmarks to offer, so the evidence offers the accessibility identifiers it found:
+
+```text
+found: Ambiguous element: button("Bookmark") matched 3 elements on the screen:
+  1. Button "Bookmark"  [testId: event-1-bookmark]
+  2. Button "Bookmark"  [testId: event-2-bookmark]
+  3. Button "Bookmark all"
+why: A verb acts on exactly ONE element: a target that matches several is refused, never settled by the first.
+fix: designate one of them:
+  • scope it       within(testId('...'), button("Bookmark")): a screen has no landmarks, and any target works as the scope
+  • test id        testId("event-1-bookmark")   [also here: event-2-bookmark]
+  • other element  a button() or field() may name one thing where this does not
+read: docs/reference/linting.md#target-matches-one-element
+```
+
+Taking "the first match" is the failure this rule exists to prevent: the spec stays green while the visitor acts on a different element, and nothing ever reports it. Ambiguity is an authoring mistake, not something DOM order should arbitrate.
+
+### A name designates the accessible name WHOLE
+
+`link('Articles')` does not reach "Read Articles". A substring default is the shape that lets a test pass for years against the element beside the one it named, and the refusal never comes, because there is only ever one match.
+
+```typescript
+await visitor.click(link('Articles')); // exactly "Articles"
+await visitor.click(link('Articles', { exact: false })); // also "Read Articles"
+```
+
+Every named target accepts the option (`button`, `link`, `field`, `heading`, `content`, `option`, and the named landmarks) on every surface: the web compiles it to a whole-string match, the device to `==` and, opted out, to `CONTAINS`.
+
+Reach for the opt-out only when the name genuinely carries a variable part (a count, a user's name); scope with `within()` when the problem is that the same name appears twice.
+
+A name only part of an accessible name designates nothing, on every surface and at every level of a chain: `within(button('Proof of authorship'), content('Verified'))` against a button named "Proof of authorship Verified" fails on the SCOPE. The name to write is the ACCESSIBLE name, whole: what the ARIA tree (`result.tree`) prints for the element, never its text content: a button holding two inline children reads as `Experiments9` through its text and is named "Experiments 9", and a field's name is its label, which its text carries nothing of. On a device it is the element's label.
+
+## Pitfalls
+
+- **Asserting focus with a golden.** The tree carries no focus; see [§ Modifiers](#modifiers).
+- **Expecting a name to match a prefix.** It does not: write the name whole, read off the ARIA tree, or scope it with `within(...)`.
+- **Answering an ambiguity with `{ exact: false }`.** The option widens the match; ambiguity wants narrowing. Scope it.
+- **Reaching for `testId()` first.** It is the last rung, and `test-id-states-what-is-missing` asks for the line saying why. A heading, a button or a field usually names the thing already.
+- **Putting an `expect()` inside a scenario.** `no-expect-in-scenario` refuses it: a scenario is interaction, the Then is on the result.
+- **Passing a landmark to a mobile verb.** It refuses at runtime, naming the boundary. Scope with `within(testId(...), ...)` instead.
+- **Nesting three constructors in a verb call.** `unicorn/max-nested-calls` refuses it, and a named `const` reads better.
+
+## Related
+
+[Component specs](../guides/component-specs.md) · [Website specs](../guides/website-specs.md) · [Mobile specs](../guides/mobile-specs.md) · [Assertions](assertions.md) · [Tokens](tokens.md) · [Conventions](../concepts/conventions.md) · [Linting](linting.md)