@ultimat3/testing 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -2,8 +2,8 @@
 
 Tier 5. May import tiers 0–4. Imported by every package's tests and by generated apps.
 
-Deps: `core` (tier 0), plus `time`, `jobs`, `mail`, `db` and `entity` — imported **dynamically
-inside the fixture factories only**, so a test that never destructures `mail` never loads the mail
+Deps: `core` (tier 0), plus `time`, `jobs`, `mail`, `db`, `entity`, `render` and `http` — imported **dynamically
+inside the fixture factories only** (`render` inside `render-view.ts`, `http` inside `auth-request.ts`), so a test that never destructures `mail` never loads the mail
 package and a `packages/core` test never loads the entity registry. `entity` is a dependency for
 exactly one call: `nPlusOne()`, so the strict fixture reports the error `x dev` reports, with the
 `fix:` the schema's own relations spell. A second N+1 code owned here would be a second answer to
@@ -20,7 +20,11 @@ is its own entry point and not part of the barrel.
 | Self is not egress | a port core's `markListening()` announced passes through — a socket test never unseals |
 | Offline is a state, not a mock | `network.offline()` / `.drop()` fail every request as `X_TEST_NETWORK_OFFLINE`, ahead of the mocks — the app's own offline path runs |
 | One way offline | the `network` fixture. `setNetworkState` is the gate's only writer and is not exported — setting it from a test body skips the fixture's disposal and leaves every later file offline |
+| The seal key is a test process's, and nobody's export | `test-seal-key.ts`: installed by the preload only when `NODE_ENV === 'test'` and neither `ULTIMATE_SECRETS_KEY` nor `.secrets.key` exists; `startE2eApp` hands it to the child by VALUE (`testSealKeyEnv`), because the spawned app is a server and must never be able to install one. The constant is module-private and off the barrel (`test-seal-key.test.ts`). Never loosen the `NODE_ENV` check: the key is public |
+| `toEqualRow` never prints a server-only value | `matcher-row.ts` compares every OWN property (`toEqual` cannot see a `.sealed()` column — empty diff). A non-enumerable property that differs is NAMED; its value and its length stay out of the message, which lands in CI logs |
 | No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
+| A mutator's `local()` runs against `memoryLocalTx()` | `local-tx.ts`: keyed rows with the record store's rules (update invents nothing, `undefined` leaves a column, rows frozen). Never a hand-rolled table per test |
+| A page test RENDERS, with no cast | `render-view.ts`: `renderRoute(module, { url, actor })` resolves `load` once and hands `meta` and the page that one object, as every render mode does; `renderView(Component, props)` is one component. `@ultimat3/render` is imported INSIDE both, never at module scope — the barrel is what a tier-0 test imports for `expect` |
 | `toBeUltimateError` reads THREE fields | an `X_` code plus a `cause` plus a `fix`, all through core's `stringField`. `typeof value.code === 'string'` alone passed a Node `ENOENT` |
 | One matcher WAITS, and it is `toBeVisible` | `await expect(locator).toBeVisible()` retries `isVisible()` to a budget — 5000ms every 100ms, Playwright's own default, narrowable per call. |
 | The budget is counted in LOOKS, not milliseconds | this package freezes `Date.now()`, so a deadline computed from the clock never expires and the loop spins forever. `attemptsFor(budget)` is `1 + floor(timeout / interval)` |
@@ -29,12 +33,18 @@ is its own entry point and not part of the barrel.
 | Wrong receiver throws, wrong value returns | a matcher handed a page where a locator belongs is not FALSE, it is unanswerable — `pass: false` would read as "the element was hidden". A wrong-shaped receiver is a coded throw |
 | A matcher MESSAGE is a thunk, and never `JSON.stringify` | `result(pass, () => …)` — `expect.extend` reads `message()` only on the wrong verdict, and the string used to be built EAGERLY. |
 | Every message thunk needs a test that PROVOKES it | a thunk is a function, so an unread message is an UNCOVERED function and `bun run scripts/coverage-gate.ts --package testing` is what says so |
