@jterrazz/test 15.3.0 → 16.1.0

package/docs/README.md

@@ -0,0 +1,36 @@
+# @jterrazz/test — the corpus
+
+The manual of this repository: what the framework is, how it is changed, what proves a change, how it is released, and one chapter per subject it holds. The vitrine is the root `README.md`; the brief a session opens first is the root `AGENTS.md`.
+
+| Chapter                                     | Holds                                                                                                                                                             |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [01 — Architecture](01-architecture.md)     | The runner model behind the six constructors, the five source trees and their edges, the seven enforcement channels, the four entries, what the tarball publishes |
+| [02 — Developing](02-developing.md)         | The repository's own loop and what a change owes; then install, first specs, the vitest preset and its helpers                                                    |
+| [03 — Testing](03-testing.md)               | The vitest projects, the generated capability matrix, the layered reading, the coverage ratchet, the meta-test channel, what CI runs                              |
+| [04 — Operating](04-operating.md)           | The npm release; the peers a consumer brings — required, optional, the provider's exact pin, the native seams; Node 24; the ARIA dialect                          |
+| [05 — Module tests](05-module-tests.md)     | The majority kind: what a `*.test.ts` beside its module may and may not do — `mockOf`, `vi.fn`, `clock`, `intercept`, `vi.stubEnv`, `*.fixtures.ts`, `test.each`  |
+| [06 — Integration specs](06-integration.md) | `specification.integration()`: a module against real services or a golden — `.call()`, `value`/`error`, the `integration()` project                               |
+| [07 — Component specs](07-component.md)     | `component`: a rendered unit in Chromium — the chain, the visitor, `tree`/`html`, the `component()` project, the hook and DOM-function recipes                    |
+| [08 — Website specs](08-website.md)         | `specification.website()`: `.fetch()` / `.visit()`, visit scenarios, declared backends, the `head` golden                                                         |
+| [09 — Mobile specs](09-mobile.md)           | `specification.mobile()`: `.open()`, simulator resolution, open scenarios, the `screen` golden                                                                    |
+| [10 — API specs](10-api.md)                 | `specification.api()`: options, the in-process app, `.http` request files, inline actions, seeds, intercepts                                                      |
+| [11 — Jobs specs](11-jobs.md)               | `specification.jobs()`: in-process pipelines, `.trigger()`, provider error cases                                                                                  |
+| [12 — CLI specs](12-cli.md)                 | `specification.cli()`: `.exec()`, `.env()`, fixtures and projects, `<case>.spec.yaml` documents, the three doors, services, Docker-aware mode                     |
+| [13 — Elements](13-elements.md)             | The one element vocabulary: descriptors, modifiers, verbs, `see()` semantics, W3 and its evidence, `within()`, exact names, `testId`                              |
+| [14 — Assertions](14-assertions.md)         | The reference: every matcher, grouped by subject, sync/async rules, `toMatch` resolution, diffs                                                                   |
+| [15 — Tokens](15-tokens.md)                 | The `{{token}}` grammar: all 21 tokens, `#ref` captures, `match.*`, and update mode end to end                                                                    |
+| [16 — Contracts](16-contracts.md)           | `defineContract` / `defineContracts`, the facade layout, selection, provider builders, `intercept()` and its origin, streams, the browser transport               |
+| [17 — Services](17-services.md)             | `postgres` / `redis` / `sqlite` / `process`, the services record, init scripts, per-worker isolation, the optional peer each one names                            |
+| [18 — Conventions](18-conventions.md)       | The constitution: the principles, the fork, the doubles ladder, the rule families, the backlog, what stays human, the naming recap, retro-propagation (K1)        |
+| [19 — Linting](19-linting.md)               | The oxlint plugin (`@jterrazz/test/oxlint`), the conventions checker, and the GENERATED seven-channel rule catalogue                                              |
+
+The decisions this package alone took stand in [`decisions/`](decisions/), numbered in the order they were taken, the mold `_template.md` beside them. A decision that spans several repositories belongs to the corpus that spans them. The generated API reference is [`reference/`](reference/) — a projection of the source, never authored by hand.
+
+## How to read it
+
+- **01 to 04 are the spine**, and they answer for the repository itself: what it is, how it is changed, what proves a change, how it ships.
+- **05 to 12 are the kinds of test, in the order the fork asks them.** A module test needs no runner and has no folder (05); everything below it is an assembled product met through an entry. Read 02, then the one chapter matching what you specify.
+- **13 to 17 are shared references.** The element vocabulary reaches every rendered surface; assertions and the token grammar reach every facet; contracts apply wherever a facet meets the network, services wherever it has a database. The kind chapters link into them and restate nothing.
+- **18 and 19 cover enforcement.** 18 is the constitution — the principles and the criteria no machine settles. 19 documents the static plugin and the checker, and carries the generated catalogue, sourced from `src/lint/manifest.ts`. The chapters explain and illustrate; the constitution and the catalogue decide.
+
+Every kind chapter (05 to 12) is written on the same seven sections — **What it specifies · The constructor · The chain · The result · Unique here · Pitfalls · Related** — so the reader who learned one facet already knows where to look in the next. All examples use the Given/Then comment convention the framework itself enforces (rule B4).

