@ultimat3/testing 26.0.0 → 26.1.0

package/README.md

@@ -92,6 +92,7 @@ with `{ runJobs }` — never `describe(testName('unit', …))` around a bare `te
 | `clock` | `now()` · `advance('3d')` · `set(instant)` on the frozen clock | the preload |
 | `mail` | `outbox()` · `lastTo(address)` · `failOnce(mail)` over an in-memory transport | the preload |
 | `network` | `offline()` · `drop()` · `online()` · `state()` over the sealed network | the preload |
+| `push` | a Web Push runtime with the push service and the device played in-process: `subscribe(actorId, { locale })` gives that person a browser, `sent()` is what each device would SHOW (decrypted with its own key), `answerOnce(410 \| 429 \| …)` scripts the push service | the preload |
 | `runJobs` | a worker: call it to enqueue+drain, then `enqueue()` `drain()` `due()` `inFlight()` `depth()` — see [below](#a-job-under-runjobs) | the preload |
 | `statements` | every statement the test issued: `all()` `count(fingerprint?)` `shapes()` — and an N+1 throws | the preload |
 | `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker({ timeoutMs? })` — an uncontrolled first page is reloaded once for its worker (`e2e-service-worker.ts`) | a browser driver |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "26.0.0",
+  "version": "26.1.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -36,19 +36,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "26.0.0",
-    "@ultimat3/cache": "26.0.0",
-    "@ultimat3/core": "26.0.0",
-    "@ultimat3/db": "26.0.0",
-    "@ultimat3/entity": "26.0.0",
-    "@ultimat3/http": "26.0.0",
-    "@ultimat3/i18n": "26.0.0",
-    "@ultimat3/jobs": "26.0.0",
-    "@ultimat3/mail": "26.0.0",
-    "@ultimat3/policy": "26.0.0",
-    "@ultimat3/query": "26.0.0",
-    "@ultimat3/realtime": "26.0.0",
-    "@ultimat3/render": "26.0.0",
-    "@ultimat3/time": "26.0.0"
+    "@ultimat3/action": "26.1.0",
+    "@ultimat3/cache": "26.1.0",
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/db": "26.1.0",
+    "@ultimat3/entity": "26.1.0",
+    "@ultimat3/http": "26.1.0",
+    "@ultimat3/i18n": "26.1.0",
+    "@ultimat3/jobs": "26.1.0",
+    "@ultimat3/mail": "26.1.0",
+    "@ultimat3/policy": "26.1.0",
+    "@ultimat3/pwa": "26.1.0",
+    "@ultimat3/query": "26.1.0",
+    "@ultimat3/realtime": "26.1.0",
+    "@ultimat3/render": "26.1.0",
+    "@ultimat3/time": "26.1.0"
   }
 }

package/src/fixture-push.ts

@@ -0,0 +1,113 @@
+// The `push` fixture: a Web Push runtime for one test, with the push service AND the device played
+// in-process. `push.subscribe(actorId)` gives that person a browser — a real P-256 key and auth
+// secret, as `PushSubscription.toJSON()` carries — and `push.sent()` is what each device would SHOW:
+// every delivery decrypted with that browser's own key, so a test asserts the notification, not
+// the bytes. Nothing reaches the network.
+
+import type { PushReceiverKeys } from '@ultimat3/pwa';
+import { frozenNow } from './determinism';
+
+/** One delivery, as the device received it. */
+export interface TestPushMessage {
+  readonly actorId: string;
+  readonly endpoint: string;
+  /** The push service's request headers: `ttl`, `urgency`, `topic`, `authorization`. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** The notification the worker would show — `serializePushMessage`'s fields, decrypted. */
+  readonly notification: Readonly<Record<string, unknown>>;
+}
+
+/** `Disposable`: the fixture installs the process's push runtime and releases it after the test. */
+export interface TestPush extends Disposable {
+  /** A browser for `actorId`, subscribed in `locale` (default `en`); answers its endpoint. */
+  subscribe(
+    actorId: string,
+    options?: { readonly locale?: string; readonly timeZone?: string },
+  ): Promise<string>;
+  /** Oldest first. */
+  sent(): readonly TestPushMessage[];
+  /** The push service answers the next request `status`: 410 deletes it, 429 makes the job retry. */
+  answerOnce(status: number): void;
+  clear(): void;
+}
+
+const PUSH_SERVICE = 'https://push.test';
+
+export async function testPush(): Promise<TestPush> {
+  const pwa = await import('@ultimat3/pwa');
+  const store = pwa.memoryPushSubscriptionStore();
+  const devices = new Map<string, { readonly actorId: string; readonly keys: PushReceiverKeys }>();
+  const sent: TestPushMessage[] = [];
+  const answers: number[] = [];
+  let counter = 0;
+
+  const pushService = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request = new Request(input, init);
+    const answer = answers.shift() ?? 201;
+    const device = devices.get(request.url);
+    if (answer >= 200 && answer < 300 && device !== undefined) {
+      const body = new Uint8Array(await request.arrayBuffer());
+      const plain = await pwa.decryptPushMessage(body, device.keys);
+      sent.push({
+        actorId: device.actorId,
+        endpoint: request.url,
+        headers: Object.fromEntries(request.headers.entries()),
+        notification: JSON.parse(new TextDecoder().decode(plain)) as Record<string, unknown>,
+      });
+    }
+    return new Response(null, { status: answer });
+  }) as typeof fetch;
+
+  const release = await pwa.installWebPush({
+    store,
+    keys: pwa.DEV_VAPID_KEYS,
+    subject: 'mailto:push@example.test',
+    fetch: pushService,
+    // The stub push service's host: not a real one, so the app's list names it, as an app would.
+    pushHosts: [new URL(PUSH_SERVICE).hostname],
+    // The clock the `clock` fixture moves — never the wall clock: a VAPID token's `exp` and a
+    // subscription's `expirationTime` are read against it, so `clock.advance('2d')` reaches both.
+    clock: { now: frozenNow, monotonic: () => frozenNow().getTime() },
+  });
+
+  return {
+    async subscribe(actorId, options) {
+      counter += 1;
+      const pair = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+        'deriveBits',
+      ]);
+      const publicKey = new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey));
+      // why: a browser rolls its auth secret; this stands in for one, and pins nothing a test reads.
+      const authSecret = crypto.getRandomValues(new Uint8Array(16));
+      const endpoint = `${PUSH_SERVICE}/device/${counter}`;
+      devices.set(endpoint, {
+        actorId,
+        keys: { privateKey: pair.privateKey, publicKey, authSecret },
+      });
+      const base64url = (bytes: Uint8Array): string =>
+        btoa(String.fromCharCode(...bytes))
+          .replaceAll('+', '-')
+          .replaceAll('/', '_')
+          .replaceAll('=', '');
+      await store.save({
+        endpoint,
+        keys: { p256dh: base64url(publicKey), auth: base64url(authSecret) },
+        locale: options?.locale ?? 'en',
+        timeZone: options?.timeZone ?? 'UTC',
+        actorId,
+        createdAt: 0,
+        expirationTime: null,
+      });
+      return endpoint;
+    },
+    sent: () => [...sent],
+    answerOnce: (status) => {
+      answers.push(status);
+    },
+    clear: () => {
+      sent.length = 0;
+      answers.length = 0;
+    },
+    [Symbol.dispose]: release,
+  };
+}

package/src/fixtures.ts

@@ -16,6 +16,7 @@ import type { SignIn, Subscribe, TestBudget, TestDeploy } from './fixture-driver
 import type { RunJobs } from './fixture-jobs';
 import type { TestMail } from './fixture-mail';
 import type { TestNetwork } from './fixture-network';
+import type { TestPush } from './fixture-push';
 import type { TestStatements } from './fixture-statements';
 import type { PageLike, TestOptions } from './test-types';
 
@@ -45,6 +46,7 @@ export interface Fixtures {
   readonly clock: TestClock;
   readonly mail: TestMail;
   readonly network: TestNetwork;
+  readonly push: TestPush;
   readonly runJobs: RunJobs;
   readonly statements: TestStatements;
   readonly budget: TestBudget;

package/src/framework-fixtures.ts

@@ -7,6 +7,7 @@ import { DRIVER_FIXTURE_NAMES, driverFixtures } from './fixture-drivers';
 import { testJobs } from './fixture-jobs';
 import { testMail } from './fixture-mail';
 import { testNetwork } from './fixture-network';
+import { testPush } from './fixture-push';
 import { testStatements } from './fixture-statements';
 import { subscribeDriver } from './fixture-subscribe';
 import { defineFixtures } from './fixtures';
@@ -21,6 +22,8 @@ export const FRAMEWORK_FIXTURE_NAMES = [
   'clock',
   'mail',
   'network',
+  // 2026-10-08: the Web Push runtime, with the push service and the device played in-process.
+  'push',
   'runJobs',
   'statements',
   // Moved here from `DRIVER_FIXTURE_NAMES` on 2026-08-20: the driver it was waiting for is
@@ -51,6 +54,7 @@ export function registerFrameworkFixtures(): void {
     clock: testClock,
     mail: testMail,
     network: testNetwork,
+    push: testPush,
     runJobs: testJobs,
     statements: testStatements,
     // After the spread, so it REPLACES the `unavailableFixture('subscribe')` declaration above it —

package/src/index.ts

@@ -202,6 +202,8 @@ export type { MailRef, TestMail } from './fixture-mail';
 export { testMail } from './fixture-mail';
 export type { TestNetwork } from './fixture-network';
 export { testNetwork } from './fixture-network';
+export type { TestPush, TestPushMessage } from './fixture-push';
+export { testPush } from './fixture-push';
 export type { ObservedStatement, StatementShape, TestStatements } from './fixture-statements';
 export { testStatements } from './fixture-statements';
 export type { SubscribeDriver } from './fixture-subscribe';