@jterrazz/test 16.1.1 → 18.0.0

package/README.md

@@ -1,197 +1,71 @@
 # @jterrazz/test
 
-Declarative testing framework for modules, APIs, jobs, CLIs, rendered components, websites and native apps. Six constructors — `specification.api()`, `specification.jobs()`, `specification.cli()`, `specification.integration()`, `specification.website()`, `specification.mobile()` — plus the `component` chain, which starts nothing and needs none, and the module test, which needs neither.
-
-A spec reads as a sentence: given → action → assertions. The vitest test name is its only description, every assertion goes through `expect()` with subject-typed matchers, and the infrastructure a spec declares — Postgres, Redis, SQLite, a child process, a real Chromium, an iOS simulator — is started, isolated per worker and cleaned up for you.
-
-```bash
-npm install -D @jterrazz/test vitest
-```
-
-Everything a spec needs imports from `@jterrazz/test`; the entries beside it are tools no spec imports, and they are listed once — [docs/01 § What the tree publishes](docs/01-architecture.md#what-the-tree-publishes).
-
-## One kind of test, one example
-
-Which kind a test is, is the first question — [the fork](docs/18-conventions.md#the-fork--which-kind-of-test-this-is) asks it in nine lines and the answer fixes the folder, the constructor and the project.
-
-**A module** — beside its code, nothing started ([docs/05](docs/05-module-tests.md)):
+A testing framework on vitest for whole products: HTTP APIs, background jobs, CLIs, websites, native mobile apps, rendered components, modules against real databases, and the lint rules a project ships. You declare what a test needs (Postgres, a built binary, a real Chromium, an iOS simulator), and the framework starts it, isolates it per worker and cleans it up. Each test is one sentence: a few setups, one action, and the whole result compared with `expect()`.
 
 ```typescript
-// src/domain/ranking.test.ts
-import { clock } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-import { rank } from './ranking.js';
-
-test('ranks a fresher post above an older one of equal score', () => {
-    // Given - two posts of equal score, one written this morning
-    using _ = clock.at('2026-03-04T09:30:00Z');
+// specs/api/users/list/shape.spec.ts
+import { file } from '@jterrazz/test';
+import { describe, expect, test } from 'vitest';
 
-    // Then - the fresher one leads
-    expect(rank(posts).map((post) => post.id)).toStrictEqual(['fresh', 'stale']);
-});
-```
+import { api } from '../../api.specification.js';
 
-**An integration spec** — a module against the real thing, or against a golden ([docs/06](docs/06-integration.md)):
+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');
 
-```typescript
-// specs/integration/posts/find.spec.ts
-import { expect, test } from 'vitest';
+        // Then - the whole response
+        expect(result.response).toMatch(`
+            HTTP/1.1 200 OK
+            content-type: application/json
 
-import { integration } from '../integration.specification.js';
-
-test('finds the post the migration wrote', async () => {
-    // Given - a seeded database
-    const result = await integration.seed('posts.sql').call(({ db }) => findPost(db, 'p-1'));
-
-    // Then - the row comes back as the repository shapes it
-    expect(result.value).toMatch('found.json');
-});
-```
-
-**A component** — a rendered unit in a real browser, beside its code ([docs/07](docs/07-component.md)):
-
-```tsx
-// src/presentation/post-table.test.tsx
-import { component, content } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-import { PostTable } from './post-table.js';
-
-test('says how much of the collection the table is showing', async () => {
-    // Given - a page of one row answering for a collection of two hundred
-    const result = await component.intercept(listing).render(<PostTable />, async (visitor) => {
-        await visitor.see(content('Showing 1 of 200 posts'));
+            {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+        `);
     });
-
-    // Then - the table is qualified by what it is not showing
-    await expect(result.tree).toMatch('one-of-two-hundred.aria.yaml');
 });
 ```
 
-**A website** — the served page, driven in a browser ([docs/08](docs/08-website.md)):
+`api` comes from a specification file that builds it once for the suite: `specification.api({ services: { db: sqlite() }, server: ... })` starts the database, wires your app to it and serves it in the test process. [Getting started](docs/start/getting-started.md) walks through it from `npm install` to a green run.
 
-```typescript
-// specs/website/subscribe/subscribe.spec.ts
-import { button, content, field } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-import { website } from '../website.specification.js';
-
-test('subscribes through the form and captures the final state', async () => {
-    // Given - a visitor on the homepage
-    const result = await website.visit('/', async (visitor) => {
-        await visitor.fill(field('Email'), 'visitor@site.test');
-        await visitor.click(button('Subscribe'));
-        await visitor.see(content('Thanks for subscribing'));
-    });
+## Why
 
-    // Then - the page says so, and the console is clean
-    expect(result.content).toContain('Thanks for subscribing');
-    await expect(result.errors).toBeEmpty();
-});
-```
-
-**A mobile screen** — the installed app on a simulator ([docs/09](docs/09-mobile.md)):
-
-```typescript
-// specs/mobile/events/bookmark.spec.ts
-import { button, content } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-import { mobile } from '../mobile.specification.js';
-
-test('bookmarks an event from its detail screen', async () => {
-    // Given - a visitor on the events feed
-    const result = await mobile.open('news://events', async (visitor) => {
-        await visitor.tap(button('Fauci inquiry'));
-        await visitor.see(content('reports'));
-        await visitor.tap(button('Bookmark'));
-    });
-
-    // Then - the capture reflects the screen after the interaction
-    expect(result.content).toContain('Bookmarked');
-});
-```
-
-**An API** — the assembled app, met through a complete HTTP exchange ([docs/10](docs/10-api.md)):
-
-```typescript
-// specs/api/users/create-user.spec.ts
-import { expect, test } from 'vitest';
-
-import { api } from '../api.specification.js';
+- **The infrastructure is declared, not scripted.** `postgres()`, `redis()`, `sqlite()` and `process()` are started for you, one database per worker, reset before every test.
+- **A result is compared whole.** The full response, table, output or page outline, written in the test or in a file beside it, with `{{tokens}}` for values that move. `TEST_UPDATE=1` writes the expected values for you to review.
+- **The conventions are a linter.** Where a test lives, how it is named and what it may import are checked by an oxlint plugin and a checker, and every finding says what it found, why, how to fix this case, and where to read more.
 
-test('creates a user and returns its location', async () => {
-    // Given - an empty users table
-    const result = await api.seed('empty.sql').request('create-user.http');
+## Install
 
-    // Then - the response matches the golden, tokens and all
-    expect(result.response).toMatch('user-created.http');
-    await expect(result.table('users')).toMatchRows({
-        columns: ['name'],
-        rows: [['Alice']],
-    });
-});
+```bash
+npm install -D @jterrazz/test @jterrazz/typescript vitest
 ```
 
-**A job** — what a name triggers, in-process ([docs/11](docs/11-jobs.md)):
-
-```typescript
-// specs/jobs/digest/daily-digest.spec.ts
-import { expect, test } from 'vitest';
-
-import { jobs } from '../jobs.specification.js';
+[`@jterrazz/typescript`](https://github.com/jterrazz/package-typescript) is the toolchain the framework is built for: one devDependency that builds, type-checks, lints and formats a project, run as `npx typescript check` and `npx typescript fix` (its bin is named `typescript`; it is not Microsoft's compiler package). It is a required peer ([why](docs/start/set-up-a-project.md#what-to-install)), and its lint conventions are opt-in: a project that never lists the framework's preset in `jterrazz.config.ts` runs none of them, and writes its tests all the same.
 
-test('writes one digest row per active subscriber', async () => {
-    // Given - two active subscribers and one cancelled
-    const result = await jobs.seed('subscribers.sql').trigger('daily-digest');
-
-    // Then - only the active ones were written
-    await expect(result.table('digests')).toMatchRows({
-        columns: ['to'],
-        rows: [['a@site.test'], ['b@site.test']],
-    });
-});
-```
-
-**A CLI** — the built binary, usually as a document ([docs/12](docs/12-cli.md)):
-
-```yaml
-# specs/cli/scaffold/new-project.spec.yaml
-description: scaffolds a project into an empty directory
-fixture: empty-dir
-runs:
-    - command: new my-app
-      exitCode: 0
-      stdout: scaffolded.txt
-      files:
-          my-app/package.json: package.json
-```
+An ES module project on Node 24, vitest 5 and `@jterrazz/typescript` 11 is required ([Setting up § Project requirements](docs/start/set-up-a-project.md#project-requirements)). A browser, a database driver or a simulator is installed only by a project that tests through it, and the error names the package when one is missing: see [Setting up a project](docs/start/set-up-a-project.md#what-to-install).
 
-## The map
+## What you can test
 
-Everything is stated ONCE, in the chapter that owns it — a second copy here would be a second answer, and the one a reader meets first is the one that goes stale. The corpus map is [docs/README.md](docs/README.md).
+| Kind                                            | Subject                                                         | Entry point                    |
+| ----------------------------------------------- | --------------------------------------------------------------- | ------------------------------ |
+| [Module](docs/guides/module-tests.md)           | One module, beside its code, nothing started                    | plain vitest, `<file>.test.ts` |
+| [Integration](docs/guides/integration-specs.md) | A module against real services, or against a golden             | `specification.integration()`  |
+| [Component](docs/guides/component-specs.md)     | A React component, hook or DOM function in a real Chromium      | `component.render()`           |
+| [Website](docs/guides/website-specs.md)         | A served page, fetched or driven in a browser                   | `specification.website()`      |
+| [Mobile](docs/guides/mobile-specs.md)           | A native app on an iOS simulator                                | `specification.mobile()`       |
+| [API](docs/guides/api-specs.md)                 | An HTTP app, through complete requests                          | `specification.api()`          |
+| [Job](docs/guides/job-specs.md)                 | A pipeline triggered by name                                    | `specification.job()`          |
+| [CLI](docs/guides/cli-specs.md)                 | A binary in a fresh working directory, often as a YAML document | `specification.cli()`          |
+| [Lint](docs/guides/lint-specs.md)               | The rules a project ships, over fixture trees                   | `specification.lint()`         |
 
-| Subject                                                          | Chapter                                                          |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
-| What the framework is, its trees, its channels, its four entries | [docs/01](docs/01-architecture.md)                               |
-| Installing it, the preset, the project helpers                   | [docs/02](docs/02-developing.md#vitest-config-the-preset)        |
-| What a consumer must bring: the peers, Docker, the pinned pair   | [docs/04](docs/04-operating.md#what-a-consumer-must-bring)       |
-| Each kind of test, one chapter, the same seven sections          | [docs/05](docs/05-module-tests.md)–[docs/12](docs/12-cli.md)     |
-| Naming an element: descriptors, verbs, `within`, exact names     | [docs/13](docs/13-elements.md)                                   |
-| Every matcher, by subject                                        | [docs/14](docs/14-assertions.md)                                 |
-| The `{{token}}` grammar, `#ref` captures, update mode            | [docs/15](docs/15-tokens.md)                                     |
-| Contracts, selection, provider builders, `intercept()`           | [docs/16](docs/16-contracts.md)                                  |
-| Services, init scripts, per-worker isolation, `process()`        | [docs/17](docs/17-services.md)                                   |
-| The conventions, and the catalogue that enforces them            | [docs/18](docs/18-conventions.md), [docs/19](docs/19-linting.md) |
+Which kind a test is depends on its subject, and one ordered list of questions decides it: [Which kind of test](docs/start/getting-started.md#which-kind-of-test).
 
-The conventions are not prose alone: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) and a `jterrazz-test-check` binary that reads the fixtures and cross-file relationships oxlint cannot. Every diagnostic ends in a rule id and an anchor into the generated catalogue.
+## Documentation
 
-Node 24 and vitest 5 are the required peers; everything else — a browser, a database driver, a simulator — is an optional peer, loaded the first time a spec needs it and named in the refusal when it is not there. What to install, and when: [docs/04](docs/04-operating.md#what-a-consumer-must-bring).
+The manual is [`docs/`](docs/README.md), mapped by the same four families as the package's exports:
 
-## Docs
+- **What is tested:** one guide per kind, linked above.
+- **What surrounds the subject:** [stubs](docs/reference/stubs.md) for the network, [services](docs/reference/services.md) for databases and processes, [time and doubles](docs/reference/time-and-doubles.md).
+- **Acting on a screen:** [the visitor](docs/reference/visitor.md): `click`, `fill`, `see`, and how elements are named.
+- **Judging the result:** [assertions](docs/reference/assertions.md) and [tokens](docs/reference/tokens.md).
 
-- The corpus: [docs/README.md](docs/README.md) — the spine, one chapter per kind, the shared references, the enforcement.
-- API reference: [docs/reference/](docs/reference/) — compiled from source by `npm run docs`.
-- Agent skill: [skills/jterrazz-test/](skills/jterrazz-test/) — the fork, the mental model, and a generated signature card per kind.
+The conventions and their reasons are [Conventions](docs/concepts/conventions.md); every rule, generated from the code, is [Linting](docs/reference/linting.md). The API is the types the package publishes, one declaration file per entry (`dist/index.d.ts` for `@jterrazz/test`, `dist/services.d.ts` and `dist/stubs.d.ts` for `@jterrazz/test/services` and `@jterrazz/test/stubs`, then `dist/vitest.d.ts`, `dist/config.d.ts` and `dist/oxlint.d.ts`), which your editor reads, and which you can browse without one in `node_modules/@jterrazz/test/dist/` or on [npm's Code tab](https://www.npmjs.com/package/@jterrazz/test?activeTab=code); each guide shows its kind's constructor, chain and result. Agents read [`skills/jterrazz-test/SKILL.md`](skills/jterrazz-test/SKILL.md).