package/docs/decisions/001-v9-conventions-on-three-channels.md

@@ -0,0 +1,50 @@
+# ADR-001: v9 — conventions enforced on three channels
+
+**Status:** Accepted
+**Date:** 2026-07-17
+
+Retroactive record, written 2026-09-04 from the v9 design lock (2026-07-17)
+and the `@jterrazz/test@9.0.0` ship (2026-07-18, after a multi-agent review
+campaign). Moved into this repository 2026-09-06, from the OS wiki where it
+was ADR-003 — this package alone can falsify it, and the normative spec was
+always here.
+
+## Context
+
+Testing conventions lived in prose and review habits; every consumer repo
+drifted its own way, and partial assertions ("status is 200") hid silent
+failures.
+
+## Decision
+
+v9 is specification-first: three constructors (`specification.api/jobs/cli`),
+one `{{token}}` grammar across every fixture kind, and golden files (`.http`
+_requests/responses, full-output text snapshots) as the default assertion — a
+partial probe must earn its place as a deliberate scalpel.
+
+Crucially, every convention is enforced on one of THREE channels, or
+documents why it cannot be:
+
+1. **Static** — oxlint rules living IN this package, so a rule versions with
+   the API it describes, wired by `@jterrazz/typescript` through composable
+   presets (`compose(node, testing)`).
+2. **Meta-tests** — executed truths: every token matcher tested both ways,
+   update-mode fixtures re-verified on the next run.
+3. **Runtime** — strict errors: an outbound request with no matching intercept
+   fails the spec.
+
+Any newly discovered defect class must, in the same change, produce a rule on
+one of the channels — the package's "rule K".
+
+## Consequences
+
+- Product specs live under `specs/<facet>/<domain>/`; unit tests are siblings
+  of their module. A consumer's own conventions derive from this package,
+  except where its doctrine states a more specific shape — the first such case
+  is jterrazz-os's `docs/decisions/006-cli-specs-mirror-the-command-tree.md`.
+- Migrations proved the value immediately: strict intercepts caught a real
+  production-class bug in a consumer (an undrained handler), and dead test
+  layers were deleted by the dead-fixture checker.
+- The docs are code: each rule's normative text lives in its implementation's
+  metadata and the catalog is generated — hand-synced convention documents are
+  banned by construction.

package/docs/decisions/002-the-statique-channel-holds-only-what-upstream-does-not.md

