@specific.dev/spectest 0.14.0 → 0.16.0

package/src/daemon.ts

@@ -34,8 +34,8 @@ import {
   proxy as makeProxyDecl,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
-import { openBrowser } from "./browser.js";
-import { openMobile, isMobileApp } from "./mobile.js";
+import { acquirePersistentBrowser } from "./browser.js";
+import { isMobileApp, openPersistentMobile } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
 import {
@@ -1478,6 +1478,88 @@ const HOP_BY_HOP_HEADERS = new Set([
   "host",
 ]);
 
+/**
+ * Is this a CORS preflight? A preflight is the browser's own probe (never
+ * app business logic): an `OPTIONS` carrying `Origin` +
+ * `Access-Control-Request-Method`. Plain `OPTIONS` calls (no `ACRM`) are real
+ * app requests and pass straight through to the upstream/fake.
+ */
+function isCorsPreflight(req: Request): boolean {
+  return (
+    req.method === "OPTIONS" &&
+    req.headers.has("origin") &&
+    req.headers.has("access-control-request-method")
+  );
+}
+
+/**
+ * Answer a CORS preflight at the ingress, permissively, reflecting exactly
+ * what the browser asked for.
+ *
+ * Why this belongs in the platform, not the app: inside the hermetic sandbox
+ * the app page's origin (e.g. `http://<svc>.internal:<port>`) and every host
+ * it fetches through this ingress (`https://api.example.com`) are *always*
+ * different origins, so any request with a non-safelisted header — which
+ * includes `Authorization`, and crucially `Cache-Control` / `Pragma` — is
+ * preflighted by the browser. If we forward the `OPTIONS` to the upstream, the
+ * request succeeds or fails on whether *that* app happens to enumerate the
+ * header in its `Access-Control-Allow-Headers`. Real apps list `Authorization`
+ * but almost never `Cache-Control`/`Pragma`, so a client that sends those (many
+ * HTTP libraries add `Cache-Control: no-cache` by default) fails the preflight
+ * with an instant "Failed to fetch" — even though the identical request works
+ * in production behind a permissive edge/gateway. Reflecting
+ * `Access-Control-Request-Headers` verbatim makes the ingress transparent to
+ * whatever header vocabulary the app under test uses.
+ */
+function corsPreflightResponse(req: Request): Response {
+  const origin = req.headers.get("origin") ?? "*";
+  const reqHeaders = req.headers.get("access-control-request-headers");
+  const reqMethod = req.headers.get("access-control-request-method");
+  const headers = new Headers();
+  headers.set("access-control-allow-origin", origin);
+  // Echo the specific origin (not `*`) so credentialed requests are allowed;
+  // `Allow-Origin: *` + `Allow-Credentials: true` is a spec violation browsers
+  // reject.
+  headers.set("access-control-allow-credentials", "true");
+  headers.set(
+    "access-control-allow-methods",
+    reqMethod && reqMethod.length > 0
+      ? reqMethod
+      : "GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS",
+  );
+  headers.set(
+    "access-control-allow-headers",
+    reqHeaders && reqHeaders.length > 0 ? reqHeaders : "*",
+  );
+  headers.set("access-control-max-age", "600");
+  // The response varies by the reflected origin/headers — keep caches honest.
+  headers.append("vary", "Origin");
+  headers.append("vary", "Access-Control-Request-Headers");
+  return new Response(null, { status: 204, headers });
+}
+
+/**
+ * Make sure the browser sees an `Access-Control-Allow-Origin` it accepts on the
+ * *actual* cross-origin response. Only fills one in when the upstream/fake
+ * didn't set its own, so an app that manages CORS itself keeps full control;
+ * this just stops a missing header from turning an otherwise-fine 200 into a
+ * "Failed to fetch". No-op for same-origin requests (no `Origin`).
+ */
+function augmentCorsResponse(req: Request, res: Response): Response {
+  const origin = req.headers.get("origin");
+  if (!origin) return res;
+  if (res.headers.has("access-control-allow-origin")) return res;
+  try {
+    res.headers.set("access-control-allow-origin", origin);
+    res.headers.set("access-control-allow-credentials", "true");
+    res.headers.append("vary", "Origin");
+  } catch {
+    // Some responses (e.g. a 101 upgrade stub) carry guarded/immutable
+    // headers — leave those untouched.
+  }
+  return res;
+}
+
 /**
  * Bring ingress servers up: bind one Bun.serve per unique HTTP port
  * (fakes' ports plus the always-on :80 for service proxies), plus a
@@ -1865,9 +1947,15 @@ async function dispatchIngress(
       { status: 404, headers: { "content-type": "text/plain" } },
     );
   }
+  // Answer CORS preflights at the ingress (see corsPreflightResponse) so a
+  // cross-origin browser request carrying any header — Authorization,
+  // Cache-Control, Pragma, … — isn't rejected by whatever the upstream happens
+  // to list in Access-Control-Allow-Headers.
+  if (isCorsPreflight(req)) return corsPreflightResponse(req);
   if (route.kind === "fake") {
     try {
-      return await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
+      const res = await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
+      return augmentCorsResponse(req, res);
     } catch (err) {
       const e = err as Error;
       return new Response(
@@ -1876,7 +1964,15 @@ async function dispatchIngress(
       );
     }
   }
-  return proxyToService(req, server, route.service, route.port, listenerLabel, proto);
+  const res = await proxyToService(
+    req,
+    server,
+    route.service,
+    route.port,
+    listenerLabel,
+    proto,
+  );
+  return augmentCorsResponse(req, res);
 }
 
 /**
@@ -2574,6 +2670,13 @@ async function bootstrap(): Promise<BootstrapTimings> {
   // browser.ts:213 (the long-standing intermittent NAME_NOT_RESOLVED) and
   // the clocksource-regression notes. Re-enabling requires fixing the
   // restored-renderer DNS state, not just re-adding the prewarm call.
+  // NOTE: persistent sessions (ctx.browser/ctx.mobile keep one live view
+  // across tests, so restored forks navigate on a pre-snapshot renderer
+  // routinely) hit the same bug head-on; browser.ts handles it there by
+  // rebuilding the view in the same Chrome and retrying the navigation
+  // (`rebuildView`) — profile state survives, so auth carries over. That
+  // recovery is scoped to inherited-navigation failures and does NOT make
+  // the about:blank prewarm pool safe to re-enable.
 
   const result: BootstrapTimings = {
     totalMs: Date.now() - bootStart,
@@ -3645,22 +3748,49 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   const parentId = testCase.dependsOn?.id;
   const parent = parentId !== undefined ? TEST_DATA.get(parentId) : undefined;
 
-  // Track every Browser opened during this test so we can close them in
-  // `finally` — leaked Chromium subprocesses would survive the snapshot
-  // and chew memory across forks. Each Browser also gets a session
-  // recorder; the records flow back to the control plane as part of
-  // RunResult.browserSessions and are archived to S3 as the case's
-  // replay bundle.
-  // Tracks both Browser and Mobile handles for cleanup — both expose an
-  // async close() that does the final rrweb drain before teardown.
-  const openBrowsers: Array<{ close(): Promise<void> }> = [];
+  // Browser/mobile sessions are PERSISTENT: `ctx.browser()` acquires THE
+  // shared desktop browser and `ctx.mobile(app)` the one session for that
+  // app (browser.ts's module-scoped registry, which forks with the
+  // snapshot like fake state). At test end we DETACH — final rrweb drain,
+  // stop writing to this test's recorder — but deliberately keep the
+  // Chromium alive so the post-test snapshot captures it and dependsOn
+  // children resume the live page (cookies, localStorage, signed-in SPA
+  // state) instead of re-navigating. Each test still gets its own session
+  // record (attach re-arms rrweb with a fresh full snapshot, so replays
+  // stay per-case self-contained); records flow back to the control plane
+  // on RunResult.browserSessions and are archived to S3 as the case's
+  // replay bundle. Within one test repeated ctx.browser()/ctx.mobile(app)
+  // calls return the same handle (memoized below) so one test = one
+  // session per device. An explicit `.close()` destroys the shared
+  // instance — the memo is cleared so a later call starts fresh.
+  const browserDetaches: Array<() => Promise<void>> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
+  let sharedBrowser: Browser | null = null;
+  const sharedMobiles = new Map<string, Mobile>();
   const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
+    if (sharedBrowser) return sharedBrowser;
     const session = newBrowserSession(start, testCase.id);
     sessions.push(session);
-    const b = await openBrowser({ ...(opts ?? {}), recorder: session.recorder });
-    openBrowsers.push(b);
-    return b;
+    const { browser, attached, detach } = await acquirePersistentBrowser({
+      ...(opts ?? {}),
+      recorder: session.recorder,
+    });
+    // An attached session starts mid-page (no navigate event will fire) —
+    // stamp the inherited URL so the dashboard can still label the replay.
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = browser.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = browser.close.bind(browser);
+    browser.close = async () => {
+      await innerClose();
+      if (sharedBrowser === browser) sharedBrowser = null;
+    };
+    sharedBrowser = browser;
+    return browser;
   };
   const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
     if (!isMobileApp(app)) {
@@ -3668,11 +3798,28 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
         "ctx.mobile(app): pass a mobile-app handle from ctx.svc, e.g. ctx.mobile(ctx.svc.app) for a service declared with expo().",
       );
     }
+    const existing = sharedMobiles.get(app.url);
+    if (existing) return existing;
     const session = newBrowserSession(start, testCase.id, "mobile");
     sessions.push(session);
-    const m = await openMobile({ url: app.url, recorder: session.recorder });
-    openBrowsers.push(m);
-    return m;
+    const { mobile, attached, detach } = await openPersistentMobile({
+      url: app.url,
+      recorder: session.recorder,
+    });
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = mobile.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = mobile.close.bind(mobile);
+    mobile.close = async () => {
+      await innerClose();
+      if (sharedMobiles.get(app.url) === mobile) sharedMobiles.delete(app.url);
+    };
+    sharedMobiles.set(app.url, mobile);
+    return mobile;
   };
 
   // Build convenience handles (e.g. ctx.svc.db.client) from the loaded
@@ -3740,13 +3887,14 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     (process.stdout as any).write = origStdout;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (process.stderr as any).write = origStderr;
-    // Best-effort browser cleanup. `close()` does a final rrweb drain
-    // before tearing the view down, so we must `await` it before
-    // collecting session records. Leaked Chromium subprocesses would
-    // survive the snapshot and chew memory across forks.
-    for (const b of openBrowsers) {
+    // Detach every browser/mobile session: final rrweb drain (must be
+    // awaited before collecting session records), then stop writing to
+    // this test's recorder. The Chromium itself deliberately stays alive
+    // — it's part of the state the post-test snapshot captures for
+    // dependsOn children (see the acquire comment above).
+    for (const detach of browserDetaches) {
       try {
-        await b.close();
+        await detach();
       } catch {
         /* ignore */
       }
@@ -3926,14 +4074,35 @@ async function evalCode(
   // wrapped type is honest at runtime). Restored in the `finally` below.
   const restoreFetch = installFetchWrapper();
 
-  const openBrowsers: Array<{ close(): Promise<void> }> = [];
+  // Same persistent acquire/detach as a test run (see runOne): the browser
+  // survives the eval, so successive `spectest env eval` calls continue one
+  // live session — and a snapshot taken afterwards carries it.
+  const browserDetaches: Array<() => Promise<void>> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
+  let sharedBrowser: Browser | null = null;
+  const sharedMobiles = new Map<string, Mobile>();
   const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
+    if (sharedBrowser) return sharedBrowser;
     const session = newBrowserSession(start, "eval");
     sessions.push(session);
-    const b = await openBrowser({ ...(opts ?? {}), recorder: session.recorder });
-    openBrowsers.push(b);
-    return b;
+    const { browser, attached, detach } = await acquirePersistentBrowser({
+      ...(opts ?? {}),
+      recorder: session.recorder,
+    });
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = browser.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = browser.close.bind(browser);
+    browser.close = async () => {
+      await innerClose();
+      if (sharedBrowser === browser) sharedBrowser = null;
+    };
+    sharedBrowser = browser;
+    return browser;
   };
   const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
     if (!isMobileApp(app)) {
@@ -3941,11 +4110,28 @@ async function evalCode(
         "ctx.mobile(app): pass a mobile-app handle from ctx.svc, e.g. ctx.mobile(ctx.svc.app) for a service declared with expo().",
       );
     }
+    const existing = sharedMobiles.get(app.url);
+    if (existing) return existing;
     const session = newBrowserSession(start, "eval", "mobile");
     sessions.push(session);
-    const m = await openMobile({ url: app.url, recorder: session.recorder });
-    openBrowsers.push(m);
-    return m;
+    const { mobile, attached, detach } = await openPersistentMobile({
+      url: app.url,
+      recorder: session.recorder,
+    });
+    if (attached && session.record.initialUrl === undefined) {
+      session.record.initialUrl = mobile.url;
+    }
+    browserDetaches.push(async () => {
+      await detach();
+      session.markClosed();
+    });
+    const innerClose = mobile.close.bind(mobile);
+    mobile.close = async () => {
+      await innerClose();
+      if (sharedMobiles.get(app.url) === mobile) sharedMobiles.delete(app.url);
+    };
+    sharedMobiles.set(app.url, mobile);
+    return mobile;
   };
 
   // Terminal sessions — same shape as runOne, but eval has no active
