@ultimat3/testing 19.2.0 → 19.3.2

package/CLAUDE.md

@@ -27,6 +27,8 @@ is its own entry point and not part of the barrel.
 | A FIXED interval, and never a curve | doubling the gap makes the last look land long after the state changed, and the caller's deadline is the contract. There is exactly one backoff curve in the framework (`@ultimat3/core`'s `backoff.ts`) and this is deliberately not a second one. A zero or negative interval is REFUSED: the failure mode is a test that never fails — it hangs, and CI reports a runner timeout with no assertion in it |
 | A matcher that may throw a coded error MUST NOT be `async` | measured against Bun 1.4.0: an `async` matcher has any error it throws REPLACED by bun's own `Matcher \`x\` returned a promise that rejected`, so the code, the cause and the fix are gone before a reader sees them. `X_TEST_SCHEMA_EXPECTED` and `X_TEST_JOB_EXPECTED` were declared, registered, titled — and unreachable by any caller for their whole life, because nothing asserted them. The shape is a SYNCHRONOUS prologue that validates the receiver (`assertStandardSchema`, `assertJobDeclaration`, `assertVisibilityProbe`) and a promise returned after it. `matcher-receiver.test.ts` pins all four |
 | 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 wrong value is `result(false, …)` |
+| 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. `JSON.stringify` refuses a BigInt and throws on anything cyclic, so `expect(schema).toRejectInput({ n: 1n })` — a schema that DID reject — came back as ``Matcher `toRejectInput` returned a promise that rejected``, with the real answer gone, on the PASSING path. Three matchers quoted their input that way. `renderCauseValue` (`@ultimat3/core`) is the renderer: it quotes what JSON can quote and names the shape of what it cannot, so the message still reads `expected the schema to reject {"id":"ok"}` |
+| 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 — the eleven thunks landed with two of them read and took the package from 95.62% to 94.03%. That number is the useful half: `.not` on a `pass: false` never asks for the message, so `expect({ paths: {} }).not.toMatchOpenApi(…)` passes with the type guard deleted, and the same test reads as covering the matcher. `messageOf()` in `matchers.test.ts` awaits the FAILING side and asserts the sentence, whichever way bun delivers it |
 | 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`) — `bunTest` is called with two arguments, so bun's own third one is unreachable and no case can ask for more than the default 5s. Slow work goes in `beforeAll(fn, 60_000)`, which is `bun:test`'s own re-export and does take one; that is where both generated island tests and `examples/dummy/apps/web/app/settings/settings.island.test.ts` build their chunk, once, for every case to share — a Babel pass plus a browser bundle is seconds. A case that needs 60s of its own is work sitting in the wrong place |
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
@@ -69,6 +71,7 @@ is its own entry point and not part of the barrel.
 | 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({ build, root, file })` takes the function as a parameter and declares only the two fields it reads — `IslandChunkLike` is `{ file, code }`, so a CSS artifact, a source map or a dev/production flag the bundler grows is invisible here. Moving the bundler down a tier was the alternative and it drags `@babel/core` and `babel-preset-solid` with it, into a package whose whole point is being importable from tier 0 |
 | `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited — the shipped runtime chains `import(e).then((m) => m.mount(el, props))` (`packages/render/src/hydrate.ts`) and only marks the element mounted when that settles, so an `async` mount is an ordinary island and `like.island.tsx` already is one. Typed `=> void` and called bare, the fixture returned before an island that opens a queue or a socket had rendered anything, so every assertion after it read an empty wrapper — and worse, the mount RESUMED after `restore()` had taken the fake `document` back out, failing with `document is not defined` inside whichever later test happened to be running. Not a breaking change: `IslandEntry` is module-private and an island module is matched structurally off an `unknown` import, so nothing implements it. |
+| 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()` — the island's disposer clears an interval whose callback reads `document`, or removes a listener from it, and must find the `document` it was made against. Solid's `render` returns a disposer, so `return render(…)` is an island's whole side of it (`X_TEST_ISLAND_NO_MOUNT`'s fix line and `x g island`'s template both say so). Restoring the globals was the whole teardown until 2026-09-07, and an island that polled on an interval kept ticking after the DOM was gone: measured in ai-maxxing as `document is not defined` thrown into whichever later test was running and as one file's fetch stub receiving another file's POSTs. Once — `using` and an `afterAll` that also disposes by hand are both real — and a disposer that throws still hands the globals back in a `finally`; the throw is the test's to see |
 | The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. **"Once" is scoped to this job, and said so only from 2026-08-23**: `packages/ui/src/fake-dom.ts` is a second micro-DOM (201 lines, test-only, off that package's barrel) for a different one — focus, `activeElement`, `contains` and a `:not()` selector grammar for keyboard code, none of which parses a `<template>`. It is not a copy to collapse: `ui` is tier 4 and this package is tier 5, so `ui -> testing` is an upward import the boundary check refuses, and the merge would need the shared half moved down to a tier neither grammar belongs in. `bun test` has no DOM and no DOM library may be added; `generate: 'dom'` builds every element from `_$template("<label …>")`, so a stub without a parsed `<template>` cannot run one line of a compiled island. It lived twice, ~200 lines each, in `packages/cli/src/island-bundle.test.ts` and the reference app's island test |
 | `style` and `classList` RECORD, `As of 2026-08` | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses on one element: a STATIC entry baked into the template's `style=` attribute, a dynamic one through `setStyleProperty` → `style.setProperty`, a whole-object or string prop through `style()` → `cssText`, and a cleared one through `removeAttribute`. It was `style = {}` until 2026-08-21 — `<Form>`, `<Stack>`, `<Grid>` and `<Container>` each set a CSS custom property, so every one of them died inside `mount` with `e.style.setProperty is not a function`, and `x g resource` emitted a plain `<form>` rather than the design system's. A design-system component kept out of generated code by the limits of a TEST DOUBLE. A no-op `setProperty` would have stopped the crash and left "the component set `--form-gap`" unassertable, which is the same hole one layer down |
 | `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. `add` was the only method the stand-in had and is the one Solid never calls |

package/README.md

@@ -303,6 +303,17 @@ removed.
 `island[Symbol.dispose]()` in an `afterAll`. Left installed it hands a fake `document` to every
 later FILE in the run.
 
+**Dispose also stops the island** (`As of 2026-09-07`): when `mount` returns a function, that is
+the island's disposer and dispose calls it — before the globals go back, so a disposer that
+removes a listener from `document` or clears an interval whose callback reads it finds the same
+`document` `mount` ran under. Solid's `render` already returns exactly that, so an island's whole
+side of the contract is `return render(() => <Counter {...props} />, el)` — and a disposed root
+runs every `onCleanup` inside it. Until this landed, restoring the globals was the whole of the
+teardown: an island whose `mount` polled on an interval kept ticking after the DOM was gone,
+which surfaced as `document is not defined` thrown into whichever later test happened to be
+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.
+
 ### Selectors
 
 `find`, `all`, `text`, `fire`, `resize`, `scroll` and `observing` take one grammar, `As of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "19.2.0",
+  "version": "19.3.2",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -33,16 +33,16 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "19.2.0",
-    "@ultimat3/core": "19.2.0",
-    "@ultimat3/db": "19.2.0",
-    "@ultimat3/entity": "19.2.0",
-    "@ultimat3/i18n": "19.2.0",
-    "@ultimat3/jobs": "19.2.0",
-    "@ultimat3/mail": "19.2.0",
-    "@ultimat3/policy": "19.2.0",
-    "@ultimat3/query": "19.2.0",
-    "@ultimat3/realtime": "19.2.0",
-    "@ultimat3/time": "19.2.0"
+    "@ultimat3/cache": "19.3.2",
+    "@ultimat3/core": "19.3.2",
+    "@ultimat3/db": "19.3.2",
+    "@ultimat3/entity": "19.3.2",
+    "@ultimat3/i18n": "19.3.2",
+    "@ultimat3/jobs": "19.3.2",
+    "@ultimat3/mail": "19.3.2",
+    "@ultimat3/policy": "19.3.2",
+    "@ultimat3/query": "19.3.2",
+    "@ultimat3/realtime": "19.3.2",
+    "@ultimat3/time": "19.3.2"
   }
 }