-| Test names | the filename picks the step; `testName(type, name)` on the outer `describe` puts that type on every failure line under it. Never on the inner `test` too — the prefix would print twice |
-| `test` here is `fixtureTest`, and it takes no timeout | `(name, body)`, nothing else (`fixtures.ts:248`, exported as `test` by `index.ts:107`) |
+| Test names | the filename picks the step; a typed helper prefixes its own name. `testName(type, name)` is for an outer `describe` only — never on the inner `test` too, the prefix would print twice |
+| One body shape, five registrars | `test` (= `fixtureTest`), `unitTest`, `contractTest`, `liveTest`, `jobTest` all take `FixtureBody` + `{ timeoutMs }`: `unitTest('…', async ({ runJobs }) => …)`. Never `describe(testName('unit', …))` + `test` to get a fixture |
+| `runJobs` says who and what | `{ actor }` is the WORKER's identity (the org stays the job's declared tenant), `{ tenantId }` the enqueuer's row; `executions[n].result` is the body's return. A fresh event bus per fixture |
+| A `runJobs` pass is a real worker's `tick()` | `fixture-jobs.ts` builds an unstarted `createWorker` per pass, so admission runs: `concurrency` waits and `whenBusy: 'fail'` refuses (`X_JOB_KEY_BUSY`) exactly as in a fleet. Never `executeJob` on a bare `claim()`. The lease and slot renew every 1 ms of TEST time (`RENEW_MS`, `frozen-scheduler.ts` on `onClockMoved`), never on a wall-clock interval: cancel, `clock.advance(1)`, and the body hears `X_JOB_LEASE_LOST` — no hand-built worker |
+| Per-test state is `per-test-reset.ts` | the app preload's `beforeEach` resets the jobs event bus — only when `@ultimat3/jobs` is already loaded, so a core test never loads it |
+| An island test is `describeIslandState` | one block per declared state: mounted in `beforeAll` (60 s), disposed in `afterAll`, one build per file. `mountIslandState` + `using` for one test's own mount; an undeclared id is `X_TEST_ISLAND_STATE_UNKNOWN` |
+| An authenticator is tested with `authRequest()` | the hook's own two arguments, real — never `as unknown as Parameters<…>` |
+| `LOG_LEVEL` above `info` filters the TERMINAL | `quiet-logs.ts` pins the logger at `info` while core loads, so a collecting `setLogSink` still sees `warn` under `LOG_LEVEL=error`. It stays the preload's FIRST import |
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
-| Fixtures | the preload registers the whole framework bag — an app registers only what the framework cannot know (`seed`, `actorFor`) |
-| e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. |
-| The seam has an inverse | `resetE2eDriver()`. `useE2eDriver` writes MODULE scope and `bun test` is one process, so a file that installs a browser must undo it |
+| Fixtures | the preload registers the framework bag — an app registers only what it alone knows (`seed`, `actorFor`) |
+| e2e without a driver | `e2eTest` becomes `test.skip`; the gate reports the step SKIPPED (or `X_VERIFY_SUITE_VANISHED` when `x.verify.json` requires it), never passed |
+| The seam has an inverse | `resetE2eDriver()`: `useE2eDriver` writes MODULE scope, so a file that installs a browser undoes it |
 | Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). |
 | `page` HAS a driver; `budget`, `signIn`, `deploy` do not | `installE2eDriver({ page, baseUrl })` registers `page` only. Byte counts, a sign-in route and a new build id are facts no page port can answer; a no-op would read as proof |
 | `network` is THIS process's fetch, and an e2e page is not in this process | `network.offline()` beside `page` is a no-op on the browser. `E2eFixtures.offline()` is the browser-side spelling and forwards to `E2eBrowserPage.offline()`; a page port with none refuses by name |
@@ -53,7 +63,7 @@ is its own entry point and not part of the barrel.
 | Leaks are the file's, not the next file's | `installRegistryLeakGuard()` runs from the preload and fails the run naming the FILE that left cache tags declared or a cache tier registered after its last test (`X_TEST_REGISTRY_LEAK`). |
 | The baseline is not a hook | measured on Bun 1.3.14 the order is onLoad → module eval → file `beforeAll` → describe `beforeAll` → preload `beforeEach`, so a preload hook cannot sample before the file's own `beforeAll` |
 | Reported and restored are different sets | the guard also RESTORES, at the same file boundary, the registries whose module-scope declarations a neighbour's cleanup destroys |
-| A catalog restore is a MERGE, never a replace, `As of 2026-08-23` | the other three registries are replaced with the snapshot; the catalogs are not. `registerCatalog` has no inverse, so the only thing a file can cost its neighbour is a `resetCatalogs()` |
+| A catalog restore is a MERGE, never a replace | the other three registries are replaced with the snapshot. `registerCatalog` has no inverse, so all a file can cost its neighbour is a `resetCatalogs()` |
 | Permissions are still REPLACED at a file boundary, and it is measured | an app's `definePermissions()` reached only by a dynamic `loadApp()` is dropped at that file's boundary exactly as catalogs were; the union rule would leak `permissions.test.ts`'s declarations into every later file. Open, its own piece of work (history) |
 | Guarded state is boot state | only the two registries whose honest invariant is "clean when the file ends" — `declareTags` and `registerTier` are boot installs. |
 | Filled and CLEARED are different questions | and the row above answers only the first. "Idiomatic to leave filled" is about the leak REPORT |
@@ -64,37 +74,37 @@ is its own entry point and not part of the barrel.
 | A boot that rejects is its own teardown | `acquireWorkerDatabase`, `seed` or `boot` throwing returns no `BootedHarness`, so no caller can ever reach `close()` |
 | A found template is not a migrated one | `template-db.ts` tolerates "already exists" for the `CREATE DATABASE` alone. `config.migrate` runs unconditionally and un-swallowed |
 | Fixture teardown | a fixture that installs process-global state (the ambient job or mail driver) implements `Symbol.dispose` / `Symbol.asyncDispose` and restores what was there |
-| Building one by hand | `createRunJobs()` outside `fixtureTest` is not disposed for you — reset the driver in `afterEach`, or the next file in the process inherits your queue |
+| Building one by hand | `createRunJobs()` outside a fixture body is not disposed for you — dispose it in `afterEach`, or the next file inherits your queue and your event bus |
 | Factory strategy | an association is built with the strategy that asked for it: `build()` never reaches a database, `create()` writes the parent first. Never a third strategy |
 | One write seam | `usePersister` is the only place `create()` writes. A factory that took a repo argument would put the seam at every call site |
 | Factory seeds | derived from the table name unless given, so two entities never draw the same uuid stream. `reset()` cascades into associated parents — a half-reset row is worse than none |
 | Shared examples | `behavesLike` calls `describe`, so it goes at declaration scope; bun rejects a `describe` inside a test body |
 | An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. |
 | `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited |
-| Dispose STOPS the island, then restores the globals | `mountIsland` keeps what `mount` resolved to and, when it is a function, calls it in `[Symbol.dispose]` BEFORE `restore()` |
+| Dispose STOPS the island, then restores the globals | when `mount` resolved to a function, `[Symbol.dispose]` calls it BEFORE `restore()` |
 | The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. `packages/ui/src/fake-dom.ts` is a second one for keyboard code, and `ui -> testing` is upward, so it is not a copy to collapse. `bun test` has no DOM and no DOM library may be added |
 | `style` and `classList` RECORD | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses (static attribute, `setProperty`, `cssText`, `removeAttribute`), so a test can assert the component set `--form-gap` |
 | `classList` is the class attribute | not a list of its own, so `classList.toggle` — what the compiler emits INLINE for `classList={{ … }}`, with no runtime helper in front of it — and `className` can never answer one element two ways. |
 | A `document` listener is the documentElement's | no bubbling: `document.addEventListener` registers on `documentElement`, and `fire(mounted.documentElement, 'keydown', …)` drives it. One handler per type, last wins |
 | `querySelector` skips `this` | descendants only, as the DOM's does. Matching the element it is called on made a host `<div>` answer `find('div')` with the container the test built rather than the markup the island rendered |
 | The selector grammar is SMALL and REFUSES | `island-selector.ts`: compounds of tag, `#id`, `.class`, `[attr]`, `[attr="value"]`, joined by space or `>`. Anything else is `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` with the offset, never an empty answer |
