@jterrazz/test 16.1.1 → 17.0.0

package/docs/09-mobile.md

@@ -1,270 +0,0 @@
-# 09 — Mobile specs (`specification.mobile`)
-
-`specification.mobile()` tests a native app on the iOS simulator — its screens (the accessibility tree a user's assistive tech sees) and its flows (tap, fill, see) — through a real XCUITest session driven by appium. It resolves and boots the simulator itself, and starts the appium server from the caller project.
-
-Use it when the subject under test is an installed native app. For a browser-rendered page use [website](08-website.md); for a JSON/HTTP API surface use [api](10-api.md).
-
-## What it specifies
-
-A mobile spec answers one question: **given this backend and this visitor, what does the native app draw on a simulator, and what does the screen read like to someone who cannot see it?** The subject is the installed app met through a deep link, driven by the accessibility tree the platform publishes. A React Native component rendered off a device is jest's for now, not this facet's ([07](07-component.md) states the boundary and the spike that would move it).
-
-## The constructor
-
-```typescript
-// specs/mobile/mobile.specification.ts
-import { specification } from '@jterrazz/test';
-import { afterAll } from 'vitest';
-
-export const { cleanup, mobile } = await specification.mobile({
-    app: { bundleId: 'com.jterrazz.fakenews' },
-    device: { name: 'iPhone 17', os: '26.5' },
-});
-
-afterAll(cleanup);
-```
-
-### Options
-
-| Option     | Description                                                                                                                                              |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `app`      | `{ bundleId }` — the installed app under test. Every `.open()` terminates and relaunches it                                                              |
-| `device`   | `{ name, os?, udid? }` — the simulator to run on, resolved through `xcrun simctl` and booted when shut down                                              |
-| `backend`  | `{ port? }` — start a declared stub backend; the handle gains `backendUrl` — see [Declared backend](#declared-backend)                                   |
-| `root`     | **Project-root override** (rule A9): where the `appium` binary is resolved from (`node_modules/.bin`). Auto-discovered from the calling file when absent |
-| `services` | A named record started with the runner and stopped with it — a `process()` for the bundler the app loads from, a database a dev build reads              |
-| `timeouts` | `{ action?, launch? }` in ms — how long this runner waits. Each field falls back to the framework's default; see [Declared timeouts](#declared-timeouts) |
-
-`device` itself takes:
-
-| `device` field | Description                                                                                    |
-| -------------- | ---------------------------------------------------------------------------------------------- |
-| `name`         | Simulator name, matched exactly (`'iPhone 17'`)                                                |
-| `os`           | OS narrowing when the name exists on several runtimes — `'26.5'` or `'iOS 26.5'`, case-relaxed |
-| `udid`         | Explicit UDID — skips name/os resolution entirely                                              |
-
-Resolution refuses rather than guesses: zero matches and several matches both fail with the full `simctl` device listing, so the fix never needs an Xcode round-trip. A shut-down simulator is booted (`simctl boot` + `bootstatus`); an already-booted one is reused as-is.
-
-**`services` is where Metro goes.** A dev build loads its JavaScript from a bundler, and until now that bundler was a `beforeAll` the repository maintained, with an `afterAll` it sometimes forgot. It is a `process()` like any other external process the framework owns, started before the app is ever launched and stopped with the specification ([17 — Services](17-services.md#process--the-one-shape-an-external-process-takes)):
-
-```typescript
-import { process, specification } from '@jterrazz/test';
-
-export const { cleanup, mobile, udid } = await specification.mobile({
-    app: { bundleId: 'com.example.app' },
-    device: { name: 'iPhone 17' },
-    services: {
-        metro: process({ command: 'expo start', ready: /Metro waiting on .*:(\d+)/u }),
-    },
-});
-```
-
-The appium server is spawned from the caller project's `node_modules/.bin/appium` on a free port and polled on `/status` until ready. On teardown the driver session ends and the server process group is terminated (SIGTERM, escalating to SIGKILL after a 2 s grace) — the same escalation as the [website](08-website.md) serve adapter.
-
-The handle destructures to `{ mobile, cleanup, udid }` (rule A3) — `udid` is the resolved simulator, handy for shelling out to `simctl` in a debugging session. With the `backend` option it additionally carries `backendUrl`.
-
-### Declared timeouts
-
-Every verb auto-waits — there is no sleep and no conditional helper. `timeouts` states how long, for the two waits a project legitimately needs to move:
-
-| `timeouts` field | The wait it budgets                                                                         | Default   |
-| ---------------- | ------------------------------------------------------------------------------------------- | --------- |
-| `action`         | one visible match, on every verb — the whole `see`/`tap`/`fill` budget, polled every 500 ms | `30_000`  |
-| `launch`         | WebDriverAgent to build and launch, on a run's first session                                | `240_000` |
-
-The defaults suit a **release** bundle: 30 s absorbs a cold app boot, the same figure playwright chose for its actionability timeout. A project driving a **dev** build pays its bundler's cold boot on top — a Metro cold start to first content measures 31–32 s, over the default — and states that wait once, on the runner, rather than sleeping inside its scenarios:
-
-```typescript
-// specs/mobile/mobile.specification.ts
-export const { cleanup, mobile } = await specification.mobile({
-    app: { bundleId: 'com.jterrazz.fakenews' },
-    device: { name: 'iPhone 17', os: '26.5' },
-    // Dev-mode Metro cold boot measured at 31-32s — over the 30s default.
-    // 45s covers the cold path with margin without hiding a real hang.
-    timeouts: { action: 45_000 },
-});
-
-afterAll(cleanup);
-```
-
-Raise it to the slowest **honest** path and no further: the timeout is what turns a hang into a legible refusal naming the element and what was on screen instead.
-
-## The chain
-
-### One terminal action: `.open(deepLink?, scenario?)`
-
-`.open()` is terminal and deterministic: it **terminates and relaunches the app** (fresh state every spec), applies the deep link when given, runs the scenario, then captures the final screen — the projected accessibility tree plus the visible texts:
-
-```typescript
-test('shows the events feed behind its deep link', async () => {
-    // Given - the events screen
-    const result = await mobile.open('news://events');
-
-    // Then - one golden covers the whole screen
-    expect(result.screen).toMatch('events.screen.json');
-});
-```
-
-Without a deep link, the app opens on its launch screen. There is **one driver session per runner**, created lazily on the first `.open()` and reused — the expensive part is WebDriverAgent startup, not the app relaunch.
-
-### Open scenarios — the When
-
-A scenario is the interaction that happens **before** the capture — the open's When. The capture always reflects the **final** screen state, after the scenario ran:
-
-```typescript
-test('bookmarks an event from its detail screen', async () => {
-    // Given - a visitor on the events feed
-    const result = await mobile.open('news://events', async (visitor) => {
-        // When - they open the Fauci event and bookmark it
-        await visitor.tap(button('Enquête Fauci COVID-19'));
-        await visitor.see(content('12 rapports publiés'));
-        await visitor.tap(button('Bookmark'));
-    });
-
-    // Then - the capture reflects the screen after the interaction
-    expect(result.content).toContain('Bookmarked');
-});
-```
-
-**No `expect()` inside a scenario (rule W1).** A scenario is pure interaction — assertions live in the Then, on the returned result.
-
-The element vocabulary is [13 — Elements](13-elements.md)'s, the same one the website and component facets name things with — there is no CSS, no XPath and no raw predicate surface. What a device does with it is this chapter's, and it is three things.
-
-**The verbs are three.** `tap(element)` is the device's word for a click, `fill(element, value)` fills a text field, and `see(element)` is the only synchronization primitive. There is no `gone()` here: the adapter cannot answer honestly for absence on an XCUITest tree. Every verb polls until at least one visible match exists (default 30 s, sized for a cold app boot), then enforces the verb's cardinality; there are no sleeps anywhere in the framework. Actionability includes **scroll-into-view**: when a descriptor matches nothing visible but an off-screen element exists, the adapter scrolls it into view once (directly by element id) and keeps polling — elements buried in very heavy screens (a full-page WebView) may still be out of reach, so prefer a deep link then.
-
-**Four descriptors reach a screen** — `button(name)` (accessible label, `XCUIElementTypeButton`), `field(label)` (accessible name or value, text and secure-text fields), `content(text)` (any element whose label or value IS the text — the whole-name default of [13 — Elements](13-elements.md#a-name-designates-the-accessible-name-whole), compiled to `==`; `{ exact: false }` compiles to `CONTAINS`) and `testId(id)` (the accessibility identifier, rule W2's escape hatch, with the line saying what the element lacks). The link, heading, dialog, table and option roles, the landmarks and the state modifiers are not part of a device's tree: passing one to a mobile verb refuses at runtime with a message naming the boundary.
-
-**W3 is relaxed for `see()` alone.** `tap` and `fill` refuse an ambiguous descriptor and print the candidates with their accessibility identifiers; `see()` does not — [13 — Elements § `see()` and `gone()`](13-elements.md#see-and-gone-are-the-synchronization) says why, once.
-
-A mobile scope is any descriptor, most often a `testId()` on the containing view, because iOS has no landmarks:
-
-```typescript
-await visitor.tap(within(testId('event-list'), button('Bookmark')));
-```
-
-`see()` resolving through render work is the point: a deep link into a Metro cold bundle, a network round-trip, an animation — the poll absorbs them all without a single sleep.
-
-## The result
-
-| Member           | Type           | Description                                                                  |
-| ---------------- | -------------- | ---------------------------------------------------------------------------- |
-| `result.screen`  | `JsonAccessor` | The projected accessibility tree — the one-golden-per-screen surface         |
-| `result.content` | `TextAccessor` | The visible texts, one per line in reading order — the scalpel for one probe |
-
-### The `screen` golden — one per screen
-
-`result.screen` is the **stable, assertion-friendly projection** of the XCUITest page source. The raw source is deep and noisy — React Native wraps every view in layers of unlabeled `XCUIElementTypeOther` nodes — so the projection collapses it: wrapper nodes with no label, no value and no identifier are dropped (their children hoisted), an element repeated as its own child appears once, type names lose the `XCUIElementType` prefix, and a value or identifier merely echoing the label is omitted:
-
-```json
-{
-    "type": "Application",
-    "label": "SigNews",
-    "children": [
-        { "type": "StaticText", "label": "Signals" },
-        { "type": "Button", "label": "Enquête Fauci COVID-19" },
-        { "type": "TextField", "label": "Email", "value": "a@b.test", "identifier": "email-field" }
-    ]
-}
-```
-
-It is the one golden a screen needs:
-
-```typescript
-test('renders the events feed', async () => {
-    // Given - the events screen
-    const result = await mobile.open('news://events');
-
-    // Then - the whole projected tree matches one golden
-    expect(result.screen).toMatch('events.screen.json');
-});
-```
-
-The tree describes the **whole mounted hierarchy**, including rows below the fold; `result.content` carries only what is visible. Volatile parts (dates, counters) are covered by the usual `{{token}}` grammar ([15 — Tokens](15-tokens.md)); generate with `TEST_UPDATE=1`.
-
-## Unique here
-
-### Declared backend
-
-A native app usually talks to an API. The `backend` option starts a small **stub backend** (plain `node:http`, no extra dependency) with the runner; what it serves is declared per chain, as [contracts](16-contracts.md) — the feature's `contracts/` facade, exactly the form `api`/`jobs` use:
-
-```typescript
-// specs/mobile/mobile.specification.ts
-export const { backendUrl, cleanup, mobile } = await specification.mobile({
-    app: { bundleId: 'com.jterrazz.fakenews' },
-    backend: { port: 4820 },
-    device: { name: 'iPhone 17', os: '26.5' },
-});
-
-afterAll(cleanup);
-```
-
-```typescript
-// specs/mobile/events/feed.spec.ts
-import newsroom from './contracts/newsroom.contracts.js';
-
-test('renders the events feed from the declared backend', async () => {
-    // Given - the backend under contract for this chain
-    const result = await mobile.intercept(newsroom).open('news://events');
-
-    // Then - the screen rendered what the stub declared
-    expect(result.screen).toMatch('events.screen.json');
-});
-```
-
-| `backend` field | Description                                                                       |
-| --------------- | --------------------------------------------------------------------------------- |
-| `port`          | Fixed port — pins a stable stub URL across runs. Default: a free OS-assigned port |
-
-**The ownership boundary.** The framework owns the simulator and the appium server — it does NOT own the JS bundler: Metro belongs to the caller's repo, exactly like `next build` belongs to a website's. So nothing is injected anywhere; the handle exposes `backendUrl` and **the caller wires it into its own bundler env** (e.g. `EXPO_PUBLIC_API_URL=<backendUrl> npx expo start`). This is why `port` exists: Metro inlines `EXPO_PUBLIC_*` values at bundle-serve time, and a stable port lets a warm Metro survive between runs instead of re-bundling against a fresh URL.
-
-The stub behaves exactly as on the website facet ([08 — Website specs](08-website.md#declared-backend)): it **resets between chains** (one chain = one terminal action); selection is the shared queue (first non-exhausted match wins, no `times` = unlimited); a request matching no declared contract is answered **501 and recorded**, and the `.open()` then **throws** an error enumerating every unmatched request (method, path, count) — screenshots and other failure evidence are captured first, as always. A chain with zero contracts leaves the stub unguarded.
-
-### Evidence on failure
-
-When a scenario throws — an element never appears, a `see()` times out — the error carries a screenshot of the state the scenario died in, referenced by its temp path in the error message. A timeout additionally includes a compact excerpt of the labels currently on screen, so the failure reads without relaunching anything. The original error is never masked.
-
-### Requirements — what the machine must have
-
-Provisioning the simulator environment is not this package's job. The framework needs, in this order:
-
-1. **Xcode + an iOS simulator** — `xcrun simctl list devices` must show the device named in `device`.
-2. **The app installed on that simulator** — `.open()` launches by bundle id; it does not build or install. Install with your build tooling (`xcrun simctl install <udid> <path>.app`, Expo/EAS, xcodebuild).
-3. **appium + webdriverio + the XCUITest driver** in the caller project — both are optional peer dependencies:
-
-```bash
-npm install -D appium webdriverio && npx appium driver install xcuitest
-```
-
-Calling `specification.mobile()` (or `.open()`) without them throws exactly that guidance — there is nothing else to search for.
-
-### Folder layout
-
-```
-specs/mobile/
-├── mobile.specification.ts     # runner at the facet ROOT (rule C1)
-└── <domain>/
-    ├── <aspect>.spec.ts
-    ├── _expected/                # ALL expected fixtures, FLAT (*.screen.json, …)
-    └── contracts/               # what the declared backend serves — with the `backend` option
-        ├── newsroom.contracts.ts
-        └── http/…
-```
-
-No `_seeds/` or `_requests/` — `specification.mobile()` has no `services` option and no request-file format; `.open()` calls are inline, and the golden is always `_expected/<name>`.
-
-## Pitfalls
-
-- **Using `expect()` inside a scenario callback.** Forbidden (rule W1) — the scenario is the When; assertions belong on the result the `.open()` promise resolves to.
-- **The first session builds WebDriverAgent (~40 s, once per simulator).** Subsequent sessions on a warm simulator are seconds. Budget the first run; do not "fix" it with retries.
-- **Passing a landmark (`main()`, `navigation()`) to a mobile verb.** They are website concepts — iOS has no ARIA regions; the runtime refusal points at `within(testId('…'), …)` as the scoping tool.
-- **Reaching for `testId()` as the default locator.** It exists as an escape hatch (rule W2 warns) — prefer `button`/`field`/`content`, the vocabulary the accessibility tree exposes to a real user.
-- **Expecting `.open()` to preserve app state between specs.** It never does — every open terminates and relaunches the app; a flow that spans screens belongs in ONE scenario.
-- **Asserting on off-screen content with `result.content`.** `content` carries only _visible_ texts; the mounted-but-offscreen rows live in `result.screen`. Use the golden for the whole list, `content` for what the user currently sees.
-- **Calling `specification.mobile()` without appium installed.** The error names the exact fix — `npm install -D appium webdriverio && npx appium driver install xcuitest` — there is no silent fallback.
-- **Pointing `device.name` at an ambiguous simulator.** When the same name exists on several OS runtimes the constructor refuses with the listing — narrow with `os:` (or pin `udid:`), do not delete simulators to make it pass.
-- **Calling `.intercept()` without the `backend` option.** It throws immediately, naming the fix: add `backend: { … }` to the `specification.mobile()` options — a chain's `.http` exchanges need a stub to serve them.
-- **Sleeping around a slow boot instead of declaring it.** A dev bundle that boots past the 30 s default makes every verb refuse; the answer is `timeouts: { action: … }` on the runner, once — an arbitrary wait inside a scenario is untyped, per-spec, and hides the next regression.
-- **Expecting the framework to point the app at the stub.** It never touches the bundler — that is the caller's territory. Wire `backendUrl` into your own bundler env (`EXPO_PUBLIC_API_URL`), and pin `port` so a warm Metro keeps its inlined URL.
-
-## Related
-
-[02 — Developing](02-developing.md) · [14 — Assertions](14-assertions.md) · [15 — Tokens](15-tokens.md) · [08 — Website specs](08-website.md)

package/docs/10-api.md

@@ -1,264 +0,0 @@
-# 10 — API specs (`specification.api`)
-
-`specification.api()` tests an HTTP API through real requests. Your app runs **in this process**, built by the `server` factory from the services the runner started in real containers — so a request reaches it without a socket, and a contract, a clock and a golden all mean something because the app shares this process's world.
-
-Use it when the subject under test is an HTTP surface. For background pipelines use [jobs](11-jobs.md); for binaries use [cli](12-cli.md).
-
-## What it specifies
-
-An api spec answers one question: **given this state and this request, what does the HTTP app answer, and what does it leave behind?** The subject is the assembled app met through its own entry — the handler chain, the middleware, the serialisation, the database writes — and the request is a complete HTTP exchange, written as a file a person can read. A single handler function called directly is a module test's ([05](05-module-tests.md)); a repository against a real database with no HTTP in sight is an integration spec's ([06](06-integration.md)).
-
-### The app runs in THIS process
-
-| Aspect             | What it means                                                              |
-| ------------------ | -------------------------------------------------------------------------- |
-| Your app           | In-process, built by `server(services)` — no container, no socket          |
-| Services           | Real containers, started by testcontainers from each handle's own defaults |
-| What it proves     | Application logic against real databases, caches and processes             |
-| Parallel isolation | Per-worker schema / db-index / file copy (rule G2)                         |
-
-Because the app shares this process, three things the framework offers are real here and nowhere else: `.intercept()` (msw runs in-process), `.clock()` (it pins the `Date` the app reads), and a golden of the response the app actually built. What the SHIPPED artefact does — its Dockerfile, its wiring, its networking — is a deployment probe, and this facet does not claim it.
-
-`docker/<service>/init.sql` runs when the corresponding service starts, under the kebab-case of its record key. See [services](17-services.md).
-
-## The constructor
-
-```typescript
-// specs/api/api.specification.ts
-import { afterAll } from 'vitest';
-import { specification, postgres, redis } from '@jterrazz/test';
-import { createApp } from '../../src/app.js';
-
-export const { api, cleanup } = await specification.api({
-    services: {
-        db: postgres(), // → reported as "db", init from docker/db/
-        analyticsDb: postgres(), // → "analytics-db", init from docker/analytics-db/
-        cache: redis(), // → "cache"
-    },
-    server: ({ db, analyticsDb, cache }) =>
-        createApp({
-            databaseUrl: db.connectionString,
-            analyticsDatabaseUrl: analyticsDb.connectionString,
-            redisUrl: cache.connectionString,
-        }),
-    // root: absent → auto-discovery (see below)
-});
-
-afterAll(cleanup);
-```
-
-### Options
-
-| Option     | Required                     | Description                                                                                                                             |
-| ---------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `services` | yes (if the app needs infra) | Named record of service factories (`postgres()`, `redis()`, `sqlite()`). Keys are your test vocabulary — see [services](17-services.md) |
-| `server`   | yes                          | `(services) => app` — receives the started services record, fully typed (rule A8)                                                       |
-| `root`     | no                           | Override for root resolution — reserved for cases where the convention is not enough (rule A9)                                          |
-
-### Root resolution (rule A9)
-
-Without `root`, the framework walks **up from the specification file** to the **nearest** directory carrying `package.json` — the package being tested, not the repository around it. Passing a `root` that points at the directory the walk would have found anyway is redundant (future lint warning).
-
-## The chain
-
-### Setups (chainable)
-
-| Setup                             | Description                                                                                                                     |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `.seed('file.sql')`               | Load `_seeds/file.sql` into the database                                                                                        |
-| `.seed('file.sql', { database })` | Target a database by its record key — **mandatory with ≥ 2 databases, forbidden with 1** (rule A7)                              |
-| `.headers({ 'Name': 'value' })`   | Set request headers; repeated calls merge                                                                                       |
-| `.intercept(contract)`            | Mock an outgoing HTTP call with a declared [contract](16-contracts.md)                                                          |
-| `.intercept(trigger, response)`   | Inline intercept for one-off cases                                                                                              |
-| `.clock('2026-03-04T09:30:00Z')`  | Pin the app's `Date` for this chain, released when the action resolves ([18](18-conventions.md#time--one-primitive-two-depths)) |
-
-Contracts are **strict** (rule D7): once a chain declares one, every outgoing request must match a declared, non-exhausted contract or the spec fails with an explicit "Unmatched outgoing HTTP request" error (see [contracts](16-contracts.md#strict-by-construction-rule-d7)). `.intercept()` and `.clock()` both work because the app runs in THIS process: msw intercepts its outgoing requests, and the pinned `Date` is the one it reads.
-
-```typescript
-test('serves french content', async () => {
-    // Given - headers inline
-    const result = await api.headers({ 'Accept-Language': 'fr' }).get('/welcome');
-
-    // Then
-    expect(result.response.body).toEqual({ message: 'Bienvenue' });
-});
-```
-
-#### Isolation between specs (rules B1, B7)
-
-Databases are **reset at the start of every chain**. A spec never depends on a previous spec, and there is no "flow" mode — sequential scenarios are expressed through seeds:
-
-```typescript
-test('starts clean between specs', async () => {
-    // Given - nothing (every chain resets the databases: one spec = ONE action)
-    const result = await api.get('/orders');
-
-    // Then
-    await expect(result.table('orders', { database: 'db' })).toBeEmpty();
-});
-```
-
-### Actions (terminal)
-
-Exactly one per chain (rule B1/B2). Each executes the spec and resolves to the result.
-
-| Action                  | Description                                                   |
-| ----------------------- | ------------------------------------------------------------- |
-| `.request('file.http')` | Execute the complete request from `_requests/file.http`       |
-| `.get(path)`            | Inline GET — for simple cases where a file would be excessive |
-| `.post(path, body?)`    | Inline POST                                                   |
-| `.put(path, body?)`     | Inline PUT                                                    |
-| `.delete(path)`         | Inline DELETE                                                 |
-
-The inline `body?` of `.post()` / `.put()` is a plain object, JSON-serialized with a `Content-Type: application/json` default header. There is no filename form inline — file-based requests always go through `.request('file.http')`, whose body section is sent **raw**: the surrounding blank lines are trimmed, but everything between is preserved byte-for-byte (interior double spaces, indentation, and non-JSON text are intact).
-
-There is no `.run()` and no label argument: the vitest test name is the spec's only description (rule B3).
-
-```typescript
-test('returns 404 with a useful body', async () => {
-    // Given - empty database
-    const result = await api.get('/users/999');
-
-    // Then - inline assertions when a fixture file would be excessive
-    expect(result.status).toBe(404);
-    expect(result.response.body).toEqual({ error: 'User 999 not found' });
-});
-```
-
-### `.http` request files — full format
-
-Requests live in `_requests/`, one file per request, extension `.http` (rule C2). A request file is the **complete** request: method + path on the first line, then headers, then a blank line, then the body.
-
-```http
-### _requests/create-user.http
-POST /users
-Content-Type: application/json
-Accept-Language: fr
-
-{ "name": "Alice" }
-```
-
-Format rules:
-
-- First line: `METHOD /path` — the file must start with it (rule C2). The path is relative to the app under test.
-- Header lines: `Name: value`, one per line, immediately after the request line.
-- Blank line, then the body (optional — a GET usually has none).
-- Executed with `api.request('create-user.http')` — the argument is the file name inside the feature's `_requests/` folder.
-
-Expected responses live in `_expected/`, like every other expected fixture, same extension, and start with a status line (rule C3):
-
-```http
-### _expected/user-created.http
-HTTP/1.1 201 Created
-Content-Type: application/json
-Location: /users/{{uuid#user}}
-
-{ "id": "{{uuid#user}}", "name": "Alice" }
-```
-
-- First line: `HTTP/1.1 <status>` — mandatory.
-- Headers are matched as a **subset**: listed headers must match, unlisted headers are unconstrained (rule C3).
-- Body and headers both accept `{{token}}` placeholders, including `#ref` captures — `{{uuid#user}}` above must be the _same_ UUID in the `Location` header and the body. See [tokens](15-tokens.md).
-
-## The result
-
-The result of an API action exposes read-only accessors (rule D1); all assertions go through `expect()`:
-
-| Member                      | Type             | Description                                                                      |
-| --------------------------- | ---------------- | -------------------------------------------------------------------------------- |
-| `result.status`             | `number`         | HTTP status code — assert with native `expect(...).toBe(...)`                    |
-| `result.response`           | response subject | Full response (status + headers + body) — subject for `toMatch`                  |
-| `result.response.body`      | parsed body      | Raw body for native assertions (`toEqual`, `toMatchObject`)                      |
-| `result.table(name, opts?)` | table subject    | Database table — subject for `toMatchRows` / `toBeEmpty` (async, `await expect`) |
-
-`expect(result.response).toMatch('user-created.http')` resolves against `_expected/`, like every other subject (rule D3) — there is no per-subject resolution. The full matcher reference is in [assertions](14-assertions.md).
-
-Beyond the result, the `specification.api()` handle destructures to `{ api, cleanup, docker }`. The `docker(containerId)` reader lazily runs `docker inspect` and returns a `ContainerAccessor` for an arbitrary container id — usable with `await expect(docker(id)).toBeRunning()` and the sync read accessors (`.exists`, `.status`, `.file(path)`, logs). An unknown id yields `exists: false` instead of throwing. (`specification.jobs()` has no `docker` member — jobs never spawn containers.)
-
-## Unique here
-
-### Full example — a multi-database order flow
-
-```http
-### _requests/new-order.http
-POST /orders
-Content-Type: application/json
-
-{ "sku": "KB-42", "quantity": 1 }
-```
-
-```http
-### _expected/order-created.http
-HTTP/1.1 201 Created
-Content-Type: application/json
-Location: /orders/{{uuid#order}}
-
-{
-    "id": "{{uuid#order}}",
-    "status": "pending",
-    "total": "{{number}}",
-    "createdAt": "{{iso8601}}",
-    "paymentIntent": { "orderId": "{{uuid#order}}", "expiresAt": "{{iso8601}}" }
-}
-```
-
-```typescript
-// specs/api/orders/orders.spec.ts
-import { expect, test } from 'vitest';
-import { match } from '@jterrazz/test';
-import { api } from '../api.specification.js';
-
-test('ingests an order event into analytics', async () => {
-    // Given - catalog in the main database, analytics empty
-    const result = await api.seed('catalog.sql', { database: 'db' }).request('new-order.http');
-
-    // Then - one row per database, targeted by record key
-    await expect(result.table('orders', { database: 'db' })).toMatchRows({
-        columns: ['status'],
-        rows: [['pending']],
-    });
-    await expect(result.table('events', { database: 'analyticsDb' })).toMatchRows({
-        columns: ['type'],
-        rows: [['order_created']],
-    });
-});
-
-test('returns the created order with consistent ids', async () => {
-    // Given
-    const result = await api.seed('catalog.sql', { database: 'db' }).request('new-order.http');
-
-    // Then - {{uuid#order}} appears 3 times (Location header included) → all equal
-    expect(result.response).toMatch('order-created.http');
-});
-
-test('links the analytics event to the created order', async () => {
-    // Given
-    const result = await api.seed('catalog.sql', { database: 'db' }).request('new-order.http');
-
-    // Then - same id on both sides, without ever knowing its value
-    await expect(result.table('orders', { database: 'db' })).toMatchRows({
-        columns: ['id', 'status'],
-        rows: [[match.ref('order'), 'pending']],
-    });
-    await expect(result.table('events', { database: 'analyticsDb' })).toMatchRows({
-        columns: ['order_id', 'type'],
-        rows: [[match.ref('order'), 'order_created']],
-    });
-});
-```
-
-> This project declares two databases, so `database:` is mandatory on every `.seed()` and `.table()` (rule A7). With a single database you would write `api.seed('catalog.sql')` and `result.table('orders')` — and adding `database:` would be forbidden as redundant.
-
-The app runs in THIS process, always: there is no second mode, no container binding and no `TEST_MODE`. Why compose mode left, and what was weighed against keeping it: [ADR-007](decisions/007-compose-mode-leaves-the-package.md).
-
-## Pitfalls
-
-- **Omitting `database:` with ≥ 2 databases, or passing it with 1** — both are convention violations (rule A7).
-- **Expecting unlisted response headers to be constrained.** Response `_expected/*.http` header matching is subset-only; if a header must be _absent_, that is not expressible in the file — assert on it in code.
-- **Chaining two actions** (`api.get(...).get(...)`) or reusing state across tests. One chain = one terminal action; databases reset per chain (rules B1, B7).
-- **Forgetting that `.intercept()` is strict.** After the first `.intercept()`, an unmatched or queue-exhausted outgoing request fails the spec (rule D7).
-- **Putting the request body in the test file when it has any substance.** Requests of more than a line or two belong in `_requests/*.http` — inline `.post()` is for trivial cases.
-
-## Related
-
-[11 — Jobs specs](11-jobs.md) · [14 — Assertions](14-assertions.md) · [15 — Tokens](15-tokens.md) · [16 — Contracts](16-contracts.md) · [17 — Services](17-services.md)