package/src/errors.ts

@@ -466,7 +466,7 @@ export class IslandMountMissingError extends UltimateError {
       fix:
         component === undefined
           ? `${file} exports nothing a mount could render — x g island <name> --at apps/web/site writes an island whose mount() is already there, and its shape is the one to copy`
-          : `in ${file} add: import { render } from 'solid-js/web'; export function mount(el: HTMLElement, props: Parameters<typeof ${component}>[0]): void { el.textContent = ''; render(() => <${component} {...props} />, el); }`,
+          : `in ${file} add: import { render } from 'solid-js/web'; export function mount(el: HTMLElement, props: Parameters<typeof ${component}>[0]): () => void { el.textContent = ''; return render(() => <${component} {...props} />, el); }`,
     });
   }
 }

package/src/fixture-island.ts

@@ -57,6 +57,10 @@ export interface MountIslandOptions {
   readonly size?: ResizeInput;
 }
 
+/**
+ * `Disposable`: dispose calls the disposer the island's `mount` returned (Solid's `render` answers
+ * one — `return render(…)`), then hands the process its globals back. Both, in that order.
+ */
 export interface MountedIsland extends Disposable {
   /** The chunk's source, for asserting on what did or did not reach the browser. */
   readonly code: string;
@@ -101,11 +105,19 @@ export interface MountedIsland extends Disposable {
  * opens a queue or a socket first is therefore an ordinary island (`like.island.tsx` is `async`),
  * and a fixture typed `=> void` could only ever call it and walk away. Widening, not narrowing: an
  * island module is matched structurally off an `unknown` import, so nothing implements this type.
+ *
+ * What `mount` answers, once awaited, is the island's DISPOSER when it is a function — the one
+ * way an island hands back what it started, and Solid's `render` already returns exactly that, so
+ * `return render(…)` is the whole of an island's side. The fixture calls it on dispose.
  */
 interface IslandEntry {
   readonly mount: (el: unknown, props: unknown) => unknown;
 }
 
+/** The island's disposer, when `mount` answered one — anything else is an island with nothing to stop. */
+const disposerOf = (returned: unknown): (() => void) | undefined =>
+  typeof returned === 'function' ? (returned as () => void) : undefined;
+
 /** `unknown` + a check, not a cast: a chunk whose `mount` was renamed is a real authoring mistake
  *  and `entry.mount is not a function` names neither the file nor the export it wanted. */
 function entryOf(module: unknown, file: string): IslandEntry {
@@ -198,6 +210,13 @@ function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
  * The island fixture. Everything it installs is process-global, so the result is `Disposable` and
  * the idiom is `using mounted = await mountIsland(…)` — a mount left installed hands a fake
  * `document` to every later FILE in the run.
+ *
+ * Dispose is two things in one order: the island's own disposer first, then the globals back.
+ * Restoring the globals was the whole of it until 2026-09-07, so an island whose `mount` started
+ * an interval kept ticking after the DOM was gone — measured as `document is not defined` thrown
+ * into whichever later test was running, and as one file's fetch stub receiving POSTs from another
+ * file's island. The disposer runs while the fake `document` is still installed, because what it
+ * clears (a listener on `document`, an interval whose callback reads it) was made against that one.
  */
 export async function mountIsland(options: MountIslandOptions): Promise<MountedIsland> {
   // `only`, because this fixture has always KNOWN which island it wants and asked for all of them
@@ -240,7 +259,21 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     // island's `mount` resumed AFTER the `restore()` below had taken the fake `document` back out
     // — so it failed with `document is not defined` inside whichever later test happened to be
     // running, with no thread back here.
-    await entry.mount(el, options.props);
+    const unmount = disposerOf(await entry.mount(el, options.props));
+    let disposed = false;
+    const dispose = (): void => {
+      // Once: `using` and an `afterAll` that also disposes by hand are both real, and Solid's own
+      // disposer is idempotent while an island's `clearInterval` wrapper need not be.
+      if (disposed) return;
+      disposed = true;
+      try {
+        unmount?.();
+      } finally {
+        // Whatever the disposer did — including throw, which is the test's to see — the process
+        // gets its globals back, or the fake `document` reaches every later file in the run.
+        restore();
+      }
+    };
     const resolve = (target: string | FakeElement | null | undefined): FakeElement | null =>
       typeof target === 'string' ? el.querySelector(target) : (target ?? null);
     return {
@@ -271,7 +304,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
         const node = resolve(target);
         return node !== null && [...resizeObservers].some((each) => each.targets.has(node));
       },
-      [Symbol.dispose]: restore,
+      [Symbol.dispose]: dispose,
     };
   } catch (error) {
     // A mount that throws restores the process before it rethrows: the alternative leaves every

package/src/matchers.ts

@@ -4,7 +4,7 @@
 
 import type { ExpectExtendMatchers } from 'bun:test';
 import { expect } from 'bun:test';
-import { describeValue, isUltimateError, stringField } from '@ultimat3/core';
+import { describeValue, isUltimateError, renderCauseValue, stringField } from '@ultimat3/core';
 import { TestJobExpectedError, TestSchemaExpectedError } from './errors';
 import type { MatcherResult } from './matcher-result';
 import type { UltimateMatchers } from './matcher-surface';
@@ -144,10 +144,15 @@ export async function recordSteps(job: unknown, input: unknown = {}): Promise<re
   return names;
 }
 
-const result = (pass: boolean, message: string): MatcherResult => ({
-  pass,
-  message: () => message,
-});
+/**
+ * A THUNK, never a built string. `expect.extend` reads `message()` only when the verdict is the
+ * wrong one, and building the sentence eagerly made three matchers raise from inside the assertion
+ * library on values they were answering correctly: `JSON.stringify` refuses a BigInt and throws on
+ * anything cyclic, so `expect(schema).toRejectInput({ n: 1n })` — a schema that DID reject — came
+ * back as `Matcher \`toRejectInput\` returned a promise that rejected`, with the real answer gone.
+ * Deferred, a value that cannot be rendered costs nothing on the path that passes.
+ */
+const result = (pass: boolean, message: () => string): MatcherResult => ({ pass, message });
 
 const isOpenApiLike = (value: unknown): value is OpenApiLike =>
   isRecord(value) &&
@@ -221,11 +226,12 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     if (actual === undefined) {
       return result(
         false,
-        `expected an UltimateError (an X_ code with a cause and a fix), received ${describeValue(received)}`,
+        () =>
+          `expected an UltimateError (an X_ code with a cause and a fix), received ${describeValue(received)}`,
       );
     }
-    if (code === undefined) return result(true, `expected not to be an UltimateError`);
-    return result(actual === code, `expected error code ${code}, received ${actual}`);
+    if (code === undefined) return result(true, () => 'expected not to be an UltimateError');
+    return result(actual === code, () => `expected error code ${code}, received ${actual}`);
   },
 
   async toDenyPolicy(received: unknown, context: Readonly<Record<string, unknown>>) {
@@ -233,10 +239,13 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     if (allowed === undefined) {
       return result(
         false,
-        'expected a policy — an object with run() (@ultimat3/policy) or evaluate()',
+        () => 'expected a policy — an object with run() (@ultimat3/policy) or evaluate()',
       );
     }
-    return result(!allowed, `expected the policy to deny ${JSON.stringify(context)}`);
+    // `renderCauseValue`, never `JSON.stringify`: the context is a value a test authored, and this
+    // matcher is asked about policies whose input holds a BigInt id or a back-reference. It quotes
+    // what JSON can quote and names the shape of what it cannot, instead of throwing over either.
+    return result(!allowed, () => `expected the policy to deny ${renderCauseValue(context)}`);
   },
 
   // Not `async` — see `assertStandardSchema`. The guard is the synchronous prologue; the wait is
@@ -246,7 +255,7 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     return recordSteps(job).then((names) =>
       result(
         JSON.stringify(names) === JSON.stringify(expected),
-        `expected steps ${expected.join(' -> ')}, ran ${names.join(' -> ')}`,
+        () => `expected steps ${expected.join(' -> ')}, ran ${names.join(' -> ')}`,
       ),
     );
   },
