@ultimat3/testing 24.0.0 → 25.0.0

package/src/registry-snapshot.ts

@@ -3,11 +3,17 @@
 // module declares at MODULE scope evaluates once per `bun test` process — a neighbour's clear is
 // permanent and there is no second evaluation left to redo it.
 //
-// FOUR registries, out of roughly nine that publish a `clear*`/`reset*`. The missing ones and what
+// SIX registries, out of roughly nine that publish a `clear*`/`reset*`. The missing ones and what
 // each still needs are tabulated in `registry-leak-guard.ts` beside `RegistrySample` — every one of
 // them needs a RESTORE in its owning package first, the way `restorePermissions` / `restoreRoles`
 // were added to `@ultimat3/policy` for the two rows below.
 
+import type { MeasurementActorFactory } from '@ultimat3/core';
+import {
+  declaredMeasurementActor,
+  defineMeasurementActor,
+  resetMeasurementActor,
+} from '@ultimat3/core';
 import type { Catalog, Locale, LocaleConfig } from '@ultimat3/i18n';
 import {
   catalogDeclarationCount,
@@ -53,6 +59,13 @@ export interface ProcessRegistrySnapshot {
   readonly tasks: readonly TaskHandle[];
   /** `defineCatalogs()` calls so far — see `@ultimat3/i18n`'s `catalogDeclarationCount`. */
   readonly catalogDeclarations: number;
+  /**
+   * `defineMeasurementActor()`'s factory, `undefined` for core's default. An `app.config.ts`
+   * declares it at module scope, so a test body that imported a tracked app's config
+   * (`buildIslands(examples/dummy)`) made every later file's `x build` measure as that app's
+   * member — and `prerender-actor.test.ts`'s policy-guarded load was denied X_FORBIDDEN.
+   */
+  readonly measurementActor: MeasurementActorFactory | undefined;
 }
 
 export function captureProcessRegistries(): ProcessRegistrySnapshot {
@@ -65,6 +78,7 @@ export function captureProcessRegistries(): ProcessRegistrySnapshot {
     roleSites: roleDeclarationSites(),
     tasks: registeredTasks(),
     catalogDeclarations: catalogDeclarationCount(),
+    measurementActor: declaredMeasurementActor(),
   };
 }
 
@@ -81,6 +95,8 @@ export function restoreProcessRegistries(snapshot: ProcessRegistrySnapshot): voi
   restorePermissions(snapshot.permissions, snapshot.permissionSites);
   restoreRoles(snapshot.roles, snapshot.roleSites);
   restoreTasks(snapshot.tasks);
+  if (snapshot.measurementActor === undefined) resetMeasurementActor();
+  else defineMeasurementActor(snapshot.measurementActor);
 }
 
 /**
@@ -147,6 +163,8 @@ export function mergeSnapshots(
     roleSites: { ...older.roleSites, ...newer.roleSites },
     tasks: [...tasks.values()],
     catalogDeclarations: Math.max(older.catalogDeclarations, newer.catalogDeclarations),
+    // Last declaration wins, as `defineMeasurementActor` itself has it; "none" never erases one.
+    measurementActor: newer.measurementActor ?? older.measurementActor,
   };
 }
 

package/src/render-view.ts

@@ -3,7 +3,7 @@
 // them. No browser, no server, no cast: a test asserts on markup and on visible text.
 
 import type { Actor } from '@ultimat3/core';
-import { assert, createContext, runWithContext } from '@ultimat3/core';
+import { assert, ctxOf, runWithContext } from '@ultimat3/core';
 import type { IslandDirective, RouteConfig, RouteParams } from '@ultimat3/render';
 
 /** What a component rendered. */
@@ -101,7 +101,7 @@ export async function renderRoute<TData>(
   );
   const url = request.url ?? DEFAULT_URL;
   const ctx = { params: request.params ?? {}, url };
-  const islands = render.createIslandCollector({ file: url, hydrate: config.hydrate });
+  const islands = render.islandCollector({ file: url, hydrate: config.hydrate });
 
   const run = async (): Promise<RenderedRoute<TData>> => {
     const data = await render.routeDataFor(config, ctx);
@@ -114,5 +114,5 @@ export async function renderRoute<TData>(
   };
 
   if (request.actor === undefined) return run();
-  return runWithContext(createContext({ actor: request.actor }), run);
+  return runWithContext(ctxOf({ actor: request.actor }), run);
 }