-| The box is 0 until a test writes it | `clientHeight`, `scrollTop`, `scrollHeight` and the rest are plain writable numbers, default 0, and `getBoundingClientRect()` derives from the offset box. |
+| The box is 0 until a test writes it | `clientHeight`, `scrollTop`, `scrollHeight` and the rest are writable numbers, default 0; `getBoundingClientRect()` derives from the offset box |
 | `ResizeObserver` records and never fires on its own | `island-observers.ts`, one registry PER DOCUMENT. |
-| A mount installs process globals | so `MountedIsland` is `Disposable` and a `mount` that THROWS restores before it rethrows. A fake `document` left installed reaches every later FILE in the run, and fails somewhere with no thread back |
+| A mount installs process globals | so `MountedIsland` is `Disposable` and a `mount` that THROWS restores before it rethrows. A fake `document` left installed reaches every later FILE in the run |
 | `fire` answers whether a handler ran | a selector matching nothing and an island that attached no handler are the same silence otherwise — the second is a bug, the first a typo. |
 | A states file is PURE DATA, and it is enforced | `defineIslandStates` declares the states an island can be photographed in — error, empty, over-quota, read-only |
-| The rule is the RELATIVENESS, not the extension, `As of 2026-08-23` | the scan refused `solid-js` and a specifier ENDING in `.tsx`/`.jsx`, and `import { X } from './settings.island'` resolves to `./settings.island.tsx` under Bun |
+| The rule is the RELATIVENESS, not the extension | `import { X } from './settings.island'` resolves to `./settings.island.tsx` under Bun, so any relative runtime import is refused |
 | `import type` is not an import, and it is the one way to name the component | `verbatimModuleSyntax` erases a statement that BEGINS `import type` / `export type` |
 | Unreadable is not pure | a computed specifier — ``import(`./${name}.island`)``, `require(SPEC)` — is refused as `IslandStatesOpaqueImportError` rather than passed. |
-| What the scan does NOT follow, stated rather than silent | a BARE specifier other than `solid-js`, an ABSOLUTE path specifier, and a specifier inside a string LITERAL (read as an import). The first two are holes; the third is a false refusal, the safe direction |
+| What the scan does NOT follow | a BARE specifier other than `solid-js`, an ABSOLUTE path (both holes), and a specifier inside a string LITERAL (a false refusal, the safe direction) |
 | Props are JSON or they are refused | they ride `data-x-props`, which `@ultimat3/render`'s `emitIslandProps` `JSON.stringify`s, so anything else is a prop the component never receives. |
 | The clock is pinned in the vocabulary, zone included | `timeZone` defaults to `ISLAND_SHOT_TIME_ZONE` (`UTC`) and `now` to this package's own `DEFAULT_NOW`, and both ride onto every `IslandShotTarget`. |
 | Loose in, strict out | `findIslandStates` resolves `Settings`, `settings`, `settings.island.tsx` and the full path to one manifest, and refuses a name nothing answers to by listing EVERY valid one |
 | The disk check is not in `defineIslandStates` | a declaration evaluates wherever it is imported from, so a rule that reads the filesystem at import time fails on the cwd rather than on the path. |
 | The island EXTENSION is not restated here | `.island.tsx` is `@ultimat3/render`'s `ISLAND_EXTENSION` and `render` is not a dependency of this package. |
 | The chunk is imported from a temp FILE | named by its SHA-256, so an edit is a new module and nothing is left in the app. Never a `data:` URL: `bun test --coverage` panics importing one past ~4 kB (Bun 1.4.0); `fixture-island.test.ts` pins it |
-| The scratch directory is lazy and removed, `As of 2026-08-22` | `mkdtempSync` ran at MODULE scope and nothing removed it, so every process importing `@ultimat3/testing` at all — this module is on the `.` barrel, so `expect` alone did it |
-| Attaching a node MOVES it | `appendChild`, `insertBefore` and `replaceChild` detach the node from its old parent first, and `removeChild` clears `parentNode` |
+| The scratch directory is lazy and removed | made on the first mount, deleted on `exit`; never at module scope — this module is on the `.` barrel |
+| Attaching a node MOVES it | `appendChild`, `insertBefore`, `replaceChild` detach it from its old parent first; `removeChild` clears `parentNode` |
 | Globals install all-or-nothing | `installGlobals` saves DESCRIPTORS, not values — a saved value cannot tell "no such global" from "a global holding `undefined`", and the teardown deleted both |
 | Which command shards | `bun test` is one process on one database, and that is still what a scaffolded app's `test` script runs. |
 