@@ -255,13 +264,15 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     if (!isOpenApiLike(received)) {
       return result(
         false,
-        'expected an OpenAPI document — an object with operations: [{ operationId, required? }]',
+        () =>
+          'expected an OpenAPI document — an object with operations: [{ operationId, required? }]',
       );
     }
     const broke = breakingChanges(committed, received);
     return result(
       broke.length === 0,
-      `contract broke: ${broke.join('; ')} — bump the package version or restore the old shape`,
+      () =>
+        `contract broke: ${broke.join('; ')} — bump the package version or restore the old shape`,
     );
   },
 
@@ -269,23 +280,26 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     if (typeof received !== 'number') {
       return result(
         false,
-        `expected a number to compare against the budget, got ${typeof received}`,
+        () => `expected a number to compare against the budget, got ${typeof received}`,
       );
     }
-    return result(received <= limit, `expected ${received} to be within the budget of ${limit}`);
+    return result(
+      received <= limit,
+      () => `expected ${received} to be within the budget of ${limit}`,
+    );
   },
 
   toRejectInput(received: unknown, input: unknown) {
     const schema = assertStandardSchema(received);
     return hasIssues(schema, input).then((rejected) =>
-      result(rejected, `expected the schema to reject ${JSON.stringify(input)}`),
+      result(rejected, () => `expected the schema to reject ${renderCauseValue(input)}`),
     );
   },
 
   toAcceptInput(received: unknown, input: unknown) {
     const schema = assertStandardSchema(received);
     return hasIssues(schema, input).then((rejected) =>
-      result(!rejected, `expected the schema to accept ${JSON.stringify(input)}`),
+      result(!rejected, () => `expected the schema to accept ${renderCauseValue(input)}`),
     );
   },
 };