@@ -0,0 +1,49 @@
+# ADR-002: the statique channel holds only what upstream does not
+
+**Status:** Accepted
+**Date:** 2026-09-15
+
+## Context
+
+The statique channel grew by writing a rule for every mechanizable convention,
+without asking whether oxlint already carried one. Four hygiene rules ended up
+restating rules of oxlint's own `vitest` plugin — J1 (`.only`/`.skip`), J3 (an
+assertion per test), J4 (unique literal titles), J5 (a lowercase title).
+
+That cost nothing while the plugin was off. `@jterrazz/typescript` v10 turns it
+on over the test globs in every profile, so a consumer composing
+`compose(node, testing)` gets both layers: one violation reported twice, two
+ids to suppress, and two normative sentences that have to be kept in step by
+hand — the drift this package's docs-as-code inversion exists to prevent.
+
+## Decision
+
+A convention an upstream oxlint rule already enforces belongs to that rule. The
+statique channel holds only the residue: what no loaded plugin carries.
+
+Equivalence is proved before a rule is deleted, on this package's own fixtures
+and on both the installed oxlint and the version the preset pins — every
+invalid sample of the rule's test must fire the upstream rule, and every valid
+sample must stay silent. A rule that catches something upstream misses is kept
+and narrowed to that residue.
+
+The four were proved equivalent and deleted (`vitest/no-focused-tests` +
+`vitest/no-disabled-tests`, `vitest/expect-expect`, `vitest/no-identical-title`,
+`vitest/prefer-lowercase-title`). J2, the arbitrary-sleep ban, has no upstream
+counterpart and stays.
+
+## Consequences
+
+- Breaking for consumers: `jterrazz/j1-no-only-skip`,
+  `jterrazz/j3-no-expectless-test`, `jterrazz/j4-unique-test-names` and
+  `jterrazz/j5-lowercase-title` no longer exist, and a config still naming one
+  fails oxlint's unknown-rule check.
+- The hygiene floor now reaches this package only through the base preset. A
+  repository that adopts the conventions without `@jterrazz/typescript` wires
+  `plugins: ['vitest']` itself — the catalogue chapter says which rules.
+- One behaviour is configuration, not code: `prefer-lowercase-title` flags an
+  all-caps first word (`VALID_CATEGORIES`, `HTTP`, `DI`) that J5 exempted, and
+  `allowedPrefixes` restores the exemption.
+- The rule of growth changes with it. A new mechanizable defect class (K1) is
+  now searched for upstream first, and a rule is written here only where the
+  search comes back empty.

package/docs/decisions/003-a-rendered-component-is-a-facet-on-vitest-browser-mode.md