@@ -140,6 +150,7 @@ lives beside the `PageLike` it implements. `cli` imports it over the declared `c
 | `cdp-e2e-session.ts` | the BROWSER half, `E2eSession`: every target auto-attached at browser level and PAUSED until its Network domain is on (a SharedWorker opens its socket at start-up) |
 | `cdp-e2e-page.ts` | one TAB, `E2eTab`: `E2eBrowserPage`'s five methods plus `reload`, `waitFor`, `indexedDbNames`, `close`. `offline()` forwards to the session — the switch is browser-wide |
 | `e2e-app.ts` | `startE2eApp({ root, mode, seed })`: reset + seed + spawn on a THROWAWAY `ULTIMATE_STATE_DIR` and free ports, `/readyz`-gated, spawned through the app's own `@ultimat3/cli` bin (`xBin`); `stop()` removes the directory |
+| `failure-context.ts` | a FAILED test's message ends with the e2e app's last 40 log lines (≤ 4 kB): `e2e-run.ts` installs `app.log()`, `fixtureTest` and `e2eTest` append it. Never on a pass |
 | `e2e-preload.ts` + `e2e-browser-handle.ts` | the `e2e` step's preload (`@ultimat3/testing/e2e-preload`): with `ULTIMATE_E2E_ROOT` set it spawns the app, opens ONE browser, installs its first tab, and publishes `e2eBrowser()`, `e2eApp()`, `e2eBaseUrl()` |
 | `packages/cli/src/verify-e2e.ts` | `withE2eApp` (cli's): in an app on a machine with Chrome, the `e2e` step runs the suite with that preload; otherwise exactly as before |
 | `cdp-errors.ts` | one constructor per way the browser half refuses |
@@ -148,26 +159,8 @@ lives beside the `PageLike` it implements. `cli` imports it over the declared `c
 answers `false` and the gate's `e2e` step refuses rather than passing over a browser it lacks.
 GitHub-hosted `ubuntu-latest` ships Chrome at `/usr/bin/google-chrome`.
 
