@ultimat3/testing 12.0.0 → 13.0.0

package/CLAUDE.md

@@ -22,6 +22,11 @@ is its own entry point and not part of the barrel.
 | 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 |
 | No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
 | `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` — so a suite pinning "never throw a bare `Error`" stayed green through exactly the regression it guards (`matchers.test.ts`). Same discriminator `packages/cli/src/output.ts` uses to decide what the terminal shows, and a hostile getter answers `undefined` instead of raising inside the assertion |
+| 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. **`.not` waits for the element to GO**: it reads bun's `isNot` (measured — the flag is real but is not in bun's published types) and inverts what it waits FOR, never just the answer. Inverting a single look is a no-op that passes on a page which has not painted yet, which is the failure a retrying assertion exists to remove. `expect(await locator.isVisible()).toBe(true)` is the point-in-time spelling and stays a different assertion |
+| 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)` — one free look plus one per whole interval — and it is what a test asserts, because elapsed time is the one thing a frozen clock cannot give it. `retryUntil`'s `sleep` is a DEFAULT PARAMETER for the same reason a `random = Math.random` default is: a test injects a counting stub and measures how many times it looked and slept |
+| 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, …)` |
 | 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/README.md

@@ -16,7 +16,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `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` |
+| `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` `toAcceptInput` `toBeVisible` |
+| `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 |
 | `fixture-drivers.ts` | the five it declares but a driver must build — `page` `budget` `signIn` `deploy` `subscribe` |
@@ -356,6 +357,32 @@ changed when only the reviewer moved.
 **The command that takes the pictures is not here yet.** `As of 2026-08-23` this package ships the
 vocabulary, the expansion and the refusals; the browser half is `x shot`'s.
 
+## The one assertion that waits
+
+```ts
+import { e2eTest, expect } from '@ultimat3/testing';
+
+e2eTest('the feed paints, and says so when the socket drops', async ({ page }) => {
+  // Retries isVisible() to a budget — 5000ms every 100ms unless you narrow it.
+  await expect(page.getByRole('heading', { name: 'Feed' })).toBeVisible();
+  await expect(page.getByText('Reconnecting')).toBeVisible({ timeout: 10_000 });
+
+  // `.not` waits for it to GO, not for one look to come back false.
+  await expect(page.getByText('Offline')).not.toBeVisible();
+});
+```
+
+| Fact | Why |
+|---|---|
+| the budget is counted in **looks**, not elapsed ms | this package freezes `Date.now()`, so a deadline read off the clock never expires. `1 + floor(timeout / interval)` |
+| a fixed interval, never a curve | the caller's deadline is the contract; a curve spends most of it waiting. The framework's one backoff curve is `@ultimat3/core`'s |
+| `interval: 0` is refused | an unbounded spin is a test that never fails — it hangs, and CI reports a runner timeout with no assertion in it |
+| a receiver with no `isVisible()` is `X_TEST_LOCATOR_EXPECTED` | the assertion is unanswerable, not false; `pass: false` would read as "the element was hidden" |
+| `timeout: 0` is the non-retrying spelling | one look, no wait — and you have to ask for it |
+
+`expect(await locator.isVisible()).toBe(true)` still works and is a **different** assertion: it
+fails on a page that simply has not painted yet.
+
 ## Errors
 
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`

package/package.json

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

package/src/errors.ts

@@ -21,6 +21,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_EVAL_THRESHOLD',
   'X_TEST_SCHEMA_EXPECTED',
   'X_TEST_JOB_EXPECTED',
+  'X_TEST_LOCATOR_EXPECTED',
   'X_TEST_NETWORK_RACE',
   'X_TEST_FACTORY_TRAIT_UNKNOWN',
   'X_TEST_FACTORY_NOT_PERSISTED',
@@ -55,6 +56,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_EVAL_THRESHOLD: 'an evalTest() score fell below its threshold',
   X_TEST_SCHEMA_EXPECTED: 'a matcher expected a Standard Schema and got something else',
   X_TEST_JOB_EXPECTED: 'a matcher expected a job declaration and got something else',
+  X_TEST_LOCATOR_EXPECTED: 'a matcher expected a locator and got something else',
   X_TEST_NETWORK_RACE: 'a request raced unsealNetwork() and lost the patched fetch',
   X_TEST_FACTORY_TRAIT_UNKNOWN: 'a factory was asked for a trait it does not declare',
   X_TEST_FACTORY_NOT_PERSISTED: 'a factory create() had nowhere to write the row',
