@jterrazz/test 16.1.1 → 18.0.0

package/docs/reference/visitor.md

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

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).