@@ -0,0 +1,84 @@
+# ADR-003: A rendered component is a facet, on Vitest Browser Mode
+
+**Status:** Accepted
+**Date:** 2026-09-19
+
+## Context
+
+The estate tested its UI in two dialects at once. A page spec said
+`click(link('Articles'))` against a real Chromium and goldened what the page
+MEANT; beside it, in the same repository, a component test said
+`render / screen / fireEvent / waitFor` against `happy-dom` with a scripted
+`fetch`, and goldened nothing. Same product, same reader, two vocabularies —
+and the second proves the least of the two, because the thing it renders never
+met a browser.
+
+The corpus had sanctioned that split. `docs/18-conventions.md` and the agent
+skill both said a component test "needs vitest alone", on the ground that the
+framework is for a SURFACE and a component has none. The reading was wrong in
+one word: a component has no surface it is SERVED through, but it needs
+everything the framework owns — a real browser, a Vite pipeline, a network
+double, a golden engine, an element vocabulary. Rule I2's own message had been
+saying so all along: "a test needing more than its module is a specification".
+
+What forced a decision now is that the estate has a UI to migrate (a console's
+42 tests, a browser extension's DOM renderer, a web app's string renderer) and
+every one of them would otherwise be written a third time.
+
+## Decision
+
+A rendered component is a FACET of `@jterrazz/test`, running in Vitest Browser
+Mode on the `playwright` peer the website facet already drives.
+
+It is the facet with **no constructor**. A component starts nothing — no
+server, no database, no binary, no simulator — so there is no handle to
+destructure and no `*.specification.ts` to hold it. The chain is exported
+directly (`component.intercept(…).wrap(…).render(<X />, scenario)`), and what
+every render of a project shares belongs to the PROJECT: `component()` in
+`vitest.config.ts`.
+
+Its test file sits **beside its subject**, as a module test does, and the
+suffix states the kind: `<file>.test.ts` is a module, `<file>.test.tsx` is a
+component. `unit()` excludes `.test.tsx`; `component()` collects exactly those.
+
+The package keeps **one specifier**. A page cannot load the node entry, so
+`exports["."]` gains a `browser` condition resolving to a second build of the
+same surface, in which every node-only name is a stub that throws where it was
+called. The split is the runtime's, never the facets'.
+
+Weighed and rejected:
+
+- **A Node-side gallery** — Playwright driven from the test process, one
+  browser context per render. Measured at ~15 s against 0.6–1.1 s per file for
+  Browser Mode, and it needs an undeclared `vite` to build what it serves.
+- **Playwright Component Testing** — a second runner beside vitest, with its
+  own config, its own reporters and its own assertion library. The estate has
+  one runner on purpose.
+- **`happy-dom` + Testing Library** — the status quo. Two vocabularies, and the
+  cheaper one is the one that proves least.
+- **A second specifier, `@jterrazz/test/browser`** — considered and dropped: it
+  makes every test file remember which entry it may import, and needs a rule to
+  enforce the memory. One specifier and a condition costs nothing at the call
+  site.
+
+## Consequences
+
+- `happy-dom`, `jsdom` and `@testing-library/*` leave the estate's test
+  vocabulary. Rules E5, E5b, F6 and G4 refuse them and name the move; E6
+  refuses a hand-rolled `browser:` project, because the provider pin, the
+  service worker, the JSX transform and the cold-cache pre-bundling are four
+  ways for a run to pass here and fail on the next machine.
+- A component spec and a page spec now read alike: same descriptors, same
+  verbs, same W3 ambiguity refusal, same ARIA-tree golden in the same dialect.
+  The vocabulary gains what a rendered surface needs and a page lacked —
+  `gone`, `focused`, and five role descriptors.
+- A consumer takes on optional peers it did not have (`@vitest/browser-playwright`,
+  `vitest-browser-react`, `vite`, `react`), and one hard constraint with them:
+  the provider peers vitest on an EXACT version, so the two move in one change.
+- CI pays for a second Chromium project. `sequence.groupOrder` keeps it from
+  sharing a slot with the website project on a two-vCPU runner.
+- React Native stays out: Browser Mode does not run it. `.astro` pages stay
+  website specs; only islands are components.
+- The package's own suite grows a component tree that is NOT under `_fixtures/`
+  — ground is what a spec stands on from a distance, and here the spec stands
+  next to it.

package/docs/decisions/004-a-module-against-real-services-or-a-golden-is-the-integration-facet.md

