@ultimat3/testing 20.2.1 → 22.0.0

package/src/errors.ts

@@ -44,6 +44,9 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_ISLAND_STATE_JSON_INVALID',
   'X_TEST_ISLAND_STATE_CLOCK_INVALID',
   'X_TEST_ISLAND_STATE_STUB_INVALID',
+  'X_TEST_POLICY_EXPECTED',
+  'X_TEST_OPENAPI_EXPECTED',
+  'X_TEST_NUMBER_EXPECTED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -79,6 +82,9 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_ISLAND_STATE_JSON_INVALID: 'an island state carries a value JSON does not',
   X_TEST_ISLAND_STATE_CLOCK_INVALID: 'an island state manifest pins a clock that is not pinnable',
   X_TEST_ISLAND_STATE_STUB_INVALID: 'an island route stub is not "<METHOD> <pathname>"',
+  X_TEST_POLICY_EXPECTED: 'a matcher expected a policy and got something else',
+  X_TEST_OPENAPI_EXPECTED: 'a matcher expected an OpenAPI document and got something else',
+  X_TEST_NUMBER_EXPECTED: 'a matcher expected a finite number and got something else',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/fixture-subscribe.ts

@@ -9,11 +9,11 @@
 
 import type { Actor } from '@ultimat3/core';
 import { UltimateError } from '@ultimat3/core';
+import type { LiveReplicator } from '@ultimat3/realtime/server';
+import { startLiveReplicator } from '@ultimat3/realtime/server';
 import type { LiveFeed, LiveFeedPatch, LiveTarget } from './fixture-drivers';
 import type { LiveConnection, LiveNodeHandle } from './live-node';
 import { createLiveNode } from './live-node';