package/src/sealed-network.ts

@@ -1,9 +1,11 @@
 // Sealed network. Any egress a test did not explicitly mock or allow fails the test with the URL
 // and the line that fixes it. A test that quietly reaches the internet is a test that fails in CI
-// for reasons nobody can reproduce — so the default is "nothing gets out".
+// for reasons nobody can reproduce — so the default is "nothing gets out". Three dials are sealed:
+// `fetch` here, `WebSocket` and `Bun.connect` through `sealed-sockets.ts`, all behind one gate.
 
-import { isSelfOrigin } from '@ultimat3/core';
+import { classifyAddress, isSelfOrigin } from '@ultimat3/core';
 import { NetworkOfflineError, NetworkRaceError, NetworkSealedError } from './errors';
+import { installSocketSeal } from './sealed-sockets';
 
 export type FetchLike = typeof globalThis.fetch;
 
@@ -24,6 +26,8 @@ interface SealState {
   readonly mocks: MockRoute[];
   readonly seen: string[];
   original: FetchLike | undefined;
+  /** `installSocketSeal`'s undo, held beside `original` so one unseal restores all three dials. */
+  restoreSockets: (() => void) | undefined;
   network: NetworkState;
 }
 
@@ -32,6 +36,7 @@ const state: SealState = {
   mocks: [],
   seen: [],
   original: undefined,
+  restoreSockets: undefined,
   network: 'online',
 };
 
@@ -57,10 +62,44 @@ const methodOf = (input: RequestInfo | URL, init: RequestInit | undefined): stri
   return 'GET';
 };
 