@@ -0,0 +1,81 @@
+# ADR-004: A module against real services, or against a golden, is the integration facet
+
+**Status:** Accepted
+**Date:** 2026-09-19
+
+## Context
+
+The fork the corpus drew had two rungs: a module alone, tested beside its code
+with no runner, and the assembled product behind an entry — HTTP, a binary, a
+served page, a screen — specified through `specification.*`. A whole kind of
+test fell between them, and every repository invented its own answer for it.
+
+A module that needs a real database is one. signews-api kept a
+global-setup file that built a sqlite template by hand and a project named
+"integrations" running plain vitest, because no constructor covered "this
+repository function, against the real schema". package-broadcast and
+package-analytics did the same with a root tests folder and `vi.mock`.
+
+A module whose oracle is a GOLDEN is the other. package-attestation's byte
+contracts and package-intelligence's fifty-three input/output pairs are
+golden-file tests, and both reached for `toMatchSnapshot` — a second golden
+mechanism, with no token grammar, no `{ frozen }`, and no `TEST_UPDATE=1`,
+living beside the one the package owns. Rule D20 could ban the matcher only
+once the tests it serves had somewhere to go.
+
+Neither case needed a new idea. Both needed a constructor.
+
+Three shapes were weighed and refused:
+
+- **Widen `jobs`.** `trigger(name)` takes no input and a job is
+  `() => Promise<void>`, so the Given would have to leave the test and live in
+  the specification file. A spec whose input is elsewhere is not a spec.
+- **Plain vitest under a folder named for it.** The shape every repository had
+  already reached, and the shape the evidence indicts: the services are
+  hand-started, nothing resets between tests, and the goldens are somebody's.
+- **`sqlite()` outside a runner.** A second lifecycle path for services — two
+  answers to "when does this start and who stops it", which is the defect the
+  orchestrator exists to prevent.
+
+## Decision
+
+`specification.integration({ services?, root? })` is the eighth kind of test
+and the sixth constructor. Its subject is a MODULE; its terminal action is
+`.call((services) => …)`, which hands the started record to the subject so it
+is built with real connection strings; its result is `CallResult`.
+
+`CallResult` has two readings and never both: `value` is what the call
+returned — a `TextAccessor` for a string, a `JsonAccessor` for anything else —
+and `error` is what it threw, as text, empty when it returned. Both are the
+package's ordinary accessors, so `toMatch`, the `{{token}}` grammar,
+`{ frozen }` and `TEST_UPDATE=1` reach them with no new mechanism.
+
+The setups are the ones every facet already has: `.seed()`, `.intercept()`,
+`.clock()`. Without `services` the constructor starts nothing: that is the
+golden-only half, and it is the whole of what a fifty-three-row table needs —
+one `.call()` inside `test.each`.
+
+## Consequences
+
+- **A refusal is a reading.** No `try`/`catch` in a spec, and no "it should
+  throw" test that passes because nothing threw. A chain says "and it did not
+  refuse" with `await expect(result.error).toBeEmpty()`.
+- **D20 gains its destination.** `toMatchSnapshot` can be banned because every
+  test it served now has a facet, a folder and a golden engine.
+- **One more folder name is spoken for, and no unowned one is added.**
+  `specs/integration/` is a facet folder: singular, like `website/`, and
+  holding a `*.specification.ts` at its root. The package renamed its own
+  plural folder in the same change. What lived there — probes of the container
+  adapters themselves — became integration specs under
+  `specs/integration/<seam>/`: an adapter met against a real service IS a
+  module against a real service. Folder = constructor holds for the package
+  too, so no probe earns a folder under `specs/` that no constructor owns, and
+  what a probe cannot reach through the public entry is a module test beside
+  its module (rule F3).
+- **An env-gated sub-suite stops being a project.** With `{ include, exclude }`
+  on the helper, package-attestation's five projects become `unit()` plus one
+  `integration()`.
+- **A door closed.** A module test may not carry a golden (D20) and an
+  integration spec may not assert only on doubles: the ladder's rungs are now
+  distinguishable by where the test lives, which is what makes both
+  mechanizable.

package/docs/decisions/005-the-doubles-ladder-is-closed.md