-import type { LiveReplicator } from './live-replicator';
-import { startLiveReplicator } from './live-replicator';
 
 interface Row {
   readonly id: string;

package/src/index.ts

@@ -23,6 +23,44 @@ export {
 // `test` is OURS (fixture-injecting); everything else passes through. Re-exported so an app
 // test has one import line, and so `expect` carries this package's matchers already installed.
 export { afterAll, afterEach, beforeAll, beforeEach, describe, expect } from 'bun:test';
+// The browser-backed e2e driver and the raw-CDP browser under it — moved here from
+// `@ultimat3/cli` in 22.0.0. `installE2eDriver` is the ONE entry point an app's test preload calls;
+// `openE2eBrowserIfAvailable()` answers `undefined` on a machine with no Chrome, so a
+// browser-backed suite SKIPS rather than turning a gate red. RAW CDP over Bun's own `WebSocket`:
+// no dependency, and no `@ultimat3/scraping` / `puppeteer-core` behind it.
+export type { E2eBrowser, OpenE2eBrowserOptions } from './cdp-browser';
+export {
+  DEFAULT_CDP_TIMEOUT_MS,
+  openE2eBrowser,
+  openE2eBrowserIfAvailable,
+} from './cdp-browser';
+export type {
+  CdpConnection,
+  CdpConnectionOptions,
+  CdpEventListener,
+  CdpResult,
+  CdpTransport,
+} from './cdp-connection';
+export { cdpConnect, cdpConnectOver } from './cdp-connection';
+export type { CdpE2eTabOptions, E2eTab } from './cdp-e2e-page';
+export { cdpE2eTab } from './cdp-e2e-page';
+export type { CdpE2eSessionOptions, E2eSession } from './cdp-e2e-session';
+export { cdpE2eSession } from './cdp-e2e-session';
+export {
+  CdpBrowserMissingError,
+  CdpCallFailedError,
+  CdpLaunchFailedError,
+  CdpTimeoutError,
+} from './cdp-errors';
+export type { LaunchedBrowser, LaunchOptions } from './cdp-launch';
+export {
+  CHROME_CANDIDATES,
+  CHROME_PATH_ENV,
+  CONTAINER_CHROME_ARGS,
+  findChrome,
+  launchChrome,
+  launchFoundChrome,
+} from './cdp-launch';
 // The island-state vocabulary. Pure data by design: a `*.island.states.ts` file is read by the
 // command that photographs the states, by the harness page and by a guard test — none of which has
 // a bundler, and only one of which has a browser.
@@ -47,6 +85,36 @@ export {
   seededUuid,
   setFrozenClock,
 } from './determinism';
+export type { E2eApp, E2eAppMode, StartE2eAppOptions } from './e2e-app';
+export { startE2eApp } from './e2e-app';
+export { E2E_ROOT_ENV, e2eApp, e2eBaseUrl, e2eBrowser } from './e2e-browser-handle';
+export type { E2eDriverOptions } from './e2e-driver';
+export { e2eFixtures, installE2eDriver } from './e2e-driver';
+export type { E2eErrorCode } from './e2e-error-codes';
+export { E2E_ERROR_CODES, E2E_ERROR_TITLES } from './e2e-error-codes';
+export {
+  E2eAppFailedError,
+  E2eEvaluateCapturedError,
+  E2eEvaluateThrewError,
+  E2eEvaluateUnsupportedError,
+  E2eLocatorAmbiguousError,
+  E2eLocatorEmptyError,
+  E2eServiceWorkerAbsentError,
+} from './e2e-errors';
+export type { EvaluablePage } from './e2e-evaluate';
+export { closureSource, evaluateClosure, evaluateExpression } from './e2e-evaluate';
+export type { LocatablePage } from './e2e-locator';
+export { e2eLocator, resetLocatorMarks } from './e2e-locator';
+export type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
+export { DEFAULT_E2E_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_TIMEOUT_MS, e2ePage } from './e2e-page';
+export type { E2eResolution, E2eSelection } from './e2e-selection';
+export {
+  MARK_ATTRIBUTE,
+  markSelector,
+  selectionCall,
+  selectionExpression,
+  unmarkExpression,
+} from './e2e-selection';
 export type { TestingErrorCode } from './errors';
 export {
   FixtureUnavailableError,
@@ -184,8 +252,6 @@ export {
 } from './island-states-resolve';
 export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-node';
 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,

package/src/island-dom.ts

@@ -332,7 +332,24 @@ export class FakeTemplate extends FakeElement {
   }
 }
 
-const VOID_TAGS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link']);
+// The whole HTML void-element set. It held six, so `<picture><source><img></picture>` parsed the
+// img INSIDE the source — a tree no browser builds, and one an island's querySelector disagrees with.
+const VOID_TAGS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
 const TOKEN =
   /<(\/?)([a-zA-Z][\w-]*)((?:\s+[^\s=/>]+(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>|([^<]+)/g;
 const ATTRIBUTE = /([^\s=/>]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;

package/src/island-observers.ts

@@ -78,8 +78,11 @@ export class FakeResizeObserver<TElement extends object = object> {
   ) {
     registry.add(this);
   }
+  /** Back INTO the registry: `disconnect()` removed it, and an island that re-observes on its next
+   *  effect must hear the next resize. `Set.add` is idempotent, so a first observe costs nothing. */
   observe(target: TElement): void {
     this.targets.add(target);
+    this.registry.add(this);
   }
   unobserve(target: TElement): void {
     this.targets.delete(target);

package/src/live-node.ts

@@ -77,11 +77,8 @@ export interface LiveNodeOptions {
   readonly buildId?: string;
   /** Pins the reconnect epoch, so a test can force a refetch by changing it. */
   readonly epoch?: string;
-  // No `onMutate`. `SyncNodeOptions` takes one — `{ socket, name, key, seq, input }`, the actor
-  // read off the socket — and nothing here needs it: the mutation half of a live subscription is
-  // the CLIENT's local store and offline queue, which this driver deliberately does not hold. A
-  // forwarded option no test passes is a declaration nothing reads, which is what 4.0.0 spent a
-  // major deleting. It arrives with its first caller, in that caller's shape.
+  // No `onMutate`: the socket carries no writes any more (plan 101, decision 2) — a mutation goes
+  // over HTTP as an action, and `createSyncNode` takes no mutation hook to forward.
 }
 
 export interface LiveNodeHandle {

package/src/matcher-receiver-errors.ts

@@ -0,0 +1,39 @@
+// Single responsibility: the refusals three matchers give a receiver of the wrong TYPE. Thrown,
+// never `pass: false` — under `.not` a `pass: false` is a pass, so `.not.toDenyPolicy` held on
+// `undefined`. Its own module because `errors.ts` sits at the size ceiling; the codes are
+// registered there, beside every other testing code.
+
+import { describeValue, UltimateError } from '@ultimat3/core';
+
+/** `toDenyPolicy` handed something with neither `run()` nor `evaluate()`. */
+export class TestPolicyExpectedError extends UltimateError {
+  constructor(received: unknown) {
+    super({
+      code: 'X_TEST_POLICY_EXPECTED',
+      cause: `toDenyPolicy expects a policy — an object with run() (@ultimat3/policy) or evaluate() — and received ${describeValue(received)}`,
+      fix: "expect(post.policy).toDenyPolicy(ctx) — pass the policy object (@ultimat3/policy's, with run() or evaluate()), never the action or its result",
+    });
+  }
+}
+
+/** `toMatchOpenApi` handed something that is not a generated document. */
+export class TestOpenApiExpectedError extends UltimateError {
+  constructor(received: unknown) {
+    super({
+      code: 'X_TEST_OPENAPI_EXPECTED',
+      cause: `toMatchOpenApi expects an OpenAPI document — an object with operations: [{ operationId, required? }] — and received ${describeValue(received)}`,
+      fix: 'expect(await app.openapi()).toMatchOpenApi(committed) — the receiver is the generated document: an object with operations: [{ operationId, required? }]',
+    });
+  }
+}
+
+/** `toBeWithinBudget` handed something that is not a finite number. */
+export class TestNumberExpectedError extends UltimateError {
+  constructor(received: unknown) {
+    super({
+      code: 'X_TEST_NUMBER_EXPECTED',
+      cause: `toBeWithinBudget expects a finite number to compare against the budget, and received ${describeValue(received)}`,
+      fix: 'expect(bytes).toBeWithinBudget(limit) — pass the measured number itself, e.g. (await Bun.file(path).arrayBuffer()).byteLength, never a Promise or a string',
+    });
+  }
+}

package/src/matchers.ts

@@ -6,6 +6,11 @@ import type { ExpectExtendMatchers } from 'bun:test';
 import { expect } from 'bun:test';
 import { describeValue, isUltimateError, renderCauseValue, stringField } from '@ultimat3/core';
 import { TestJobExpectedError, TestSchemaExpectedError } from './errors';
+import {
+  TestNumberExpectedError,
+  TestOpenApiExpectedError,
+  TestPolicyExpectedError,
+} from './matcher-receiver-errors';
 import type { MatcherResult } from './matcher-result';
 import type { UltimateMatchers } from './matcher-surface';
 import type { VisibleOptions } from './matcher-visible';
@@ -234,18 +239,19 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     return result(actual === code, () => `expected error code ${code}, received ${actual}`);
   },
 
-  async toDenyPolicy(received: unknown, context: Readonly<Record<string, unknown>>) {
-    const allowed = await decide(received, context);
-    if (allowed === undefined) {
-      return result(
-        false,
-        () => 'expected a policy — an object with run() (@ultimat3/policy) or evaluate()',
-      );
+  // Not `async` — see `assertStandardSchema`. The receiver check throws synchronously, because a
+  // `pass: false` for a non-policy is a PASS under `.not`, and `.not.toDenyPolicy` held on
+  // `undefined`. The decision itself is the promise this returns.
+  toDenyPolicy(received: unknown, context: Readonly<Record<string, unknown>>) {
+    if (!isRunnablePolicy(received) && !isPolicy(received)) {
+      throw new TestPolicyExpectedError(received);
     }
     // `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)}`);
+    return decide(received, context).then((allowed) =>
+      result(allowed === false, () => `expected the policy to deny ${renderCauseValue(context)}`),
+    );
   },
 
   // Not `async` — see `assertStandardSchema`. The guard is the synchronous prologue; the wait is
@@ -261,13 +267,8 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
   },
 
   toMatchOpenApi(received: unknown, committed: OpenApiLike) {
-    if (!isOpenApiLike(received)) {
-      return result(
-        false,
-        () =>
-          'expected an OpenAPI document — an object with operations: [{ operationId, required? }]',
-      );
-    }
+    // Thrown, never `pass: false` — which `.not` reads as a pass (`X_TEST_OPENAPI_EXPECTED`).
+    if (!isOpenApiLike(received)) throw new TestOpenApiExpectedError(received);
     const broke = breakingChanges(committed, received);
     return result(
       broke.length === 0,
@@ -277,11 +278,10 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
   },
 
   toBeWithinBudget(received: unknown, limit: number) {
-    if (typeof received !== 'number') {
-      return result(
-        false,
-        () => `expected a number to compare against the budget, got ${typeof received}`,
-      );
+    // Thrown, never `pass: false` — which `.not` reads as a pass. `NaN` is refused too: every
+    // comparison with it is false, so `.not.toBeWithinBudget` held for a measurement that failed.
+    if (typeof received !== 'number' || !Number.isFinite(received)) {
+      throw new TestNumberExpectedError(received);
     }
     return result(
       received <= limit,

package/src/live-replicator.ts

@@ -1,147 +0,0 @@
-// The in-process replicator: committed row changes in, `ChangeEvent`s out, fanned into the node.
-//
-// Production decodes the write-ahead log. PGlite has no walsender and the memory driver has no log,
-// so a test process had no change source at all — which is what left the `subscribe` fixture with
-// no driver, and its five tests in `examples/dummy` asserting against a snapshot that never moved.
-//
-// WHAT IS REAL HERE, and it is everything downstream of the decoder: the matcher, the shared window,
-// the per-subscriber `visible` gate, the cursor, the frames. This substitutes for the WAL DECODER
-// and for nothing else — `@ultimat3/entity`'s `setRowObserver` reports what a repository wrote, in
-// this process, and the events are shaped exactly as `PgLogicalReplicationFeed` shapes them.
-//
-// WHAT IS NOT: a write another process made is invisible, because nothing here reads a log. That is
-// the honest bound, and it is why this is a fixture and not a `ChangeFeed` — `selectChangeFeed`
-// still decides what a real node reads, and this is never in that decision.
-//
-// `x dev` is the one boot that installs it outside a test, `As of 2026-09-05` (`@ultimat3/cli`'s
-// `dev-live-feed.ts`), and only under the EMBEDDED database: PGlite has no walsender, every role
-// runs in that one process, so the bound above holds by construction — and a real `DATABASE_URL`
-// gets the decoder instead, never both.
-
-import type { RowBulkChange, RowChange, RowObserver } from '@ultimat3/entity';
-import type { Row } from '@ultimat3/realtime';
-import type { ChangeEvent, ChangeOp, LiveQueryRegistry } from '@ultimat3/realtime/server';
-
-/** What a caller does with a change nobody could deliver. */
-export interface LiveReplicatorOptions {
-  readonly registry: LiveQueryRegistry;
-  /** Tenant column, hoisted out of the row so fanout filters without parsing it. */
-  readonly tenantColumn?: string;
-  readonly onError?: (error: unknown) => void;
-}
-
-export interface LiveReplicator {
-  /** Resolves when every change observed so far has been fanned out. Never a sleep. */
-  settled(): Promise<void>;
-  /** Changes this replicator has delivered — the number a test asserts a patch count against. */
-  readonly delivered: number;
-  stop(): void;
-}
-
-const OPS: Readonly<Record<RowChange['op'], ChangeOp>> = {
-  insert: 'insert',
-  update: 'update',
-  delete: 'delete',
-};
-
-/**
- * A `ChangeEvent` row is `Row` — a JSON object carrying an `id`. Every row a repository stores has
- * one; the cast is what says so to a compiler that only sees `Record<string, unknown>`, and a row
- * that genuinely has none fails downstream in `idOf`, with the entity named, exactly as a row off
- * the wire would.
- */
-const asRow = (value: Readonly<Record<string, unknown>> | null): Row | null =>
-  value === null ? null : (value as unknown as Row);
-
-/**
- * Lexicographically comparable, which is the whole contract of an lsn — `formatLsn` in
- * `@ultimat3/realtime` produces the same shape from a real WAL position. A counter is enough here
- * because one process observes its own writes in the order it made them.
- */
-const lsnOf = (position: number): string => position.toString(16).padStart(16, '0');
-
-/**
- * Install the replicator for the length of one test. It takes over the process row observer and
- * hands back whatever was installed before, because `bun test` shares one process across files and
- * an unconditional clear would take an outer harness's observer with it.
- */
-export async function startLiveReplicator(options: LiveReplicatorOptions): Promise<LiveReplicator> {
-  // Awaited BEFORE the observer exists, so installation is the last thing this function does and
-  // no write between the call and the install can slip past unobserved.
-  const entity = await import('@ultimat3/entity');
-  const { registry } = options;
-  const tenant = options.tenantColumn ?? 'orgId';
-  let position = 0;
-  let delivered = 0;
-  // One promise chain, because ORDERING is the guarantee the whole pipeline is built on — the same
-  // reason `InMemoryChangeFeed` serializes its deliveries rather than firing them concurrently.
-  let tail: Promise<void> = Promise.resolve();
-  let stopped = false;
-
-  const enqueue = (work: () => Promise<void>): void => {
-    tail = tail.then(work).catch((error: unknown) => {
-      // Never rethrown into the chain: one failed fanout must not silence every change behind it,
-      // and a rejection with nobody to hand it to ends the Bun process.
-      options.onError?.(error);
-    });
-  };
-
-  const observer: RowObserver = {
-    onChange(change: RowChange): void {
-      if (stopped) return;
-      position += 1;
-      const at = position;
-      const row = change.after ?? change.before;
-      const orgId = typeof row?.[tenant] === 'string' ? (row[tenant] as string) : null;
-      const event: ChangeEvent = {
-        entity: change.entity,
-        op: OPS[change.op],
-        before: asRow(change.before),
-        after: asRow(change.after),
-        lsn: lsnOf(at),
-        txid: String(at),
-        orgId,
-        // Deliberately not a clock read: the preload freezes `Date.now()`, and a change's commit
-        // time is not something any assertion in this repo reads. `at` keeps it monotonic anyway.
-        at,
-      };
-      enqueue(async () => {
-        delivered += await registry.deliver(event);
-      });
-    },
-
-    /**
-     * A filtered write names rows this seam never saw, so there is no event to shape. Every window
-     * on the node is marked stale instead and re-read on the next change — `invalidate()` is the
-     * node's own answer to "the change stream skipped something", used here for the one write that
-     * genuinely does. Silence would be the alternative, and a subscriber told nothing happened
-     * diverges with nobody ever asking again.
-     */
-    onBulk(_change: RowBulkChange): void {
-      if (stopped) return;
-      registry.invalidate();
-    },
-  };
-
-  const previous = entity.setRowObserver(observer);
-
-  return {
-    get delivered() {
-      return delivered;
-    },
-    settled: async () => {
-      // Twice: a fanout can enqueue nothing, but the writes that produced these changes may still
-      // be resolving their own promises when a test asks. Awaiting the chain, letting the
-      // microtask queue drain, then awaiting it again covers a change observed in between.
-      await tail;
-      for (let turn = 0; turn < 8; turn += 1) await Promise.resolve();
-      await tail;
-    },
-    stop: () => {
-      stopped = true;
-      // Restored, never cleared: one process runs every test file, and an outer harness's observer
-      // must survive an inner fixture finishing.
-      entity.setRowObserver(previous);
-    },
-  };
-}