-/** Replace global fetch. Idempotent: sealing twice keeps the one original around. */
+/**
+ * A raw socket to THIS machine is not egress, whichever port: it is how a test reaches the
+ * scripted server it `Bun.listen`ed and the compose services the live suites run against, none of
+ * which announce through `markListening`. What fails unreproducibly in CI is the internet, and a
+ * loopback dial with nothing behind it fails the same way on every machine.
+ */
+const isThisMachine = (hostname: string): boolean => {
+  if (hostname.toLowerCase() === 'localhost') return true;
+  const kind = classifyAddress(hostname);
+  return kind === 'loopback' || kind === 'unspecified';
+};
+
+/** The socket dials' gate: the same allow-list, offline state and record as `fetch`. No mocks — a
+ *  socket test injects its transport (`connect`, `client`), it does not intercept the dial. */
+const socketRefusal = (url: string, method: string): Error | undefined => {
+  state.seen.push(url);
+  let target: URL;
+  try {
+    target = new URL(url);
+  } catch {
+    return undefined; // Not a URL: the real constructor refuses it with its own SyntaxError.
+  }
+  // Offline before loopback, the order `fetch` checks in: offline cuts EVERY dial, this machine's
+  // included, or a socket would reach a host the same test's `fetch` is refused.
+  if (state.network !== 'online') {
+    return new NetworkOfflineError({ url, method, mode: state.network });
+  }
+  if (isThisMachine(target.hostname)) return undefined;
+  if (state.allowed.has(target.host)) return undefined;
+  return new NetworkSealedError({ url, method, allowed: [...state.allowed], transport: 'socket' });
+};
+
+/** Replace global fetch, `WebSocket` and `Bun.connect`. Idempotent: sealing twice keeps the one
+ *  set of originals around. */
 export function sealNetwork(): void {
   if (state.original !== undefined) return;
   state.original = globalThis.fetch;
+  state.restoreSockets = installSocketSeal(socketRefusal);
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
     const url = urlOf(input);
     state.seen.push(url);
@@ -98,13 +137,15 @@ export function unsealNetwork(): void {
   if (state.original === undefined) return;
   globalThis.fetch = state.original;
   state.original = undefined;
+  state.restoreSockets?.();
+  state.restoreSockets = undefined;
 }
 
 /** Whether the patch is installed. The `network` fixture seals before going offline, so that
  *  `offline()` has teeth in a process that deliberately unsealed (`ULTIMATE_TEST_ALLOW_NET=1`). */
 export const isNetworkSealed = (): boolean => state.original !== undefined;
 
-/** The one writer of the offline gate — `createTestNetwork()`. Never call it from a test body. */
+/** The one writer of the offline gate — `testNetwork()`. Never call it from a test body. */
 export function setNetworkState(next: NetworkState): void {
   state.network = next;
 }

package/src/sealed-sockets.ts

@@ -0,0 +1,59 @@
+// The socket half of the sealed network: `WebSocket` and `Bun.connect`, the two dials that are not
+// `fetch`. Only the patching lives here; WHETHER a dial may leave is `sealed-network.ts`'s one
+// gate, handed in, so fetch and sockets cannot disagree about the allow-list or the offline state.
+
+/** A dial's verdict: the error to raise, or `undefined` to let it through to the real one. */
+export type SocketGate = (url: string, method: 'WEBSOCKET' | 'CONNECT') => Error | undefined;
+
+/** `Bun.connect`'s two option shapes, read structurally: TCP names a host, a unix socket a path. */
+interface ConnectOptions {
+  readonly hostname?: string;
+  readonly port?: number;
+  readonly unix?: string;
+}
+
+type Connect = (options: ConnectOptions) => Promise<unknown>;
+
+/** A dial target as a URL, so the gate parses one shape. IPv6 literals need their brackets. */
+const tcpUrl = (hostname: string, port: number | undefined): string => {
+  const host = hostname.includes(':') && !hostname.startsWith('[') ? `[${hostname}]` : hostname;
+  return `tcp://${host}:${port ?? 0}`;
+};
+
+/**
+ * Patch both dials and return the uninstaller, which puts back exactly what was there — the same
+ * originals, so `globalThis.WebSocket === original` holds again. Assigned through `Reflect.set`:
+ * `Bun.connect` is a writable data property, but the type declares it a namespace function.
+ */
+export function installSocketSeal(gate: SocketGate): () => void {
+  const OriginalWebSocket = globalThis.WebSocket;
+  const originalConnect = Reflect.get(Bun, 'connect') as Connect;
+
+  // A subclass, not a wrapper function: `instanceof WebSocket`, the static `OPEN`/`CLOSED` and
+  // every option a caller passes keep working. Code before `super()` may not touch `this`, and
+  // does not — the refusal is thrown before the native constructor ever dials.
+  class SealedWebSocket extends OriginalWebSocket {
+    constructor(url: string | URL, protocols?: string | string[]) {
+      const refusal = gate(String(url), 'WEBSOCKET');
+      if (refusal !== undefined) throw refusal;
+      super(url, protocols);
+    }
+  }
+
+  // A promise either way, as the real `Bun.connect` answers a dial it cannot make. A unix socket is
+  // a path on this machine and is never egress.
+  const sealedConnect: Connect = (options) => {
+    if (options.unix === undefined && options.hostname !== undefined) {
+      const refusal = gate(tcpUrl(options.hostname, options.port), 'CONNECT');
+      if (refusal !== undefined) return Promise.reject(refusal);
+    }
+    return originalConnect(options);
+  };
+
+  Reflect.set(globalThis, 'WebSocket', SealedWebSocket);
+  Reflect.set(Bun, 'connect', sealedConnect);
+  return () => {
+    Reflect.set(globalThis, 'WebSocket', OriginalWebSocket);
+    Reflect.set(Bun, 'connect', originalConnect);
+  };
+}

package/src/template-db.ts

@@ -65,7 +65,7 @@ export function urlFor(adminUrl: string, database: string): string {
   return url.toString();
 }
 
-export const createTemplateSql = (template: string): string =>
+export const templateSql = (template: string): string =>
   `CREATE DATABASE "${template}" TEMPLATE template0`;
 
 export const cloneSql = (template: string, target: string): string =>
@@ -132,7 +132,7 @@ export async function acquireWorkerDatabase(
     await admin.exec(lockSql(template));
     try {
       try {
-        await admin.exec(createTemplateSql(template));
+        await admin.exec(templateSql(template));
       } catch (error) {
         // Tolerated for the CREATE alone: "already exists" means another worker got here first, or
         // a Postgres that outlives one run still holds last run's template.

package/src/test-types.ts

@@ -79,8 +79,12 @@ export interface PageLike {
   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>;
+  /**
+   * Resolves once the service worker controls the page, so the offline assertions are not racy. A
+   * page the worker cannot claim — the first of a run, committed before it activated — is reloaded
+   * once (that navigation IS answered by the worker). `timeoutMs` raises this call's budget.
+   */
+  waitForServiceWorker(options?: { readonly timeoutMs?: number | undefined }): Promise<void>;
   /** Called only by `x g route`'s generated e2e template — no driver runs it yet. */
   title(): Promise<string>;
   url(): string;