@@ -0,0 +1,86 @@
+# ADR-005: The doubles ladder is closed, and a ban an upstream rule can carry is an option, not a rule
+
+**Status:** Accepted
+**Date:** 2026-09-19
+
+## Context
+
+Two questions had no written answer, and the estate's tests answered them
+differently in every repository.
+
+**What may stand in for the real thing?** The measured failure mode is not
+subtle: a survey of the workbench found seven files replacing `fetch` with
+`vi.stubGlobal`, thirteen importing `vitest-mock-extended` directly, sixteen
+calling `vi.mock` on a module, two declaring `msw` themselves, five using
+`toMatchSnapshot`. Every one of them is a substitute chosen because nothing
+said which substitute to reach for first. Agents make this worse rather than
+better — the published measurements put a third of agent-written test commits
+at "adds a mock", and nearly all of those at "mocks everything".
+
+**Who owns a ban?** ADR-002 settled that a convention oxlint's own `vitest`
+plugin already enforces belongs to that plugin, and four hygiene rules left the
+`jterrazz/*` channel on that ground. It did not settle the case where the
+upstream rule exists but is inert without OPTIONS —
+`vitest/no-restricted-matchers` bans nothing until it is told which matchers,
+`vitest/no-restricted-vi-methods` until it is told which methods. Those options
+are a convention, and they had nowhere to live.
+
+Two shapes were weighed and refused. Writing a `jterrazz/*` rule for each ban
+duplicates an upstream rule that already does the work, which is exactly what
+ADR-002 forbids. Asking `compose()` to MERGE options across fragments is a
+toolchain change with no other caller, and it would make two owners of one
+rule's configuration.
+
+## Decision
+
+**The ladder is closed and ordered.** An agent takes the first rung that fits:
+
+1. **The real thing**, in-process — a pure module, a Hono app handed to
+   `server`, a component mounted in a real Chromium.
+2. **A declared service** — `sqlite()`, `postgres()`, `redis()`, `process()`:
+   real, isolated per worker, reset per chain.
+3. **A contract** — `.intercept()` on a chain, `intercept()` in module scope;
+   msw's server, msw's worker, or the `node:http` stub, all over one queue;
+   strict from the first contract.
+4. **A typed port double** — `mockOf<Port>()`, or `vi.fn<Fn>()` for a
+   function-shaped dependency.
+
+Nothing else is a rung. `vi.mock`, `vi.stubGlobal`, a raw `msw` import, `nock`,
+`sinon`, `jest` and `mockdate` are not lower rungs; they are off the ladder,
+and each has a named destination.
+
+**A ban an upstream vitest rule can carry as an OPTION is set from the
+`testing` fragment**, and the rulebook marks that rule `covered` so one owner
+states it. A ban a CORE rule would carry — `no-restricted-imports`,
+`no-restricted-globals` — stays a `jterrazz/*` rule, because an oxlint override
+REPLACES a rule's options rather than merging them, and three toolchain owners
+already set those two.
+
+This extends ADR-002: the option mechanism is this record's, the principle it
+serves is that one.
+
+## Consequences
+
+- **The ladder is citable.** "Use a contract, not a stubbed `fetch`" is a rung
+  number, not an opinion, and each ban's message names the rung above it.
+- **`mockOf` earns its place on rung four.** It pins
+  `vitest-mock-extended`'s range on the consumer's behalf, which is why the
+  consumer is forbidden to declare it. Its `{ deep: false }` form exists so
+  rung four does not push a test back down to a hand-written object.
+- **A mandatory type argument is not expressible.** `mockOf<T extends object>()`
+  has no default, but TypeScript falls back to the CONSTRAINT where no
+  inference site says otherwise, so `mockOf()` compiles and answers for
+  `object`. The refusal lands where the double is used — it is assignable to
+  no port — rather than where it was made. Stated rather than worked around: a
+  cast or a never-typed overload would buy the earlier error with a worse
+  signature.
+- **Three bans move upstream.** `no-restricted-matchers` (the snapshot
+  matchers), `no-restricted-vi-methods` (`stubGlobal`, the timer methods) and
+  `max-nested-describe` are configured, not reimplemented. They turn on in the
+  toolchain release that follows the package's next major.
+- **`vi.mock` keeps one door.** A native module a consumer cannot inject is
+  allow-listed per specifier, with a reason, and the allow-list is the
+  repository's — not a silent exception.
+- **A cost accepted.** Two channels now state bans: the fragment's options and
+  the `jterrazz/*` rules. The catalogue carries both, with `upstream` as a
+  channel value, so a reader still finds one list.