@jterrazz/test 16.1.1 → 17.0.0

package/docs/start/getting-started.md

@@ -0,0 +1,187 @@
+# Getting started
+
+`@jterrazz/test` is a testing framework built on vitest. You describe what to test (an HTTP API, a CLI, a page, a module against a real database), and it starts what that needs, runs one action, and hands back a result you compare with `expect()`. This page covers the five ideas behind it, a first spec from install to green, and the question that picks the kind of test you write.
+
+## Why it exists
+
+Three things make a test suite expensive to keep, and the framework takes each one off your hands.
+
+- **Infrastructure is code you maintain.** A suite that needs Postgres, a built binary or a browser usually grows its own `beforeAll` that starts them and an `afterAll` that sometimes forgets to stop them. Here you declare `postgres()`, `specification.cli(bin)` or a page visit, and the framework starts it, isolates it per worker and cleans it up.
+- **Assertions drift from what the user sees.** A test that checks `status === 201` and one field passes when the body is wrong. Here a result is compared whole (the full response, the full table, the full output), written in the test or in a file next to it, with `{{tokens}}` where values move.
+- **Every repository invents its own layout.** Here the conventions are a linter: where a test lives, what it may import and how it is named are checked by an oxlint plugin and a checker, and every finding says what it found, why the rule exists, how to fix this case, and where to read more.
+
+## The mental model
+
+Five ideas cover everything else in the manual. They match the four families of the docs map, plus the files a test stands on.
+
+**1. A kind of test, and its runner.** What you test decides the kind: a module, a module against a real service (integration), a rendered component, a website, a mobile screen, an HTTP API, a job, a CLI, or the lint rules a project ships. Each kind except module and component has a constructor (`specification.api()`, `specification.cli()`, ...), called once per suite in a `*.specification.ts` file. It starts what the suite needs and returns a runner (`api`, `cli`, ...) and a `cleanup` you pass to `afterAll`. The pages call the code behind one kind a **specification**.
+
+**2. A chain: setups, then one action.** Every test is one chain on that runner: zero or more setups (`.seed()`, `.intercept()`, `.clock()`, `.env()` ...), then exactly one action (`.get()`, `.exec()`, `.visit()`, `.trigger()`, `.call()` ...), which resolves to a result. The chain reads as the test's sentence: the setups are the Given, the action is the When.
+
+```typescript
+const result = await api.seed(file('./__seeds__/two-users.sql')).get('/users');
+```
+
+**3. What surrounds the subject.** A subject rarely runs alone. Real services (`postgres()`, `redis()`, `sqlite()`, `process()`) are started for you; the network is declared with stubs (`defineStub`, `.intercept()`); time is pinned with `clock`; a port your code injects is doubled with `mockOf()`. These have an order of preference, the doubles ladder: use the real thing first, a declared service next, then a stub, and a typed double last.
+
+**4. A visitor, for anything on a screen.** A page, a component or a native app is driven the way a person uses it: `visitor.click(button('Subscribe'))`, `visitor.see(content('Thanks'))`. Elements are found by role and accessible name, never by CSS selector.
+
+**5. Expectations on the whole result.** A result exposes what the action produced (`result.response`, `result.stdout`, `result.table('users')`, `result.tree`), and one matcher, `toMatch`, compares it whole: against a value written in the test, or `file('./__expected__/...')` when several tests share it. Values that change between runs are written as tokens (`{{uuid}}`, `{{iso8601}}`), and `TEST_UPDATE=1` writes the expected values for you to review.
+
+The whole-value comparison is the framework's `toMatch` on a framework result (`result.response`, `result.stdout`). On a plain string such as `result.stdout.text`, `toMatch` is vitest's own substring or RegExp check ([Assertions § Common mistakes](../reference/assertions.md#common-mistakes)).
+
+Everything a test stands on sits in a folder next to it whose name starts with `_`: `__seeds__/` (SQL), `__requests__/` (what is sent), `__fixtures__/` (files the program reads), `__expected__/` (what is compared), `__setup__/` (helper code). The `_` marks a folder that is not a subject of the tests.
+
+## A first spec
+
+This walkthrough tests an HTTP API backed by SQLite, so it needs no Docker. It assumes a Hono app in `src/app.ts`, built by a `createApp({ databaseUrl })` function, and a schema in `schema.sql`.
+
+### 1. Install
+
+```bash
+npm install -D @jterrazz/test @jterrazz/typescript vitest better-sqlite3
+```
+
+`vitest` and `@jterrazz/typescript` are always required. Everything else is installed only when a test needs it: here, `better-sqlite3` for `sqlite()`. If one is missing, the error says which package and the install command. The full list is [Set up a project § What to install](set-up-a-project.md#what-to-install).
+
+### 2. Configure vitest
+
+```typescript
+// jterrazz.config.ts
+import { test } from '@jterrazz/test/config';
+import { defineConfig } from '@jterrazz/typescript/config';
+
+export default defineConfig({
+    kind: 'api',
+    platform: 'node',
+    presets: [test()],
+});
+```
+
+`kind` and `platform` say what the project is (here, an HTTP service on Node), and `@jterrazz/typescript` derives the rest of the toolchain from them: the lint profile, the tsconfig preset, what the manifest must hold. An application kind (`api`, `website`, `mobile`) also asks for `"private": true` in `package.json`. The two lists, and which platforms each kind runs on, are the toolchain's [Getting started § Declare what the project is](https://github.com/jterrazz/package-typescript/blob/main/docs/start/getting-started.md#1-declare-what-the-project-is). `presets: [test()]` adds this package: the shared test defaults, the conventions, and the `test` section below.
+
+Then `npx typescript fix` writes the files that declaration derives, `vitest.config.ts` among them, a line you never edit. The preset sets the shared defaults (timeouts, artefact paths, no retries), and the projects are read off the tree, each built by the helper of its specification: `unit` collects the `*.test.ts` files next to your modules (the project a module test runs in), and `specs/api/` makes the `api` project, which collects `specs/api/**/*.spec.ts`. [Set up a project](set-up-a-project.md#the-vitest-config) lists every helper and default.
+
+This `api` project only names a vitest project. The `api` you send requests with is a different thing: the runner that step 3 builds.
+
+### 3. Build the runner, once per suite
+
+```typescript
+// specs/api/api.specification.ts
+import { specification } from '@jterrazz/test';
+import { sqlite } from '@jterrazz/test/services';
+import { afterAll } from 'vitest';
+
+import { createApp } from '../../src/app.js';
+
+export const { api, cleanup } = await specification.api({
+    services: { db: sqlite({ init: './schema.sql' }) },
+    server: ({ db }) => createApp({ databaseUrl: db.connectionString }),
+});
+
+afterAll(cleanup);
+```
+
+A spec imports from three entries: `@jterrazz/test` for what writes it (the constructors, `file()`, the targets, `match`), `@jterrazz/test/services` for what a specification starts (`sqlite()` here), and `@jterrazz/test/stubs` for what the network replies. A service or a stub imported from the root is a lint error, and `npx typescript fix` moves the import to its subpath (rule `service-or-stub-from-its-subpath`).
+
+`server` returns your app, and the specification sends it each request through its `request(path, init)` method, which answers a Fetch `Response`; a Hono `app` is one as it stands. The app runs in the test process, wired to a real SQLite database built from `schema.sql`. Each worker gets its own copy, and every chain starts from empty tables.
+
+An app on another framework needs two things. It needs a `request(path, init)` of its own: Express and Fastify have none, so `server` returns a wrapper you write that answers it with a `Response`. And it exposes no route table, so the run cannot measure route coverage until the project names its routes as an OpenAPI document, `test: { routes: './openapi.yaml' }` in `jterrazz.config.ts`; without one the api run fails ([API specs § An app that is not Hono](../guides/api-specs.md#an-app-that-is-not-hono)).
+
+### 4. Write the test
+
+```typescript
+// specs/api/users/list/shape.spec.ts
+import { file } from '@jterrazz/test';
+import { describe, expect, test } from 'vitest';
+
+import { api } from '../../api.specification.js';
+
+describe('shape', () => {
+    test('lists the users the database holds', async () => {
+        // Given - two users, from the seed beside the test
+        const result = await api.seed(file('./__seeds__/two-users.sql')).get('/users');
+
+        // Then - the whole response
+        expect(result.response).toMatch(`
+            HTTP/1.1 200 OK
+            content-type: application/json
+
+            {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+        `);
+    });
+});
+```
+
+```sql
+-- specs/api/users/list/__seeds__/two-users.sql
+INSERT INTO users (name) VALUES ('Alice'), ('Bob');
+```
+
+The folder says what is tested (`users/list/` is `GET /users`), the file name says which question is asked of it (`shape`), and the one `describe` repeats it. Every test carries a `// Given -` and a `// Then -` line.
+
+### 5. Run it
+
+```bash
+npx vitest --run --project api
+```
+
+`--project api` runs one project; `npx vitest --run` runs every project the config declares, and is the line to put in `package.json` as `"test": "vitest --run"`.
+
+The api project also checks route coverage: after the last test it names every route the app declares that no request reached, and a route left unreached fails the run, even on the first one. There is no switch to turn it off. To accept that debt for now, run once with `TEST_UPDATE=1`: it records the count in `.jterrazz/baseline.json`, which you commit, and the count can only go down from there ([API specs § Route coverage](../guides/api-specs.md#route-coverage)).
+
+To write the expected value instead of typing it, leave it empty (`toMatch('')`) and run once with `TEST_UPDATE=1`. The framework writes what came back into the test, with tokens where values move; you read the diff before you commit it ([Tokens § Update mode](../reference/tokens.md#update-mode-tokens-are-preserved)).
+
+### 6. Check the conventions
+
+The conventions are already on: the `test()` step 2 lists carries them, and the `oxlint.config.ts` that `npx typescript fix` wrote reads it. One command enforces them, with the rest of the toolchain:
+
+```bash
+npx typescript check
+```
+
+What it checks, and how to deviate from a rule, is [Set up a project § Turning the conventions on](set-up-a-project.md#turning-the-conventions-on).
+
+### What you commit
+
+| Path                                                                       | Commit it? | Why                                                                                                                                                      |
+| -------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jterrazz.config.ts`                                                       | yes        | the one file you write: what the project is, its presets, its test projects                                                                              |
+| `vitest.config.ts`, `oxlint.config.ts`, `oxfmt.config.ts`, `tsconfig.json` | yes        | derived by `typescript fix` and held by `typescript check`; an editor reads them by name                                                                 |
+| `.jterrazz/`                                                               | yes        | the debt the ratchets hold, such as the `baseline.json` step 5 records; commit it with the change that recorded it, since the next run judges against it |
+| `.artifacts/`                                                              | no         | caches, reports and evidence every run rewrites: add `.artifacts/` to `.gitignore`                                                                       |
+
+## Which kind of test
+
+Ask the questions in order: the first yes is the kind, and the kind decides where the file lives, which constructor it uses and which vitest project runs it.
+
+<!-- GENERATED:fork. Do not edit by hand; run `npm run docs`. Source: lint/consumer/catalogue/fork.ts -->
+
+| Question                                                               | Kind             | Lives at                                         | Constructor                   | Project       | Read                                                                                         |
+| ---------------------------------------------------------------------- | ---------------- | ------------------------------------------------ | ----------------------------- | ------------- | -------------------------------------------------------------------------------------------- |
+| Does it render in a browser as a whole served page?                    | website          | `specs/website/<domain>/<aspect>.spec.ts`        | `specification.website()`     | `website`     | [Website specs](../guides/website-specs.md)                                                  |
+| Does it render as a component (React, a DOM function, a hook)?         | component        | `__tests__/<file>.test.tsx` by `<file>.tsx`      | none, the `component` chain   | `component`   | [Component specs](../guides/component-specs.md)                                              |
+| Does it render on a simulator?                                         | mobile           | `specs/mobile/<domain>/<aspect>.spec.ts`         | `specification.mobile()`      | `mobile`      | [Mobile specs](../guides/mobile-specs.md)                                                    |
+| Does it answer HTTP?                                                   | api              | `specs/api/<resource>/<action>/<aspect>.spec.ts` | `specification.api()`         | `api`         | [API specs](../guides/api-specs.md)                                                          |
+| Is it triggered by name, in-process?                                   | job              | `specs/job/<job>/<aspect>.spec.ts`               | `specification.job()`         | `job`         | [Job specs](../guides/job-specs.md)                                                          |
+| Is it a binary?                                                        | cli              | `specs/cli/<command>/` (+ `<case>.spec.yaml`)    | `specification.cli(bin)`      | `cli`         | [CLI specs](../guides/cli-specs.md), [Spec documents](../guides/spec-documents.md)           |
+| Is it a rule the project ships: a plugin, a checker, a preset?         | lint             | `specs/lint/<rule>/<aspect>.spec.ts`             | `specification.lint()`        | `lint`        | [Lint specs](../guides/lint-specs.md)                                                        |
+| Is it a module that needs a real service, or whose oracle is a golden? | integration      | `specs/integration/<domain>/<aspect>.spec.ts`    | `specification.integration()` | `integration` | [Integration specs](../guides/integration-specs.md)                                          |
+| Is it a module alone?                                                  | module           | `__tests__/<file>.test.ts` by `<file>.ts`        | none                          | `unit`        | [Module tests](../guides/module-tests.md)                                                    |
+| Is it the repository itself, a suite over several apps?                | repository suite | `specs/<suite>/<domain>/<aspect>.test.ts`        | none                          | any name      | [Conventions § The third door](../concepts/conventions.md#the-third-door-a-repository-suite) |
+
+<!-- /GENERATED:fork -->
+
+The order matters: a page served over HTTP is a website, not an API, because the first question already caught it. And the table is total: a folder under `specs/` is a kind's name, a special folder of what the kinds share, or a repository suite; a probe of an adapter against a real database is an integration spec like any other.
+
+The file suffix tells the kind apart: `.test.ts` or `.test.tsx` next to the code for a single unit, `.spec.ts` under `specs/<kind>/` for an assembled product, `<case>.spec.yaml` for a CLI session written as data, and `<kind>.specification.ts` for the file that builds a runner. The kind follows the subject, not the amount of machinery: a component needs a real browser and still sits next to its code, because it is one unit; a module that needs a real database sits under `specs/integration/`, because it is assembled with that database.
+
+Before choosing a kind, ask whether the test should exist at all. A behaviour a user relies on is tested end to end, through the surface the user meets; a module test is kept only for a pure algorithm or a failure no end-to-end path can provoke ([Conventions § Which test earns its place](../concepts/conventions.md#which-test-earns-its-place)).
+
+## Where to go next
+
+- The chapter of your kind, from the table above. Each one has the same sections: what it specifies, the constructor, the chain, the result, what is unique to it, pitfalls.
+- What surrounds a subject: [Stubs](../reference/stubs.md), [Services](../reference/services.md), [Time and doubles](../reference/time-and-doubles.md).
+- Acting on a screen: [The visitor](../reference/visitor.md).
+- Judging a result: [Assertions](../reference/assertions.md), [Tokens](../reference/tokens.md).
+- Why the conventions are what they are: [Conventions](../concepts/conventions.md); every rule, generated from the code: [Linting](../reference/linting.md).

package/docs/start/set-up-a-project.md

@@ -0,0 +1,214 @@
+# Set up a project
+
+What a project installs, how its `vitest.config.ts` is written, how it turns the conventions on, and where a run writes. [Getting started](getting-started.md) walks through the minimum; this page is the reference behind it.
+
+## What to install
+
+```bash
+npm install -D @jterrazz/test @jterrazz/typescript vitest
+```
+
+**`vitest ^5` and `@jterrazz/typescript ^11` are the only required peers.** The framework registers its matchers into vitest and has no runner of its own. The toolchain, [`@jterrazz/typescript`](https://github.com/jterrazz/package-typescript), is required because the framework prints its refusals through the toolchain's rules kit and its published types extend the toolchain's `JterrazzConfig` (`@jterrazz/typescript/config`). Its lint conventions are a separate, opt-in step ([below](#turning-the-conventions-on)).
+
+### Project requirements
+
+- **ESM.** The package ships ES modules only, and every specification file awaits its constructor at the top level (`export const { api, cleanup } = await specification.api(...)`). Set `"type": "module"` in `package.json`, or name the config files `.mts` (`vitest.config.mts`).
+- **Node 24 or newer**, as `engines` states.
+- **A tsconfig that knows `using` and top-level await.** Tests pin time with `using _ = clock.at(...)` and dispose with `await using` ([Time and doubles](../reference/time-and-doubles.md)), which need `target` and `lib` at `ES2022` or later for top-level await and `ESNext` for `using`, with `module` at `ESNext` or `NodeNext`. The toolchain's tsconfig presets set all of it: `"extends": "@jterrazz/typescript/tsconfig/node"`.
+
+**Everything else is an optional peer**, loaded the first time a test needs it. A project that tests no page, no component and no database installs none of them.
+
+| Needed by                   | Install                                                                                                                                         |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| A website visit             | `playwright`, then `npx playwright install chromium` once                                                                                       |
+| A component                 | `@vitest/browser-playwright` (the exact version of `vitest`), `vitest-browser-react`, `vite`, `react`, `react-dom`, `playwright` and a chromium |
+| A mobile screen             | `appium`, `webdriverio`, then `npx appium driver install xcuitest`                                                                              |
+| `postgres()`, `redis()`     | `testcontainers`, plus `pg` or `redis` for the driver a table read uses, and a running Docker                                                   |
+| `sqlite()`                  | `better-sqlite3` (no Docker)                                                                                                                    |
+| A lint spec, `ruleTester()` | `oxlint`                                                                                                                                        |
+| Coverage                    | `@vitest/coverage-v8`                                                                                                                           |
+
+`msw`, which delivers stubbed network replies, is a direct dependency: nothing to install. An API spec hands your app to `server`, which must answer `request(path, init)` with a Fetch `Response` and, for route coverage, expose Hono's route table. A Hono app does both. Any other framework needs a wrapper of your own for the first, and an OpenAPI document named in `test: { routes }` for the second ([API specs § An app that is not Hono](../guides/api-specs.md#an-app-that-is-not-hono)).
+
+**A missing peer is named when it is needed.** A specification's refusal names the packages it lacks and the `npm install -D` that brings them. A service's refusal names the service that asked, the peer, and the install command of the package manager your lockfile names; under pnpm a native binding must also be listed to be built, and the message adds that line:
+
+```text
+found: sqlite() requires `better-sqlite3`, and it is not installed
+why: Every seam is an optional peer of @jterrazz/test, installed by the project that specifies through it.
+fix: pnpm add -D better-sqlite3; under pnpm the binding is not built unless the package is listed: add "better-sqlite3" to `onlyBuiltDependencies` in package.json (or `only-built-dependencies` in .npmrc) and reinstall
+read: docs/reference/linting.md#seam-is-an-optional-peer
+```
+
+**A native peer can be installed and still not built.** npm since 11, pnpm since 10 and bun since 1.2 withhold a dependency's install script by default, so a native package arrives without its compiled `.node`. `better-sqlite3` 13 ships its binding prebuilt and loads anyway; with 12, `sqlite()` notices on first load and says how to build it:
+
+```text
+found: sqlite() found `better-sqlite3`, and its native binding is not built
+why: A native peer is built by its install script, and npm runs a dependency's install script only once it is told to.
+fix: npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3
+read: docs/start/set-up-a-project.md#what-to-install
+```
+
+Three more constraints come from the peers themselves:
+
+- **One Playwright for the whole family.** This package's `playwright` peer is the exact version it is gated on, and a project declares that version: two revisions on one machine each need their own Chromium build, and `typescript doctor` names the build a project's Playwright wants and the machine lacks. `npx playwright install chromium`, run in the project, provisions it.
+- **The browser provider moves with vitest.** `@vitest/browser-playwright@X` requires `vitest` at exactly `X`, so the two are upgraded together: `npm install -D vitest@5.0.1 @vitest/browser-playwright@5.0.1`. `component()` checks the two versions match and names both when they do not.
+- **Vite `^6.4 || ^7 || ^8`** for a component. `component()` reads the installed major and states the JSX transform on the key that version reads.
+- **The ARIA dialect of a `.aria.yaml` golden is Playwright's.** A Playwright major can reword a role line, and every committed tree golden then moves with it in one `TEST_UPDATE=1` run.
+
+Why vitest 5 alone, and why the native seams became optional peers: [ADR-008](https://github.com/jterrazz/package-test/blob/main/docs/decisions/008-vitest-5-node-24-and-the-native-seams-as-optional-peers.md).
+
+To try an unreleased build of the framework, install the tarball `npm pack` writes, never a `file:` link: a link makes the project resolve vitest's types twice, and the matchers then type on one copy and not the other. The recipe (the tarball packed into `.artifacts/packages/`, the lockfile entries to drop, bun's cache, the order a wave of projects takes the two packages in) is the toolchain's [Install an unreleased build](https://github.com/jterrazz/package-typescript/blob/main/docs/guides/install-an-unreleased-build.md), since this package is installed with it.
+
+## The vitest config
+
+The projects a repository runs are read off its tree: one per folder `specs/<specification>/` it keeps (`specs/api/`, `specs/cli/`, `specs/website/` and the rest), `unit` over each root holding a module test (`src/`, `lint/`, a folder of `specs/` no specification names, a `unit` one included), and `component` over the component specs and each root holding a rendered test (`*.test.tsx`). A ground, setup or dot folder is never read. `jterrazz.config.ts` states only how a project departs from the one its tree derives (a helper's options, its own global setups), keyed by its specification, with the reason. The package's standard, `src/standard/standard.ts`, states the one departure every repository shares: the `unit` project runs a worker's files in one module graph (`isolate: false`), since a module test leaves no state behind in a module; a repository whose module tests do states `isolate: true` with its reason. The standard only shapes a project the tree derives or the file declares; it makes none exist. `typescript doctor` prints the projects derived from the tree beside what each file states. The file also declares the project's `kind` and `platform`, which `@jterrazz/typescript` reads to derive the rest of the toolchain ([its Configuration § Kind and platform](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/configuration.md#kind-and-platform)):
+
+```typescript
+// jterrazz.config.ts
+import { test } from '@jterrazz/test/config';
+import { defineConfig } from '@jterrazz/typescript/config';
+
+export default defineConfig({
+    kind: 'website',
+    platform: 'react',
+    presets: [test()],
+    test: {
+        projects: {
+            component: {
+                reason: 'the app renders through its own Vite pipeline, inside its providers',
+                vite: './vite.config.ts',
+                wrap: './src/providers.tsx',
+            },
+        },
+    },
+});
+```
+
+A project keyed by a specification the package does not ship, a declared one with no `reason`, and `projects` written as a list are refused in four parts, reading this section.
+
+`vitest.config.ts` is the file those projects derive, which `typescript fix` writes and `typescript check` holds ([`@jterrazz/typescript`'s Config pass](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/quality-checks.md#the-config-one-file-pass)):
+
+```typescript
+import { vitestConfig } from '@jterrazz/test/vitest';
+
+export default await vitestConfig(import.meta.url);
+```
+
+It reads the `jterrazz.config.ts` beside the module whose `import.meta.url` it is handed (the config file's own folder, wherever vitest, the Vitest extension or knip loads it) and builds each project the tree names, or the file declares, with its helper over the preset below. A project states no `name`, `environment` or `browser`: its helper names it for its specification and sets what the specification needs. A relative `setup` (global setups the project runs, read from the project root), `root` and `vite.resolve.alias` target are read from the project root; `wrap` stays the component's root's. A tree with no test and a file declaring no project leave the config the preset alone. It is the one-liner `@jterrazz/typescript` derives for every editor file (the entry handed the module's own `import.meta.url`, awaited at the top), which vitest and knip's loader both read whole.
+
+### The project helpers
+
+There is one helper per kind (`unit`, `integration`, `component`, `website`, `mobile`, `api`, `job`, `cli` and `lint`), named by the key of a project, and exported from `@jterrazz/test/vitest` beside `vitestConfig`, for a config written by a tool of your own. Each collects its folder (`specs/<kind>/**/*.spec.ts`, plus the `<case>.spec.yaml` documents for `cli()`) and carries what its kind needs: a browser for `component()`, a simulator session for `mobile()`, and for `api()`, `job()` and `integration()` a global setup that starts each service container once and shares it across every file and project of the run ([Services § One container per run](../reference/services.md#one-container-per-run)). Docker is needed only by a spec that declares `postgres()` or `redis()`: with no Docker running, each such file fails with one sentence naming Docker, and every other file runs. Every helper accepts:
+
+| Option                | Does                                                                                                                                                           |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `include` / `exclude` | Replace the default globs. A default `exclude` guards the default `include`, so state both or neither                                                          |
+| `timeout`             | Raise or lower the 30 s default for this project alone: each test's and each hook's, so the `afterAll` that stops what a slow test started has the same budget |
+| `serial`              | Run the project's files one at a time (`fileParallelism: false`), when they share one server, one file, one app                                                |
+
+`unit()` and `component()` are a pair: `unit()` collects `**/*.test.ts` outside `specs/` and leaves out `**/*.test.tsx`, which `component()` collects. So the suffix beside a file decides which project runs it. `unit()` also takes `roots` when the modules are not at the repository root, and `isolate: false` to run a worker's files in one module graph, only for a project whose tests leave no state behind in a module, and the default `vitestConfig` hands it. `component()` takes the options of the app it renders (`vite`, `wrap`, `viewport`, `clock`, `timezone`, `locale`, `root`), described in [Component specs](../guides/component-specs.md#the-constructor-there-is-none); `mobile()` takes the simulator the run shares ([Mobile specs](../guides/mobile-specs.md#one-session-per-run)).
+
+Projects run in groups (the node kinds first, then `website`, then `component`, then `mobile`), so two browser projects never open two Chromiums at once and a simulator runs alone.
+
+`api()`, `job()` and `integration()` also take `runner`, the module their spec files import their runner from, such as `'./specs/api/api.specification.ts'`. The tree derives it where the folder holds one specification module, named for it (`specs/api/api.specification.ts` alone in `specs/api/`), so a project states it only for a module named otherwise. With it, the files of a worker share one module graph (`isolate: false`) and the specification runs again before each file (`setupFiles`): the app's modules load once per worker instead of once per file, and every file still boots its own app on its own services. A spec file imports its runner from the specification itself, since a module of the shared graph that imports it keeps the first file's runner.
+
+An env-gated sub-suite is an `exclude`, not a second project:
+
+```typescript
+const integration = {
+    exclude: process.env.E2E_NETWORK ? [] : ['specs/integration/network/**'],
+    reason: 'the network specs reach the internet, which a run turns on with E2E_NETWORK',
+};
+```
+
+### What the preset sets
+
+| Setting                                                                                | Value                                                                                            | Why                                                                                                                            |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `test.testTimeout`, `hookTimeout`                                                      | `30_000`                                                                                         | vitest's 5 s never survived a container boot or a build                                                                        |
+| `test.retry`                                                                           | `0`                                                                                              | A flaky test is fixed or deleted; a retry hides it                                                                             |
+| `test.restoreMocks`, `unstubGlobals`, `unstubEnvs`                                     | `true`                                                                                           | A spy, a stubbed global or a stubbed env a test forgets to restore would fail a later file that did nothing wrong              |
+| `test.exclude`                                                                         | vitest's defaults + `.artifacts/**` + `**/{__expected__,__fixtures__,__requests__,__seeds__}/**` | What a test stands on is input, never a suite to run; `.artifacts/` holds copies of the project, a mutation sandbox among them |
+| `cacheDir`, `test.coverage.reportsDirectory`, `test.attachmentsDir`, `test.outputFile` | under `.artifacts/vitest/`                                                                       | Everything a tool writes lives at `.artifacts/<tool>/` ([below](#where-a-run-writes))                                          |
+| `test.globalSetup`                                                                     | update mode, the run's temp root                                                                 | Update mode writes after the run is reported; the temp root is [below](#where-a-run-writes)                                    |
+| `plugins`                                                                              | `literate()`, when `literate:` is given                                                          | Turns each `<case>.spec.yaml` into a test file ([Spec documents](../guides/spec-documents.md))                                 |
+
+Coverage attaches to every process a run spawns (`autoAttachSubprocess`), and reads `dist/` only to map each bundle back to the source it was built from (`excludeAfterRemap`): a spec that runs the built command counts toward the sources it exercised.
+
+It sets nothing else on purpose. `fileParallelism`, `reporters`, `environment`, `env` and every `include` are true of one project and not of another, so a project states them; a helper does it for you. The coverage provider is yours to install.
+
+The defaults reach every inline project too, since vitest resolves each project as its own config. A project given as a glob string, a promise or a function is handed back untouched.
+
+The `<case>.spec.yaml` documents are collected by the `cli` project, which takes `literate` beside its own options:
+
+```typescript
+const cli = {
+    literate: { runner: './specs/cli/run.specification.ts' },
+    reason: 'the documents run against the runner the run/ specs share',
+};
+```
+
+To adopt the preset from a config written by hand, file each kind of test under its folder, move what a project passed its helper beyond that into `test.projects`, keyed by its specification and with its reason, delete what the table above already says (the 30 s timeouts, `...configDefaults.exclude`, the ground exclusions), and run `typescript fix`, which writes the derived `vitest.config.ts`. A timeout lower or higher than 30 s stays stated, as the project's `timeout`: the preset is a starting point, not a ceiling. Then add `.artifacts/` to `.gitignore`.
+
+## Turning the conventions on
+
+The conventions travel in the same `test()` preset that sets the vitest defaults, so the `jterrazz.config.ts` [above](#the-vitest-config) already turns them on. The base preset needs no line of its own: the declared `platform` picks the lint profile it runs ([the toolchain's Lint presets § The profiles](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/lint-presets.md#the-profiles)), and `test()` adds this package's rules on top.
+
+The linter reads them through the `oxlint.config.ts` that `npx typescript fix` derives, one line like the vitest config:
+
+```typescript
+// oxlint.config.ts
+import { oxlintConfig } from '@jterrazz/typescript/oxlint';
+
+export default await oxlintConfig(import.meta.url);
+```
+
+`npx typescript check` then runs all of it: the oxlint plugin, the import and naming rules, and the conventions checker over `specs/`. Nothing is detected from your dependencies: a project that does not list `test()` runs none of these rules, and writes its tests all the same. A rule you set apart is written in `jterrazz.config.ts` with its reason, never in the derived file; how, how to suppress one finding, and the full catalogue are [Linting](../reference/linting.md).
+
+## Where a run writes
+
+**In the project, only under `.artifacts/`**, one folder per tool, one line in `.gitignore`, one `rm -rf .artifacts` for a clean slate:
+
+| Path                                             | Written by                                                 | Lifetime                        |
+| ------------------------------------------------ | ---------------------------------------------------------- | ------------------------------- |
+| `.artifacts/vitest/`                             | vite's transform cache, vitest's reports                   | Reused across runs              |
+| `.artifacts/vitest/coverage/`                    | the coverage provider                                      | Rewritten per coverage run      |
+| `.artifacts/vitest/sqlite/template-<key>.sqlite` | `sqlite()`'s schema template                               | Reused until the schema changes |
+| `.artifacts/vitest/evidence/<pid>-.../`          | the screenshot of a website or mobile scenario that failed | Kept until the next run starts  |
+
+**Everything else is scratch, in one temp folder per run.** Before the first worker starts, the preset creates `jterrazz-test-runs-<uid>/<pid>-...` in the OS temp directory and points `TMPDIR`, `TMP` and `TEMP` at it, so every temp folder a worker, a spawned child or a tool it runs makes lands inside. That holds each CLI spec's working directory, the per-worker database copies and a browser's profile. The run removes the folder when it ends, and the next run removes the folder of any run that died first. A CLI spec's working directory goes sooner, once its test has finished, except under `test.concurrent`, where it waits for the run.
+
+**Two environment variables are yours to set**: `TEST_UPDATE=1`, which turns on update mode ([Tokens § Update mode](../reference/tokens.md#update-mode-tokens-are-preserved)), and `TEST_MOBILE_HEADED=1`, which shows a mobile run's simulator in a window instead of running it headless ([Mobile specs](../guides/mobile-specs.md#the-simulator-and-what-the-run-leaves-on-it)). The framework also reads `VITEST_POOL_ID`, which vitest sets, to isolate each worker's databases.
+
+## Two rough edges of the toolchain's flow
+
+- **An `include` that names `.test.ts`** stops collecting the moment `typescript fix` renames a spec. The fix lists every glob or literal it broke, so update them in the same commit; `include-points-at-a-folder` holds the class afterwards.
+- **`typescript baseline` in an npm-hoisted workspace member** cannot resolve oxlint today; run it from a directory where `node_modules/.bin/oxlint` resolves.
+
+## Pitfalls
+
+- **Forgetting `afterAll(cleanup)` in a specification file.** The services leak into the next suite (rule `cleanup-passed-to-after-all`).
+- **Importing from a subpath the package does not publish** (`@jterrazz/test/matchers`). A test imports from `@jterrazz/test`, `@jterrazz/test/services` and `@jterrazz/test/stubs`; the tool entries are `/vitest`, `/config`, `/oxlint` and `/schema` (rule `no-unpublished-subpath`).
+- **Importing a service or a stub from the root.** `postgres()` comes from `@jterrazz/test/services` and `http` from `@jterrazz/test/stubs`, so a spec that starts no container and serves no stub loads neither; `npx typescript fix` moves such an import to its subpath (rule `service-or-stub-from-its-subpath`).
+- **Writing `browser:` in a config by hand.** `component()` pins the provider to the runner's version, serves the service worker and pre-bundles cold dependencies; a derived config has no place for a hand-written one: a project's `specification` is its helper.
+
+## Upgrading
+
+Each release's notes are its [GitHub release](https://github.com/jterrazz/package-test/releases); the package keeps no changelog. A major carries no bridge from the one before (no codemod, no rename map, no rule that recognises the old spellings; see [ADR-014](https://github.com/jterrazz/package-test/blob/main/docs/decisions/014-a-major-carries-no-bridge-from-the-one-before.md)), so a project moves by hand, and the rules of the new major name each leftover in their own terms.
+
+### From 16 to 17
+
+| What a 16 project wrote                                                                                                  | What 17 asks for                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@jterrazz/typescript` ^10                                                                                               | ^11, released first; its own migration is [its Release § Which number moves](https://github.com/jterrazz/package-typescript/blob/main/docs/guides/release.md#which-number-moves)                                                                         |
+| a hand-written `vitest.config.ts`                                                                                        | `test.projects` in `jterrazz.config.ts`, and the derived one-liner `typescript fix` writes ([§ The vitest config](#the-vitest-config))                                                                                                                   |
+| the `jterrazz-test-check` bin, chained after `typescript check`                                                          | `presets: [test()]`; `typescript check`, `fix` and `baseline` run the checker                                                                                                                                                                            |
+| a bare name: `.seed('two-users.sql')`, `.request('create-user.http')`, the `$`-prefixed alias of the shared fixture pool | a path from the spec file, `file('./__seeds__/two-users.sql')` or `directory(...)`; the shared ground is the special folder of its role at the specs root, `specs/__seeds__/`, `specs/__fixtures__/` and the rest, reached by the path that climbs to it |
+| `defineContract()`, `defineContracts()` and the `Contract*` types                                                        | `defineStub()`, `defineStubs()` and the `Stub*` types ([Stubs](../reference/stubs.md))                                                                                                                                                                   |
+| `specification.jobs()`, its `jobs` runner and the `jobs` folder under `specs/`                                           | `specification.job()`, the `job` runner and `specs/job/` ([Job specs](../guides/job-specs.md))                                                                                                                                                           |
+| field probes with no whole comparison, the matcher of a table's rows, an api or job `<case>.spec.yaml`                   | one `toMatch` of the whole result, written in the test or in a `file()` ([Assertions](../reference/assertions.md)); documents stay for cli and lint specs                                                                                                |
+| a rule id, in a config, a suppression or a ratchet key                                                                   | its new name, stated as its requirement ([Linting § The rule catalogue](../reference/linting.md#the-rule-catalogue)); a directive naming an old id is reported as dead                                                                                   |
+
+## Related
+
+[Getting started](getting-started.md) · [Component specs](../guides/component-specs.md) · [Linting](../reference/linting.md) · [Release](https://github.com/jterrazz/package-test/blob/main/docs/guides/release.md)

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@jterrazz/test",
-    "version": "16.1.1",
-    "description": "Declarative testing framework for HTTP APIs, CLIs, background jobs, websites, mobile apps and rendered components — one entry point, real infrastructure and a real browser, golden-file assertions, plus an oxlint convention plugin.",
+    "version": "17.0.0",
+    "description": "Declarative testing framework for HTTP APIs, CLIs, background jobs, websites, mobile apps, rendered components and the rules a project ships: one entry point, real infrastructure and a real browser, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",
         "browser-mode",
@@ -25,27 +25,42 @@
         "type": "git",
         "url": "https://github.com/jterrazz/package-test"
     },
-    "bin": {
-        "jterrazz-test-check": "dist/checker.js"
-    },
     "files": [
         "dist",
-        "!dist/catalog.*",
-        "!dist/coverage.*",
+        "!dist/**/*.map",
         "docs",
+        "!docs/guides/test.md",
+        "!docs/decisions",
         "schema"
     ],
     "type": "module",
+    "imports": {
+        "#checker": "./dist/checker.js"
+    },
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
             "browser": "./dist/browser/index.js",
             "import": "./dist/index.js"
         },
+        "./services": {
+            "types": "./dist/services.d.ts",
+            "browser": "./dist/browser/services.js",
+            "import": "./dist/services.js"
+        },
+        "./stubs": {
+            "types": "./dist/stubs.d.ts",
+            "browser": "./dist/browser/stubs.js",
+            "import": "./dist/stubs.js"
+        },
         "./vitest": {
             "types": "./dist/vitest.d.ts",
             "import": "./dist/vitest.js"
         },
+        "./config": {
+            "types": "./dist/config.d.ts",
+            "import": "./dist/config.js"
+        },
         "./oxlint": {
             "import": {
                 "types": "./dist/oxlint.d.ts",
@@ -62,51 +77,53 @@
         "registry": "https://registry.npmjs.org/"
     },
     "scripts": {
-        "build": "tsdown --config tsdown.config.ts",
-        "docs": "npm run build && node dist/catalog.js && typescript docs",
-        "lint": "typescript check && node dist/checker.js specs",
-        "lint:fix": "typescript fix && node dist/checker.js specs --fix",
+        "build": "typescript build",
+        "docs": "npm run build && node .artifacts/dev/self.js chapters && node .artifacts/dev/schema.js",
+        "lint": "typescript check",
         "test": "vitest --run",
-        "coverage": "npm run build && vitest --run --coverage && node dist/coverage.js --write",
-        "coverage:check": "node dist/coverage.js"
+        "test:repeat": "vitest --run --repeats 10"
     },
     "dependencies": {
+        "@oxlint/plugins": "^1.85.0",
         "msw": "^2.15.0",
+        "oxc-parser": "^0.150.0",
         "vitest-mock-extended": "^5.0.0",
         "yaml": "^2.9.0"
     },
     "devDependencies": {
-        "@hono/node-server": "^2.0.8",
-        "@jterrazz/typescript": "^10.3.1",
-        "@types/better-sqlite3": "^7.6.13",
-        "@types/node": "^26.1.1",
-        "@types/pg": "^8.20.0",
+        "@hono/node-server": "^2.1.1",
+        "@jterrazz/typescript": "^11.0.0",
+        "@types/better-sqlite3": "^9.6.0",
+        "@types/node": "^26.6.2",
+        "@types/pg": "^8.23.1",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",
         "@vitest/browser-playwright": "5.0.1",
         "@vitest/coverage-v8": "^5.0.1",
-        "better-sqlite3": "^12.11.1",
-        "hono": "^4.12.30",
-        "oxlint": "^1.83.0",
-        "pg": "^8.22.0",
-        "playwright": "^1.49.0",
+        "ajv": "^8.20.0",
+        "better-sqlite3": "^13.0.3",
+        "hono": "^4.13.9",
+        "oxlint": "1.85.0",
+        "pg": "^8.23.0",
+        "playwright": "1.63.0",
         "react": "^19.3.0",
         "react-dom": "^19.3.0",
         "react-router": "^8.4.0",
-        "redis": "^6.1.0",
-        "testcontainers": "^12.0.4",
-        "tsdown": "^0.22.7",
-        "vite": "^8.1.4",
+        "redis": "^6.2.1",
+        "testcontainers": "^12.1.0",
+        "vite": "^8.3.0",
         "vitest": "5.0.1",
         "vitest-browser-react": "^2.3.0",
-        "webdriverio": "^9.30.0"
+        "webdriverio": "^9.32.0"
     },
     "peerDependencies": {
+        "@jterrazz/typescript": "^11.0.0",
         "@vitest/browser-playwright": "*",
         "appium": "^3.0.0",
-        "better-sqlite3": "^12.11.1",
+        "better-sqlite3": "^12.11.1 || ^13",
+        "oxlint": "^1.85.0",
         "pg": "^8.22.0",
-        "playwright": "^1.49.0",
+        "playwright": "1.63.0",
         "react": "^18 || ^19",
         "react-dom": "^18 || ^19",
         "redis": "^6.1.0",
@@ -126,6 +143,9 @@
         "better-sqlite3": {
             "optional": true
         },
+        "oxlint": {
+            "optional": true
+        },
         "pg": {
             "optional": true
         },