@ultimat3/testing 19.2.0 → 19.3.1

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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "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.1",
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/db": "19.3.1",
+    "@ultimat3/entity": "19.3.1",
+    "@ultimat3/i18n": "19.3.1",
+    "@ultimat3/jobs": "19.3.1",
+    "@ultimat3/mail": "19.3.1",
+    "@ultimat3/policy": "19.3.1",
+    "@ultimat3/query": "19.3.1",
+    "@ultimat3/realtime": "19.3.1",
+    "@ultimat3/time": "19.3.1"
   }
 }

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)}`),
     );
   },
 };