@@ -4058,9 +4244,11 @@ async function evalCode(
     (process.stdout as any).write = origStdout;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (process.stderr as any).write = origStderr;
-    for (const b of openBrowsers) {
+    // Detach (final rrweb drain) — the browser itself stays alive; see
+    // the acquire comment above.
+    for (const detach of browserDetaches) {
       try {
-        await b.close();
+        await detach();
       } catch {
         /* ignore */
       }

package/src/index.ts

@@ -1061,9 +1061,20 @@ export interface TestContext<
    */
   openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
   /**
-   * Open a headless browser. Backed by Chromium-over-CDP inside the VM.
-   * Every view is auto-closed when the test finishes; call `.close()` to
-   * release earlier if you're opening many.
+   * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
+   *
+   * There is ONE persistent browser per environment: every `ctx.browser()`
+   * call returns it, and it stays alive across tests — the browser is part
+   * of the state a test's snapshot captures, so a `dependsOn` child resumes
+   * the exact live page its parent left (cookies, localStorage, signed-in
+   * SPA state). Sign in once in a parent test; every descendant is already
+   * signed in. Sibling tests fork from the same parent snapshot, so they
+   * can't see each other's browsing. A test with no browser-using ancestor
+   * gets a fresh browser on first call (first call's options win).
+   *
+   * `.close()` destroys the shared instance — the next `ctx.browser()`
+   * starts fresh. Don't call it for routine cleanup; recording is detached
+   * automatically at test end.
    */
   browser(opts?: BrowserOptions): Promise<Browser>;
   /**
@@ -1082,8 +1093,13 @@ export interface TestContext<
    * ```
    *
    * The session emulates the latest iPhone (viewport + DPR + mobile UA +
-   * touch) and the dashboard replays it inside a phone bezel. Auto-closed
-   * when the test finishes.
+   * touch) and the dashboard replays it inside a phone bezel.
+   *
+   * Sessions are persistent, one per app: like `ctx.browser()`, the live
+   * session is captured in the test's snapshot, so a `dependsOn` child
+   * picks up the app exactly where the parent left it (already signed in,
+   * mid-flow) instead of reloading it. `.close()` discards the session;
+   * the next `ctx.mobile(app)` opens the app fresh.
    */
   mobile(app: MobileApp): Promise<Mobile>;
   /** The test's display name. */

package/src/mobile.ts

@@ -14,10 +14,11 @@
 // `accessibilityLabel` to `aria-label`, so `getByTestId`/`getByLabel` map to
 // plain DOM attribute selectors with no shimming.
 
-import { openMobileBackend } from "./browser.js";
+import { acquirePersistentMobileBackend, openMobileBackend } from "./browser.js";
 import type {
   BrowserSessionRecorder,
   MobileBackend,
+  SafeAreaInsets,
   ScreenshotOptions,
 } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
@@ -278,6 +279,14 @@ export interface Mobile {
   back(): Promise<void>;
   /** Low-level escape hatch: evaluate JS in the page (recorded, wrapped). */
   evaluate<T = unknown>(description: string, script: string): Promise<Wrapped<T>>;
+  /**
+   * Install a script that runs before every *subsequent* document's own
+   * scripts (the Playwright `addInitScript` equivalent) — the deterministic
+   * way to plant shims/instrumentation that must win the race against the
+   * app bundle. Takes effect on the next navigation (e.g. a
+   * `location.assign` deep link), not the current document.
+   */
+  addInitScript(description: string, source: string): Promise<void>;
   /** Low-level escape hatch: poll a JS expression until truthy (recorded). */
   waitFor<T = unknown>(
     description: string,
@@ -349,6 +358,9 @@ function wrapMobile(backend: MobileBackend): Mobile {
     evaluate(description, script) {
       return backend.evaluate(description, script);
     },
+    addInitScript(description, source) {
+      return backend.addInitScript(description, source);
+    },
     waitFor(description, expression, options) {
       return backend.waitFor(description, expression, options);
     },
@@ -362,9 +374,9 @@ function wrapMobile(backend: MobileBackend): Mobile {
 }
 
 /**
- * Open a phone-emulated session pointed at `url`. The daemon calls this from
- * `ctx.mobile(app)` with a per-session rrweb recorder; the resulting record
- * carries `frame: "mobile"` so the dashboard renders a phone bezel.
+ * Open an EPHEMERAL phone-emulated session pointed at `url` (`close()`
+ * destroys it). Library callers only — the daemon's `ctx.mobile(app)` goes
+ * through {@link openPersistentMobile} so sessions survive across tests.
  */
 export async function openMobile(opts: {
   url?: string;
@@ -377,3 +389,34 @@ export async function openMobile(opts: {
   });
   return wrapMobile(backend);
 }
+
+/**
+ * Acquire the persistent phone-emulated session for an app (one per app
+ * URL, created on first use — see the "Persistent sessions" section in
+ * browser.ts). The daemon calls this from `ctx.mobile(app)` with a
+ * per-test rrweb recorder; the resulting record carries `frame: "mobile"`
+ * so the dashboard renders a phone bezel. `detach` is the test-end hook;
+ * `mobile.close()` destroys the session for real.
+ */
+export async function openPersistentMobile(opts: {
+  url: string;
+  recorder: BrowserSessionRecorder | null;
+}): Promise<{
+  mobile: Mobile;
+  attached: boolean;
+  detach(): Promise<void>;
+  /** Safe-area insets emulated on the view (`null` when the CDP override
+   *  is unavailable) — the daemon stamps them onto the session record. */
+  safeAreaInsets: SafeAreaInsets | null;
+}> {
+  const { browser, attached, detach } = await acquirePersistentMobileBackend(
+    opts.url,
+    opts.recorder,
+  );
+  return {
+    mobile: wrapMobile(browser),
+    attached,
+    detach,
+    safeAreaInsets: browser.safeAreaInsets,
+  };
+}

package/src/recorder.ts

@@ -25,7 +25,8 @@ export type TestEvent =
   | TerminalStepEvent
   | WaitEvent
   | FakeEvent
-  | EnvEvent;
+  | EnvEvent
+  | EmailEvent;
 
 interface BaseEvent {
   /** Order of *start* within the test. Reserved when an op begins (see
@@ -275,6 +276,69 @@ export interface FakeEvent extends BaseEvent {
   error?: string;
 }
 
+/**
+ * One captured email, as embedded on an {@link EmailEvent}. The HTML and
+ * text bodies ride along (truncated to the output cap) so the dashboard
+ * can render the actual email a test asserted against.
+ */
+export interface EmailEventMessage {
+  /** Sender address. */
+  from?: string;
+  /** Recipient addresses. */
+  to?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject?: string;
+  /** RFC date of the message, ISO-formatted. */
+  date?: string;
+  /** HTML body (truncated to the output cap). */
+  html?: string;
+  htmlTruncated?: boolean;
+  /** Plain-text body (truncated to the output cap). */
+  text?: string;
+  textTruncated?: boolean;
+  attachments?: { filename: string; contentType: string; size: number }[];
+}
+
+/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
+export interface EmailEventSummary {
+  from?: string;
+  to?: string[];
+  subject?: string;
+  /** Plain-text preview of the body. */
+  snippet?: string;
+  date?: string;
+}
+
+/**
+ * One call to an email service's helpers (`ctx.svc.<name>.lastEmail(...)`
+ * etc.). Single-message ops embed the full captured message — including its
+ * HTML body — so timelines can render the email itself; listing ops embed
+ * compact summaries. The return value is `wrap()`ped against this event's
+ * seq, so `expect(...)` on it nests under this step (same mechanism as
+ * http/db/fake). Inside a `ctx.poll` predicate the event ride-alongs with
+ * the poll's iteration events: failed iterations get truncated, the winning
+ * one survives as a child of the `wait` event.
+ */
+export interface EmailEvent extends BaseEvent {
+  kind: "email";
+  /** Service key of the mail server (`ctx.svc.<service>`). */
+  service: string;
+  /** Helper called, e.g. `"lastEmail"`. */
+  op: string;
+  /** Human-readable match criteria, e.g. `to alice@example.com`. */
+  query?: string;
+  /** Number of matching messages (listing ops / mailbox size on error). */
+  count?: number;
+  /** The captured message (single-message ops). */
+  message?: EmailEventMessage;
+  /** Message summaries (listing ops). */
+  messages?: EmailEventSummary[];
+  durationMs: number;
+  /** Set if the op threw (e.g. the mail server's query API failed). */
+  error?: string;
+}
+
 /**
  * A runtime mutation of the environment — `ctx.startService` /
  * `ctx.stopService` / `ctx.dnsName`, whether called from a test or from a
@@ -303,6 +367,7 @@ export interface EnvEvent extends BaseEvent {
 export type BrowserAction =
   | "navigate"
   | "evaluate"
+  | "addInitScript"
   | "waitFor"
   | "click"
   | "type"
@@ -663,6 +728,13 @@ export function recordEnv(
   return active() ? current!.push({ kind: "env", ...ev }, reservation) : undefined;
 }
 
+export function recordEmail(
+  ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "email", ...ev }, reservation) : undefined;
+}
+
 /**
  * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed
  * intermediate iterations and gives downstream tagged values