@@ -257,6 +259,22 @@ export class TestSchemaExpectedError extends UltimateError {
   }
 }
 
+/**
+ * `toBeVisible` was handed something with no `isVisible()` — a page, a selector string, or the
+ * result of awaiting the locator. Thrown rather than returned as a failing result, exactly as
+ * `TestSchemaExpectedError` is: the assertion is not false, it is unanswerable, and a `pass: false`
+ * would read as "the element was hidden".
+ */
+export class TestLocatorExpectedError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_LOCATOR_EXPECTED',
+      cause: 'toBeVisible expects a locator — an object with isVisible() — not a page or a string',
+      fix: 'expect(page.getByRole("heading", { name: "Feed" })).toBeVisible()   # the locator itself, unawaited',
+    });
+  }
+}
+
 /** `toEmitSteps`/`recordSteps` were handed something other than a job declaration. */
 export class TestJobExpectedError extends UltimateError {
   constructor() {

package/src/index.ts

@@ -185,6 +185,12 @@ export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-nod
 export { createLiveNode } from './live-node';
 export type { LiveReplicator, LiveReplicatorOptions } from './live-replicator';
 export { startLiveReplicator } from './live-replicator';
+/**
+ * The budget `toBeVisible(options?)` takes. Exported because it is in a public matcher's signature;
+ * `retryUntil` and `RetryBudget` deliberately are NOT — nothing outside this package calls them,
+ * and an export nothing calls is the unwired declaration this matcher exists to have closed.
+ */
+export type { VisibleOptions } from './matcher-visible';
 export type { MatcherResult } from './matchers';
 export { matchersInstalled, recordSteps } from './matchers';
 // `isolateEntityRegistry` is deliberately NOT here — it is `@ultimat3/testing/registry-isolation`.

package/src/matcher-result.ts

@@ -0,0 +1,7 @@
+// What every matcher in this package hands back. Its own module so `matcher-visible.ts` can carry
+// the shape without importing `matchers.ts`, which imports it.
+
+export interface MatcherResult {
+  readonly pass: boolean;
+  message(): string;
+}

package/src/matcher-surface.ts

@@ -3,6 +3,7 @@
 // program in the repo has to READ this declaration — `tsconfig.tests.json` names this file — and a
 // tier-0 test cannot reach it by importing tier-5 `@ultimat3/testing`.
 
+import type { VisibleOptions } from './matcher-visible';
 import type { OpenApiLike } from './test-types';
 
 /**
@@ -23,6 +24,13 @@ export interface UltimateMatchers<T> {
   toBeWithinBudget(limit: number): T;
   toRejectInput(input: unknown): Promise<T>;
   toAcceptInput(input: unknown): Promise<T>;
+  /**
+   * The one matcher that WAITS. Retries `isVisible()` to a budget — 5000ms every 100ms unless
+   * narrowed — and `.not.toBeVisible()` waits for the element to GO rather than inverting one look.
+   * Point-in-time is `expect(await locator.isVisible()).toBe(true)`, and it is a different
+   * assertion: it fails on a page that simply has not painted yet.
+   */
+  toBeVisible(options?: VisibleOptions): Promise<T>;
 }
 
 declare module 'bun:test' {

package/src/matcher-visible.ts

@@ -0,0 +1,68 @@
+// The one assertion in this package that WAITS. Split from `matchers.ts` because everything about
+// it is different from the others: it has a budget, it has a direction (`.not` waits for the
+// element to go), and its message has to say what it waited for and what it saw instead.
+
+import { TestLocatorExpectedError } from './errors';
+import type { MatcherResult } from './matcher-result';
+import { DEFAULT_RETRY_BUDGET, type RetryBudget, retryUntil } from './retry';
+
+/** What a caller may narrow. Both halves default to `DEFAULT_RETRY_BUDGET`. */
+export type VisibleOptions = Partial<RetryBudget>;
+
+/**
+ * Structural, and the ONE member it insists on is the one it calls. `LocatorLike` declares four,
+ * but a matcher demanding all four would refuse a driver's element handle over members this
+ * assertion never touches — and the receiver here is whatever a test passed to `expect()`.
+ */
+export interface VisibilityProbe {
+  isVisible(): Promise<boolean>;
+}
+
+/**
+ * SYNCHRONOUS, and that is the whole reason it is a function of its own.
+ *
+ * Measured against Bun 1.4.0: a matcher declared `async` that throws has its error replaced by
+ * bun's own `Matcher \`x\` returned a promise that rejected` — the code, the cause and the fix are
+ * all gone, and the reader is told nothing. A matcher that is NOT async and throws before it
+ * returns a promise keeps the error intact. So the receiver check runs here, in the synchronous
+ * prologue, and the waiting happens in the promise that follows it.
+ */
+export const assertVisibilityProbe = (received: unknown): VisibilityProbe => {
+  const probe = received as { isVisible?: unknown };
+  if (typeof received !== 'object' || received === null || typeof probe.isVisible !== 'function') {
+    throw new TestLocatorExpectedError();
+  }
+  return received as VisibilityProbe;
+};
+
+/**
+ * `pass` is the RAW fact — whether the element was visible on the last look — because `.not`
+ * inverts it and a matcher that pre-inverted would report the wrong direction. What `isNot` decides
+ * is what this WAITS FOR: `.not.toBeVisible()` must wait for the element to disappear, not check
+ * once and invert. Inverting a single look is a no-op that passes on a page which has not painted
+ * yet, which is the exact failure a retrying assertion exists to remove.
+ */
+export const visibilityResult = async (
+  probe: VisibilityProbe,
+  isNot: boolean,
+  options: VisibleOptions = {},
+): Promise<MatcherResult> => {
+  const budget: RetryBudget = {
+    timeout: options.timeout ?? DEFAULT_RETRY_BUDGET.timeout,
+    interval: options.interval ?? DEFAULT_RETRY_BUDGET.interval,
+  };
+  const wanted = !isNot;
+  const outcome = await retryUntil(
+    () => probe.isVisible(),
+    (visible) => visible === wanted,
+    budget,
+  );
+  const looks = `${outcome.attempts} look${outcome.attempts === 1 ? '' : 's'}, ${budget.interval}ms apart`;
+  // The BUDGET is reported, never an elapsed measurement: this package freezes `Date.now()`, so an
+  // "after 4993ms" would be a number nothing in the process could have produced.
+  const waited = `within ${budget.timeout}ms (${looks})`;
+  const message = isNot
+    ? `expected the locator to stop being visible ${waited}, and it was visible every time`
+    : `expected the locator to be visible ${waited}, and it was hidden every time`;
+  return { pass: outcome.last, message: () => message };
+};

package/src/matchers.ts

@@ -6,20 +6,19 @@ import type { ExpectExtendMatchers } from 'bun:test';
 import { expect } from 'bun:test';
 import { describeValue, isUltimateError, stringField } from '@ultimat3/core';
 import { TestJobExpectedError, TestSchemaExpectedError } from './errors';
+import type { MatcherResult } from './matcher-result';
 import type { UltimateMatchers } from './matcher-surface';
+import type { VisibleOptions } from './matcher-visible';
+import { assertVisibilityProbe, visibilityResult } from './matcher-visible';
 import type { OpenApiLike } from './test-types';
 
+export type { MatcherResult } from './matcher-result';
 // Re-exported so the EMITTED `matchers.d.ts` still names `./matcher-surface`. A type-only import
 // used by a non-exported const is elided from the declaration output, and with it goes the
 // `bun:test` augmentation for anyone consuming this package through `dist/` — which is every
 // package that reaches it across a project reference.
 export type { UltimateMatchers } from './matcher-surface';
 
-export interface MatcherResult {
-  readonly pass: boolean;
-  message(): string;
-}
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
@@ -56,6 +55,25 @@ interface StandardSchema {
 const isStandardSchema = (value: unknown): value is StandardSchema =>
   isRecord(value) && isRecord(value['~standard']);
 
+/**
+ * The receiver check, SYNCHRONOUS and separate from the work — measured against Bun 1.4.0: a
+ * matcher declared `async` 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 all gone by the time a reader sees
+ * it. `X_TEST_SCHEMA_EXPECTED` and `X_TEST_JOB_EXPECTED` were declared, registered and titled, and
+ * no caller could ever observe either (`matcher-receiver.test.ts`). The guard runs before the
+ * matcher returns a promise; the work happens inside it.
+ */
+function assertStandardSchema(schema: unknown): StandardSchema {
+  if (!isStandardSchema(schema)) throw new TestSchemaExpectedError();
+  return schema;
+}
+
+/** The same rule for a job declaration. `recordSteps` is public, so it keeps its own check too. */
+function assertJobDeclaration(job: unknown): JobLike {
+  if (!isJob(job)) throw new TestJobExpectedError();
+  return job;
+}
+
 async function hasIssues(schema: unknown, input: unknown): Promise<boolean> {
   if (!isStandardSchema(schema)) {
     throw new TestSchemaExpectedError();
@@ -176,7 +194,28 @@ function breakingChanges(before: OpenApiLike, after: OpenApiLike): readonly stri
  * of the three is visible, and a declared-but-unimplemented matcher fails at runtime in whichever
  * test calls it first.
  */
+/**
+ * What `expect.extend` binds `this` to. Bun supplies `isNot`, and it is the only member any matcher
+ * here reads — measured, because the shape is not in bun's published types and a matcher that
+ * guessed would silently wait for the wrong thing under `.not`.
+ */
+interface MatcherContext {
+  readonly isNot: boolean;
+}
+
 const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
+  // NOT `async`, deliberately — see `assertVisibilityProbe`. A matcher declared `async` has any
+  // error it throws replaced by bun's own "returned a promise that rejected", which is how the
+  // three matchers below it lost their codes. The guard runs synchronously; the wait is the
+  // promise this returns.
+  toBeVisible(received: unknown, options?: VisibleOptions) {
+    const probe = assertVisibilityProbe(received);
+    // `this` and not a parameter: the direction is bun's to tell us, and `.not` has to change what
+    // this WAITS for, not just how the answer is read.
+    const context = this as unknown as MatcherContext;
+    return visibilityResult(probe, context.isNot === true, options);
+  },
+
   toBeUltimateError(received: unknown, code?: string) {
     const actual = codeOf(received);
     if (actual === undefined) {
@@ -200,11 +239,15 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     return result(!allowed, `expected the policy to deny ${JSON.stringify(context)}`);
   },
 
-  async toEmitSteps(received: unknown, expected: readonly string[]) {
-    const names = await recordSteps(received);
-    return result(
-      JSON.stringify(names) === JSON.stringify(expected),
-      `expected steps ${expected.join(' -> ')}, ran ${names.join(' -> ')}`,
+  // Not `async` — see `assertStandardSchema`. The guard is the synchronous prologue; the wait is
+  // the promise this returns.
+  toEmitSteps(received: unknown, expected: readonly string[]) {
+    const job = assertJobDeclaration(received);
+    return recordSteps(job).then((names) =>
+      result(
+        JSON.stringify(names) === JSON.stringify(expected),
+        `expected steps ${expected.join(' -> ')}, ran ${names.join(' -> ')}`,
+      ),
     );
   },
 
@@ -232,14 +275,18 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     return result(received <= limit, `expected ${received} to be within the budget of ${limit}`);
   },
 
-  async toRejectInput(received: unknown, input: unknown) {
-    const rejected = await hasIssues(received, input);
-    return result(rejected, `expected the schema to reject ${JSON.stringify(input)}`);
+  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)}`),
+    );
   },
 
-  async toAcceptInput(received: unknown, input: unknown) {
-    const rejected = await hasIssues(received, input);
-    return result(!rejected, `expected the schema to accept ${JSON.stringify(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)}`),
+    );
   },
 };
 

package/src/retry.ts

@@ -0,0 +1,89 @@
+// Poll an observation until it matches, or until a declared budget runs out. The MECHANISM behind
+// every retrying assertion in this package, owned here so a second one cannot arrive with its own
+// deadline, its own interval and its own idea of what to report — the rule `backoff.ts` already
+// holds for retries that back off.
+
+import { assert } from '@ultimat3/core';
+
+/**
+ * What a retrying assertion is allowed to spend. A FIXED interval and not a curve: an assertion
+ * about a page is asked "is it there yet", and doubling the gap makes the last look land long
+ * after the state changed — the caller's deadline is the contract, and a curve would quietly
+ * spend most of it waiting. There is exactly one backoff curve in this framework
+ * (`@ultimat3/core`'s `backoff.ts`) and this is deliberately not a second one.
+ */
+export interface RetryBudget {
+  /** Total time the assertion may wait, in milliseconds. `0` is one look and no wait. */
+  readonly timeout: number;
+  /** Gap between looks, in milliseconds. */
+  readonly interval: number;
+}
+
+export interface RetryOutcome<T> {
+  readonly matched: boolean;
+  /** How many times the observation ran. `attemptsFor(budget)` when it never matched. */
+  readonly attempts: number;
+  /** What the last look answered — what a failure message reports as "saw" instead. */
+  readonly last: T;
+}
+
+/** Playwright's own default, which is what a reader of `toBeVisible()` already expects. */
+export const DEFAULT_RETRY_BUDGET: RetryBudget = { timeout: 5_000, interval: 100 };
+
+/**
+ * How many times the observation will run at most: one free look, plus one per whole interval in
+ * the budget. Exported because it is what makes a retry TESTABLE — a test asserts this number
+ * rather than measuring elapsed time, which is the one thing a frozen clock cannot give it.
+ */
+export const attemptsFor = (budget: RetryBudget): number =>
+  1 + Math.floor(budget.timeout / budget.interval);
+
+/** Real time passes here and nowhere else in this module, which is what makes `sleep` injectable. */
+const wait = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+/**
+ * Look, test, sleep, repeat — stopping on the look that matches or on the last one the budget buys.
+ *
+ * `sleep` is a DEFAULT PARAMETER and not a module-level call, the same seam a `random = Math.random`
+ * default is: a test injects a counting stub and asserts how many times this slept and how many
+ * times it looked, so "it retried, and it stopped when it said it would" is a measurement rather
+ * than a wall-clock hope. This package freezes `Date.now()`, so a deadline computed from the clock
+ * would never expire and the loop would spin forever — the budget is counted in LOOKS for that
+ * reason, not in elapsed milliseconds.
+ *
+ * Never sleeps after the look that answered: a passing assertion costs one observation and no time
+ * at all, which is what keeps a retrying matcher usable in a suite of hundreds.
+ */
+export const retryUntil = async <T>(
+  observe: () => Promise<T>,
+  matches: (value: T) => boolean,
+  budget: RetryBudget = DEFAULT_RETRY_BUDGET,
+  sleep: (ms: number) => Promise<void> = wait,
+): Promise<RetryOutcome<T>> => {
+  // Refused rather than attempted: a zero or negative interval is an unbounded spin, and the
+  // failure mode is a test that never fails — it hangs, and CI reports a runner timeout with no
+  // assertion anywhere in it.
+  assert(
+    Number.isFinite(budget.interval) && budget.interval > 0,
+    `a retry interval must be a positive number of milliseconds, got ${String(budget.interval)}`,
+    'toBeVisible({ interval: 100 })   # the gap between looks; the default budget is 5000ms every 100ms',
+  );
+  assert(
+    Number.isFinite(budget.timeout) && budget.timeout >= 0,
+    `a retry timeout must be zero or more milliseconds, got ${String(budget.timeout)}`,
+    'toBeVisible({ timeout: 5000 })   # the whole wait; 0 is one look and no wait',
+  );
+  const limit = attemptsFor(budget);
+  let attempts = 0;
+  let last = await observe();
+  attempts += 1;
+  while (!matches(last) && attempts < limit) {
+    await sleep(budget.interval);
+    last = await observe();
+    attempts += 1;
+  }
+  return { matched: matches(last), attempts, last };
+};

package/src/test-types.ts

@@ -44,19 +44,31 @@ export interface LocatorLike {
 }
 
 /**
- * The browser surface an e2e test drives. Every member is one the reference app's e2e suite
- * already calls — this is the observed contract, not a wish list, and the driver that implements
- * it (a browser, at milestone 11) is the only thing that may add to it.
+ * The browser surface an e2e test drives. Intended as the OBSERVED contract rather than a wish
+ * list, and the driver that implements it (a browser, at milestone 11) is the only thing that may
+ * add to it.
+ *
+ * This comment claimed every member was one the reference app's e2e suite already calls, and an
+ * audit on 2026-08-24 found that false for three of eleven: `content()` had ZERO call sites
+ * anywhere in the repository, and `title()` / `reload()` are named only by `x g route`'s generated
+ * template — a string the CLI writes, which nothing executes. `content()` is deleted; the other
+ * two keep their line WITH the caveat, because a generated template is a real contract the moment
+ * a driver lands and a scaffolded app runs it.
+ *
+ * The claim was checkable and nobody checked it, which is the class this tree keeps re-shipping.
+ * Nothing enforces this one either: `PageLike` has no driver, so an unwired member cannot fail —
+ * see `hasE2eDriver()`. Do not restore the absolute wording without a rule that reads it.
  */
 export interface PageLike {
   goto(url: string): Promise<unknown>;
   /** The first flush of a streamed response — the shell, before the holes resolve. */
   gotoStreamed(url: string): Promise<{ readonly html: string }>;
+  /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   reload(): Promise<unknown>;
   /** Resolves once the service worker controls the page, so the offline assertions are not racy. */
   waitForServiceWorker(): Promise<void>;
+  /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   title(): Promise<string>;
-  content(): Promise<string>;
   url(): string;
   evaluate<T>(fn: () => T): Promise<T>;
   locator(selector: string): LocatorLike;