-**Raw CDP over Bun, no dependency.** A launched Chrome is driven over its debugging PIPE
-(`cdp-pipe.ts`); a remote one over Bun's `WebSocket` (`cdpConnect`). `x shot` and the dev MCP
-server's `ui.*` tools launch on the same `launchChrome` since 22.0.0
-(`packages/cli/src/cdp-shot-driver.ts`) — one launcher, one wire. A CDP event listener is handed
-the event's `sessionId` (`CdpEventListener`), so a subscriber owning one page ignores the rest.
-
-**The load EVENT is the completion signal, never `Page.navigate`'s reply** — Chrome drops the reply
-when a navigation swaps the render process. The waiter goes up before the send; the reply is read
-only for `errorText`.
-
-**Every call is deadlined, and a close settles every call in flight.** Four codes, four repairs:
-`X_CDP_BROWSER_MISSING` (install one), `X_CDP_LAUNCH_FAILED` (read its stderr, in the cause),
-`X_CDP_CALL_FAILED` (look at the page), `X_CDP_TIMEOUT` (raise the deadline).
-
-**`evaluate` is the lossy edge.** Only `Function.prototype.toString()` crosses: a zero-parameter
-closure over page globals works; native, bound, parameterised and method-shorthand closures are
-refused statically; a missing binding comes back named from the page's own `ReferenceError`.
-
-**`update()` still refuses** — a second build under a new build id is a SERVER fact no page port
-can speak for. `offline()`/`online()` forward to `E2eBrowserPage.offline`.
+How the raw-CDP driver behaves — the pipe, the load event, deadlines, the lossy `evaluate`, the
+refusing `update()` — is [`docs/history/testing.md`](../../docs/history/testing.md#the-e2e-driver-in-brief-moved-2026-10-01).
 
 The reasoning behind every rule above, verbatim, is [`docs/history/testing.md`](../../docs/history/testing.md).
 

package/README.md

@@ -15,8 +15,14 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `factory-registry.ts` | `factoriesFor(registry)` — one factory per entity, defaults read off column names |
 | `factory-persist.ts` | `usePersister` — the one seam `create()` writes through |
 | `shared-examples.ts` | `sharedExamples` / `behavesLike` — one rule, many subjects |
-| `test-types.ts` | the six test types and their helpers |
-| `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` `toAcceptInput` `toBeVisible` |
+| `test-types.ts` | the six test types and their helpers — four of them take the fixture bag, as `test` does |
+| `auth-request.ts` | `authRequest()` — the two arguments an app's authenticator is handed, built for real |
+| `island-state-mount.ts` | `describeIslandState()` / `mountIslandState()` — one declared island state, mounted, with the setup and teardown a mount owes |
+| `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` `toAcceptInput` `toEqualRow` `toBeVisible` |
+| `matcher-row.ts` | `toEqualRow` — equality over every OWN property, so a `.sealed()` column (not enumerable on a repository row) is compared; a server-only difference is named, never printed |
+| `test-seal-key.ts` | the throwaway master key a test process seals under when the app has none — installed by the preload, handed to the app `startE2eApp` spawns, exported from nowhere |
+| `local-tx.ts` | `memoryLocalTx()` — the client store a mutator's `local()` half writes into under test, with the record store's own rules |
+| `render-view.ts` | `renderView()` / `renderRoute()` — what the server renders, for a unit test: one component, or a whole route module with its `load`, `meta` and islands |
 | `retry.ts` | the one retry loop every waiting assertion is built from — a budget, a fixed interval, and an injectable sleep |
 | `fixtures.ts` | the registry + `test('…', ({ clock }) => …)` injection |
 | `fixture-{clock,mail,jobs,network,statements}.ts` | the five fixtures the framework builds in-process |
@@ -35,6 +41,7 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `registry-leak-guard.ts` | fails the run naming the FILE that left a process-global registry dirty, and restores the ones that can be restored at the same boundary |
 | `registry-snapshot.ts` | `captureProcessRegistries()` / `restoreProcessRegistries()` — the locale config, the catalogs, the permission set and the role map, put back as a file inherited them. A module-scope declaration evaluates once per process (`bun test` without `--isolate`, `As of 2026-08`), so a neighbour's `clearPermissions()` is otherwise permanent |
 | `registry-isolation.ts` | `isolateEntityRegistry()` — an empty entity registry, and the process's back after. Its own entry point (`@ultimat3/testing/registry-isolation`), never the barrel: it value-imports `@ultimat3/entity`, and the barrel is what a tier-0 test imports for `expect` |
+| `quiet-logs.ts` | a green run prints the reporter and nothing else: the framework's log lines go to a sink that drops them. `LOG_LEVEL=info bun test <file>` shows them — naming `LOG_LEVEL` is the one escape hatch, and a level above `info` filters what the TERMINAL shows, never what the logger emits (below). A test asserting on log output hands `createLogger({ level, writer })` its own writer, or installs its own `setLogSink` and restores the previous one |
 | `preload.ts` | the bunfig preload that installs all of the above |
 
 ## Install
@@ -45,15 +52,30 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 preload = ["@ultimat3/testing/preload"]
 ```
 
+The preload also sets `ULTIMATE_SECRETS_KEY` to a fixed throwaway key, so a test over a
+`.sealed()` column runs on a fresh clone and in CI, where `.secrets.key` (gitignored) is absent.
+
+| Rule | |
+|---|---|
+| Only a test process | `NODE_ENV=test`, which `bun test` sets. A server that imported the preload gets no key |
+| The app's key wins | nothing is installed when the variable is set or `.secrets.key` exists |
+| e2e | `startE2eApp` hands the same key to the reset, the seed and the app it spawns |
+| Not an export | the key is module-private; `installTestSealKey` is not on the barrel |
+
 ## Fixtures
 
-`test` from this package passes a fixture bag as the first argument, and builds only what the
-body destructures — a test that never names `runJobs` never starts a queue.
+`test` from this package — and `unitTest`, `contractTest`, `liveTest`, `jobTest` — passes a
+fixture bag as the first argument, and builds only what the body destructures: a test that never
+names `runJobs` never starts a queue, and one that destructures nothing builds nothing.
 
 ```ts
-import { expect, test } from '@ultimat3/testing';
+import type { JobHandle } from '@ultimat3/jobs';
+import { expect, unitTest } from '@ultimat3/testing';
 
-test('the three-day sleep releases the worker', async ({ clock, runJobs }) => {
+declare const onboardOrg: JobHandle<{ orgId: string }>; // yours
+declare const orgId: string;
+
+unitTest('the three-day sleep releases the worker', async ({ clock, runJobs }) => {
   await runJobs(onboardOrg, { orgId });
   expect(await runJobs.inFlight()).toBe(0);   // suspended, not waiting
   clock.advance('3d');
@@ -61,12 +83,15 @@ test('the three-day sleep releases the worker', async ({ clock, runJobs }) => {
 });
 ```
 
+One body shape for all five (`FixtureBody`), so a job body under the `unit` step is `unitTest`
+with `{ runJobs }` — never `describe(testName('unit', …))` around a bare `test` to reach a fixture.
+
 | Fixture | Is | Built by |
 |---|---|---|
 | `clock` | `now()` · `advance('3d')` · `set(instant)` on the frozen clock | the preload |
 | `mail` | `outbox()` · `lastTo(address)` · `failOnce(mail)` over an in-memory transport | the preload |
 | `network` | `offline()` · `drop()` · `online()` · `state()` over the sealed network | the preload |
-| `runJobs` | a worker: call it to enqueue+drain, then `drain()` `due()` `inFlight()` `depth()` | the preload |
+| `runJobs` | a worker: call it to enqueue+drain, then `enqueue()` `drain()` `due()` `inFlight()` `depth()` — see [below](#a-job-under-runjobs) | the preload |
 | `statements` | every statement the test issued: `all()` `count(fingerprint?)` `shapes()` — and an N+1 throws | the preload |
 | `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker` | a browser driver |
 | `budget` | `jsBytes(route)` measured off the built output | a browser driver |
@@ -103,6 +128,41 @@ that *is* registered — never `undefined is not an object` from inside the body
 registered but has no driver fails with `X_TEST_FIXTURE_UNAVAILABLE` instead; the two are different
 instructions, so they are different codes.
 
+## A job under `runJobs`
+
+```ts
+import { serviceActor } from '@ultimat3/core';
+import type { JobHandle } from '@ultimat3/jobs';
+import { expect, unitTest } from '@ultimat3/testing';
+
+declare const reindexPost: JobHandle<{ id: string; orgId: string }>; // yours
+declare const chargeInvoices: JobHandle<{ orgId: string }>;
+declare const id: string;
+declare const orgId: string;
+
+unitTest('a row deleted before the run is skipped, not failed', async ({ runJobs }) => {
+  const trace = await runJobs(reindexPost, { id, orgId });
+  expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
+  expect(trace.executions[0]?.result).toEqual({ skipped: true });   // what the BODY returned
+  expect(Object.keys(trace.steps)).toEqual(['load']);
+});
+
+unitTest('the sweep runs as the billing worker', async ({ runJobs }) => {
+  const worker = serviceActor({ id: 'billing-worker', scopes: ['billing:run'] });
+  await runJobs(chargeInvoices, { orgId }, { actor: worker, tenantId: orgId });
+});
+```
+
+| | |
+|---|---|
+| **`trace.executions[n].result`** | what the body returned, on a completed run — `undefined` for a body that returns nothing, and no such key on a run that failed, suspended or was interrupted. It is `executeJob`'s own (`JobExecution.result`): `{ skipped: true }` and "did the work" are otherwise one trace |
+| **`trace.steps[name]`** | `executions` (a replay from storage does not count), `attempts`, `status` — cumulative for the test |
+| **`{ actor }`** | on the call and on `drain()`: the identity the WORKER runs as — what an app wires through `WorkerOptions.context()`. Its org is replaced by the job's declared tenant, as a real worker's is; `tenant: 'none'` strips it. Absent is core's anonymous actor |
+| **`{ tenantId }`** | on the call and on `enqueue()`: the ENQUEUER's tenant on the row — the limiter's bucket and the dedupe namespace, the half of `handle.as(actor, input)` that reaches the queue. Never the tenant the body runs under: that is the job's own `tenant:` |
+| **one event bus per fixture** | `step.waitForEvent` reads an ambient bus that STORES; the fixture installs a fresh one and hands the process's back, so one test's `publishEvent` cannot resume the next test's run |
+| **a real worker's pass** | each round is `createWorker(...).tick()`: admission, the limiter and keyed `concurrency` (`whenBusy: 'fail'` settles `refused`, `X_JOB_KEY_BUSY`) hold exactly as in production |
+| **a cancel reaches a running body** | the worker renews its lease on the TEST clock — every millisecond of it — and a renewal that misses the row aborts `ctx.signal` with `X_JOB_LEASE_LOST`: start `runJobs.drain()`, cancel the row (`cancelJob(jobDriver(), id)` or the app's own action), `clock.advance(1)`, await the drain. No hand-built worker, no sleep, no wall-clock timer |
+
 ## An N+1 fails the test it happened in
 
 ```ts
@@ -141,6 +201,12 @@ there is no flag on the fixture and no code to silence.
 | `e2eTest` | a browser driver; with none registered it SKIPS, and the gate's `e2e` step passes over the skip — ask `hasE2eDriver()` rather than reading that as a pass | `e2e` |
 | `evalTest` | LLM output scoring against a threshold | `eval` |
 
+Each takes an optional `{ timeoutMs }` after the body — `unitTest(name, body, { timeoutMs: 30_000 })`,
+and `test` takes the same; `evalTest` reads it off its options — handed to `bun:test` as that
+test's own deadline (`TestOptions`). Absent is Bun's 5 s default. An `E2eDriver` receives it as its
+third argument. `unitTest`, `contractTest`, `liveTest` and `jobTest` hand their body the
+[fixture bag](#fixtures); `e2eTest` hands its own (`E2eFixtures`).
+
 **Registering one, `As of 2026-08-25`.** `@ultimat3/cli`'s `installE2eDriver({ page, baseUrl })` is
 the driver that exists — a `PageLike` over `@ultimat3/scraping`'s browser — and an app's test preload
 is what calls it. It returns the undo, and `resetE2eDriver()` is the seam's inverse for anything that
@@ -258,6 +324,117 @@ core's `markListening()`, so a test may call its own `handle.url()` on a kernel-
 the seal fully on. Unsealing (`ULTIMATE_TEST_ALLOW_NET=1`) stays reserved for a deliberate live
 integration — never for a socket test.
 
+## Rendering a page or a component
+
+A page is a function of props and a route is a module, so a unit test renders either in process —
+no server, no browser, and no cast between Solid's JSX types and the server factory's.
+
+```ts
+import type { Actor } from '@ultimat3/core';
+import type { RouteModule } from '@ultimat3/testing';
+import { expect, renderRoute, renderView, unitTest } from '@ultimat3/testing';
+
+// Yours: `import { Shell } from '../../shared/shell'` and `import * as page from './page'`.
+declare const Shell: (props: { nav: string; children: string }) => unknown;
+declare const page: RouteModule<{ rows: readonly unknown[] }>;
+declare const viewer: Actor;
+declare const t: (key: string) => string;
+
+unitTest('the dashboard counts the posts of the org that is looking', async () => {
+  const view = await renderRoute(page, { url: 'https://example.test/dashboard', actor: viewer });
+  expect(view.data.rows).toHaveLength(2);                 // what `load` resolved
+  expect(view.meta.title).toBe(t('app.dashboard.title')); // what `meta` answered for that data
+  expect(view.text).toContain(t('app.dashboard.tableTitle'));
+  expect(view.html).toMatch(/<a href="\/dashboard" aria-current="page"/);
+  expect(view.islands.map((island) => island.moduleId)).toEqual(['shared-theme-toggle']);
+});
+
+unitTest('the shell keeps the page in <main>', async () => {
+  const view = await renderView(Shell, { nav: 'dashboard', children: 'the page body' });
+  expect(view.html).toMatch(/<main[^>]*>the page body<\/main>/);
+});
+```
+
+| | |
+|---|---|
+| **`renderRoute(module, { url?, params?, actor? })`** | the route module passed WHOLE (`import * as page`), so the page is found by the router's own rule (`pageComponentOf`). `load` runs once; `meta` and the page are handed that one object; islands are collected under the route's own `hydrate` |
+| **`renderView(Component, props)`** | one component. `props` is the component's own type — a renamed prop is a compile error in the test. A component that renders an `island()` is refused here: its timing is a route's |
+| **`view.html`** | the markup as the document carries it |
+| **`view.text`** | what a reader sees: tags, `<script>` and `<style>` bodies removed, entities decoded, whitespace collapsed. Compare with `t('<key>')` — markup escapes what the catalog does not |
+| **`actor`** | `load` and the page run inside `runWithContext(createContext({ actor }))`. Without one they run outside any request context, as a static page does |
+| **the file stays `.test.ts`** | no JSX in a test: the registry-leak guard's loader covers `.test.ts` only, and children that need markup are a string |
+
+`@ultimat3/render` is imported inside the two functions, so the barrel still loads no renderer.
+
+## Testing an authenticator
+
+An app's `configureAuthenticator()` function is handed a request and its context. `authRequest`
+builds both for real — a `UltimateRequest` over a `RequestContext` — so the test calls the
+function with no server and no `as unknown as Parameters<…>`.
+
+```ts
+import type { Authenticator } from '@ultimat3/http';
+import { authRequest, expect, unitTest } from '@ultimat3/testing';
+
+declare const authenticate: Authenticator; // yours — the function `configureAuthenticator()` takes
+declare const token: string;
+declare const key: string;
+
+unitTest('a session cookie resolves the member it was issued to', async () => {
+  const actor = await authenticate(...(await authRequest({ cookies: { session: token } })));
+  expect(actor?.id).toBe('ada');
+});
+
+unitTest('an API key authenticates only under /v1', async () => {
+  const [request, ctx] = await authRequest({ url: 'https://example.test/v1/posts', bearer: key });
+  expect(await authenticate(request, ctx)).not.toBeNull();
+});
+```
+
+| Key | Is |
+|---|---|
+| `cookies` | by name, sent as the ONE `cookie` header a browser sends, values percent-encoded |
+| `bearer` | `Authorization: Bearer <token>` |
+| `headers` | any other header; `cookies` and `bearer` win over the same header spelled here |
+| `url` · `method` | `https://example.test/` and `GET` when absent |
+
+The answer is the hook's own parameter list (`Parameters<Authenticator>`), so a parameter the hook
+gains is a compile error in the test. The context is the one the `auth` stage sees: its actor is
+still anonymous, because resolving it is the function under test. `@ultimat3/http` is imported
+inside the function.
+
+## Running a mutator's local half
+
+`local(tx, input)` is replayed on every rebase, so what a test proves is the row it leaves and that
+a second application leaves the same one. `memoryLocalTx` is the store it writes into — keyed rows,
+with the page record store's rules — so the test holds no hand-rolled table and no cast.
+
+```ts
+import type { MemoryLocalTx } from '@ultimat3/testing';
+import { expect, memoryLocalTx, unitTest } from '@ultimat3/testing';
+
+type RenameInput = { id: string; orgId: string; title: string };
+declare const renamePost: { local(tx: MemoryLocalTx['tx'], input: RenameInput): void }; // yours
+declare const id: string;
+declare const orgId: string;
+
+unitTest('the local twin marks the row pending, and a replay lands in the same place', () => {
+  const store = memoryLocalTx({ posts: { [id]: { id, title: 'before', pending: false } } });
+  renamePost.local(store.tx, { id, orgId, title: 'after' });
+  const once = store.rows('posts');
+  expect(once).toEqual({ [id]: { id, title: 'after', pending: true } });
+  renamePost.local(store.tx, { id, orgId, title: 'after' });
+  expect(store.rows('posts')).toEqual(once);
+});
+```
+
+| | |
+|---|---|
+| **seed** | `{ <table>: { <key>: <row> } }`. Copied and frozen: a twin that mutates a row in place throws here rather than corrupting synced truth in a browser |
+| **`update`** | a NO-OP for a key the table does not hold — a twin must not invent a row |
+| **`upsert` / `update`** | an `undefined` field leaves the column alone |
+| **`store.rows(table)`** | what the table holds now, by key; `{}` for a table never seen |
+
 ## Testing an island
 
 An island is the only client-side code Ultimate ships, so it is the only code an app cannot test
@@ -316,6 +493,52 @@ which surfaced as `document is not defined` thrown into whichever later test hap
 running, and as one file's fetch stub receiving POSTs from another file's island. A `mount` that
 returns nothing disposes as it always did.
 
+### One block per declared state
+
+Every island declares its states (below), so an island test mounts THOSE — the props a picture is
+taken of are the props the test asserts on. `describeIslandState` owns what a mount owes: the
+lookup, the `beforeAll` that builds and mounts, the `afterAll` that disposes.
+
+```ts
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import type { IslandStatesManifest } from '@ultimat3/testing';
+import { describeIslandState, expect, test } from '@ultimat3/testing';
+
+declare const counterStates: IslandStatesManifest; // yours — './counter.island.states'
+
+const island = {
+  build: buildIslands,
+  root: join(import.meta.dir, '..', '..', '..'),
+  shell: '<span>shell</span>',          // what the server rendered; `mount` replaces it
+};
+
+describeIslandState(counterStates, 'idle', island, (mounted) => {
+  test('a click reaches the DOM through the signal', () => {
+    expect(mounted().fire('button', 'click')).toBe(true);
+    expect(mounted().text('[data-role="count"]')).toBe('1');
+  });
+});
+
+describeIslandState(counterStates, 'long-label', island, (mounted) => {
+  test('the label arrives whole', () => {
+    expect(mounted().text('button')).toBe('Abrechnungseinstellungen anzeigen');
+  });
+});
+```
+
+| | |
+|---|---|
+| **`mounted()`** | an accessor, for `describeApp`'s reason: the block is declared at module scope and the mount exists only once `beforeAll` has run. Outside its block's tests it throws |
+| **one mount per block** | shared by the block's tests, in order — a mount installs a process-global `document`, so two cannot be live at once |
+| **one build per file** | the bundle is kept per `(build, root, island)`; a second state mounts the chunk the first one built. A build that rejects is not kept |
+| **`timeoutMs`** | the mount's deadline, build included. `ISLAND_MOUNT_TIMEOUT_MS` (60 s) when absent — Bun's 5 s default is what a cold runner misses |
+| **`shell` · `globals` · `size`** | `mountIsland`'s own, per block. `file` and `props` are the manifest's and are not options |
+| **an id the manifest does not declare** | `X_TEST_ISLAND_STATE_UNKNOWN`, listing the declared ones |
+| **`mountIslandState(manifest, id, options)`** | the same lookup for ONE test that needs its own mount — a fetch stub per test: `using island = await mountIslandState(states, 'idle', { build, root })` |
+
+`mountIsland` stays the call for props no state declares.
+
 ### Selectors
 
 `find`, `all`, `text`, `fire`, `resize`, `scroll` and `observing` take one grammar, `As of
@@ -486,7 +709,7 @@ fails on a page that simply has not painted yet.
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`
 `X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
 `X_TEST_ISLAND_NOT_BUILT` `X_TEST_ISLAND_NO_MOUNT` `X_TEST_ISLAND_SELECTOR_UNSUPPORTED`
-`X_TEST_ISLAND_STATES_EMPTY`
+`X_TEST_ISLAND_STATES_EMPTY` `X_TEST_ISLAND_STATE_UNKNOWN`
 `X_TEST_ISLAND_STATES_NOT_PURE` `X_TEST_ISLAND_STATES_MISSING_FILE` `X_TEST_ISLAND_STATES_UNKNOWN`
 `X_TEST_ISLAND_STATES_AMBIGUOUS` `X_TEST_ISLAND_STATE_ID_INVALID` `X_TEST_ISLAND_STATE_DUPLICATE`
 `X_TEST_ISLAND_STATE_JSON_INVALID` `X_TEST_ISLAND_STATE_CLOCK_INVALID`
@@ -506,6 +729,22 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `RegistryLeakError` | `X_TEST_REGISTRY_LEAK` | `src/errors.ts` |
 | `TestDatabaseUnavailableError` | `X_TEST_DB_UNAVAILABLE` | `src/errors.ts` |
 
+## Log lines under test
+
+| `LOG_LEVEL` | The terminal shows | A `setLogSink` a test installs receives |
+|---|---|---|
+| unset | nothing — the reporter only | `info` and above |
+| `info` | `info` and above | `info` and above |
+| `debug` · `trace` | that level and above | that level and above — asking for more lines is asking for them everywhere |
+| `warn` · `error` · `fatal` · `silent` | that level and above | **`info` and above, still** |
+
+The last row is the rule: a level above `info` filters the TERMINAL, never the process logger.
+Core reads `LOG_LEVEL` once, when it is first imported, so `LOG_LEVEL=error bun test` used to raise
+the logger itself and a test asserting on an `info` audit line collected nothing. `quiet-logs.ts`
+pins the level at `info` for the moment core loads, restores the variable (a spawned child inherits
+what was named), and installs the filter. It is the preload's first import for that reason.
+`As of 2026-10`.
+
 ## One process, one registry
 
 `bun test` runs every file of one invocation in the same process — only `x verify`'s shards pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "22.14.0",
+  "version": "23.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -35,18 +36,19 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.14.0",
-    "@ultimat3/cache": "22.14.0",
-    "@ultimat3/core": "22.14.0",
-    "@ultimat3/db": "22.14.0",
-    "@ultimat3/entity": "22.14.0",
-    "@ultimat3/i18n": "22.14.0",
-    "@ultimat3/jobs": "22.14.0",
-    "@ultimat3/mail": "22.14.0",
-    "@ultimat3/policy": "22.14.0",
-    "@ultimat3/query": "22.14.0",
-    "@ultimat3/realtime": "22.14.0",
-    "@ultimat3/render": "22.14.0",
-    "@ultimat3/time": "22.14.0"
+    "@ultimat3/action": "23.0.0",
+    "@ultimat3/cache": "23.0.0",
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/db": "23.0.0",
+    "@ultimat3/entity": "23.0.0",
+    "@ultimat3/http": "23.0.0",
+    "@ultimat3/i18n": "23.0.0",
+    "@ultimat3/jobs": "23.0.0",
+    "@ultimat3/mail": "23.0.0",
+    "@ultimat3/policy": "23.0.0",
+    "@ultimat3/query": "23.0.0",
+    "@ultimat3/realtime": "23.0.0",
+    "@ultimat3/render": "23.0.0",
+    "@ultimat3/time": "23.0.0"
   }
 }

package/src/auth-request.ts

@@ -0,0 +1,54 @@
+// `authRequest()` — the two arguments `hooks.authenticate` is handed, built the way the pipeline
+// builds them, so a test of an app's authenticator calls it with no server and no cast.
+// `@ultimat3/http` is imported INSIDE the function: this module is on the `.` barrel, which a
+// tier-0 test imports for `expect` alone.
+
+import type { Authenticator } from '@ultimat3/http';
+
+/** What an authenticator reads off a request: where it came in, and the credentials it carries. */
+export interface AuthRequestInit {
+  /** The URL the request names. `https://example.test/` when absent. */
+  readonly url?: string;
+  /** `GET` when absent. */
+  readonly method?: string;
+  /** Any header. `cookies` and `bearer` below win over the same header spelled here. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Cookies by name, sent as the ONE `cookie` header a browser sends, values percent-encoded. */
+  readonly cookies?: Readonly<Record<string, string>>;
+  /** `Authorization: Bearer <token>`. */
+  readonly bearer?: string;
+}
+
+const DEFAULT_URL = 'https://example.test/';
+
+/**
+ * The authenticator's own parameter list — `await authenticate(...(await authRequest({ cookies })))`
+ * — as a real `UltimateRequest` over a real `RequestContext`. Typed off `Authenticator`, so a
+ * third parameter on the hook is a compile error here rather than an `undefined` in a test.
+ *
+ * The context is the one the `auth` stage sees: the actor is still anonymous, because resolving
+ * it is the function under test.
+ */
+export async function authRequest(init: AuthRequestInit = {}): Promise<Parameters<Authenticator>> {
+  const http = await import('@ultimat3/http');
+  const url = new URL(init.url ?? DEFAULT_URL);
+  const method = (init.method ?? 'GET').toUpperCase();
+  const headers = new Headers(init.headers);
+  const cookies = Object.entries(init.cookies ?? {});
+  if (cookies.length > 0) {
+    headers.set(
+      'cookie',
+      cookies.map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join('; '),
+    );
+  }
+  if (init.bearer !== undefined) headers.set('authorization', `Bearer ${init.bearer}`);
+  const ctx = http.createRequestContext({
+    url,
+    method,
+    role: 'web',
+    // One process, one test: the limiter's scope has no default, and nothing here spends a bucket.
+    config: http.defineHttpConfig({ rateLimit: { scope: 'process' } }),
+    requestHeaders: headers,
+  });
+  return [new http.UltimateRequest(new Request(url, { method, headers }), ctx), ctx];
+}