@specific.dev/spectest 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/browser.ts

@@ -16,7 +16,14 @@
 // Headless-Linux specifics live here: we force the chrome backend, add
 // `--no-sandbox` (Chrome refuses to run as root otherwise) and
 // `--disable-dev-shm-usage` (Firecracker's /dev/shm is tiny).
+//
+// Sessions are PERSISTENT by default: `ctx.browser()` always hands back the
+// one shared desktop browser and `ctx.mobile(app)` the one session for that
+// app, kept alive across tests so snapshots capture the live Chromium and
+// dependsOn children resume exactly where the parent left off (signed-in
+// SPA state included). See the "Persistent sessions" section below.
 
+import { promises as dns } from "node:dns";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -205,7 +212,15 @@ export interface Browser {
   reload(): Promise<void>;
   /** Capture a PNG/JPEG/WebP screenshot of the viewport. Returns raw bytes. */
   screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
-  /** Close the underlying view. Idempotent. Drains any pending rrweb events. */
+  /**
+   * Destroy the underlying view. Idempotent; drains any pending rrweb
+   * events first. For the persistent session behind `ctx.browser()` /
+   * `ctx.mobile()` this is the escape hatch to a FRESH browser — the
+   * shared instance is discarded and the next call creates a new one.
+   * Don't call it for routine cleanup: the daemon detaches recording at
+   * test end automatically and deliberately keeps the browser alive so
+   * dependent tests inherit its state.
+   */
   close(): Promise<void>;
 }
 
@@ -603,6 +618,22 @@ interface PooledView {
   recordingInstalled: boolean;
 }
 
+/**
+ * The unit a Browser/Mobile handle drives. `view` is deliberately mutable:
+ * the DNS-recovery path (see `navigate` in {@link buildBackend}) replaces a
+ * broken restored renderer with a freshly-spawned view in the same Chrome,
+ * and every wrapper reads through the holder so the swap is transparent.
+ * `device`/`width`/`height` are kept so a rebuilt view comes back with the
+ * same viewport and emulation.
+ */
+interface ViewHolder {
+  view: BunWebViewInstance;
+  recordingInstalled: boolean;
+  device: DevicePreset | null;
+  width: number;
+  height: number;
+}
+
 // Pre-opened view pool. Renderer spawn is the expensive part of
 // `ctx.browser()` — ~1.8s for the first view in a fresh Chrome and
 // (measured 2026-06-05) a constant ~1.2-1.5s per view in a Chrome that
@@ -659,6 +690,11 @@ export async function prewarmViewPool(n = 1): Promise<void> {
  * Open a browser view. Always uses the Chrome backend in the daemon
  * (Firecracker guest is Linux; WKWebView isn't available). Serves from
  * the pre-opened pool when the caller uses the default viewport.
+ *
+ * This is the EPHEMERAL path — `close()` destroys the view. The daemon's
+ * `ctx.browser()`/`ctx.mobile()` go through {@link acquirePersistentBrowser}
+ * / {@link acquirePersistentMobileBackend} instead, which keep one view
+ * alive across tests so it rides snapshots/forks.
  */
 export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
   return openMobileBackend(opts);
@@ -668,10 +704,9 @@ export async function openBrowser(opts: BrowserOptions = {}): Promise<Browser> {
  * Like {@link openBrowser} but returns the {@link MobileBackend} superset
  * (touch + probe). When `opts.frame === "mobile"` the view is created at the
  * fixed device viewport, bypasses the (desktop-sized) pool, and has CDP
- * device emulation applied before the first navigation. The mobile facade
- * (`sdk/src/mobile.ts`) calls this; desktop callers go through
- * {@link openBrowser} and get the narrower {@link Browser} view of the same
- * object.
+ * device emulation applied before the first navigation. Desktop callers go
+ * through {@link openBrowser} and get the narrower {@link Browser} view of
+ * the same object.
  */
 export async function openMobileBackend(
   opts: BrowserOptions = {},
@@ -683,27 +718,227 @@ export async function openMobileBackend(
   // views, and a mobile view needs its emulation applied fresh anyway.
   const pooled =
     !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
-  const { view, recordingInstalled } = pooled ?? (await createView(wantW, wantH));
+  const base = pooled ?? (await createView(wantW, wantH));
+  const holder: ViewHolder = {
+    view: base.view,
+    recordingInstalled: base.recordingInstalled,
+    device,
+    width: wantW,
+    height: wantH,
+  };
 
-  if (device) await applyDeviceEmulation(view, device);
+  if (device) await applyDeviceEmulation(holder.view, device);
 
-  const browser = wrapView(view, opts.recorder ?? null, recordingInstalled);
+  const { backend } = buildBackend(holder, opts.recorder ?? null, {
+    persistent: false,
+  });
 
   // We deliberately don't forward `opts.url` to the constructor — going
   // through our own `navigate()` keeps the recorder log uniform (one
   // event per navigation, with timing) and drains rrweb after the load.
   if (opts.url !== undefined) {
-    await browser.navigate(opts.url);
+    await backend.navigate(opts.url);
   }
-  return browser;
+  return backend;
 }
 
-function wrapView(
-  view: BunWebViewInstance,
+// ────────────────────────────────────────────────────────────────────────
+// Persistent sessions (the default behind ctx.browser / ctx.mobile)
+// ────────────────────────────────────────────────────────────────────────
+
+// One long-lived desktop browser plus one mobile session per app URL.
+// Module state lives in daemon memory, so it forks with the snapshot the
+// same way fake `state` and TEST_DATA do: a test's browser — its live
+// page, cookies, localStorage, in-memory SPA state — is captured in the
+// post-test snapshot and inherited by `dependsOn` children, while sibling
+// forks never see each other's sessions. That's what lets a child test
+// continue where its parent left off (e.g. already signed in) instead of
+// re-navigating and re-authenticating.
+let SHARED_BROWSER: ViewHolder | null = null;
+const SHARED_MOBILE = new Map<string, ViewHolder>();
+
+/**
+ * What acquiring a persistent session returns. `detach` is the test-end
+ * hook (final rrweb drain, stop writing to this test's recorder, keep the
+ * view alive); `browser.close()` is the author-facing escape hatch that
+ * actually destroys the view (the next `ctx.browser()` starts fresh).
+ */
+export interface PersistentBrowser {
+  browser: MobileBackend;
+  /** True when this call attached to a view inherited from an earlier
+   *  test (possibly across a snapshot fork) rather than creating one. */
+  attached: boolean;
+  /** Final rrweb drain + detach from the current recorder. The view stays
+   *  alive so the post-test snapshot captures it. Idempotent. */
+  detach(): Promise<void>;
+}
+
+// Runs in the page when a persistent view is attached to a new test's
+// recorder: drop whatever rrweb buffered since the previous detach (idle
+// mutations; the previous test's session already drained everything it
+// owns) and emit a fresh Meta + FullSnapshot so the new session's replay
+// is self-contained from its first event.
+const ATTACH_RESET_EXPR = `(function () {
+  window.__spectestRrwebEvents = [];
+  try {
+    if (typeof rrwebRecord === "function" &&
+        typeof rrwebRecord.takeFullSnapshot === "function") {
+      rrwebRecord.takeFullSnapshot();
+    }
+  } catch (e) { /* recording not active on this document */ }
+  return true;
+})()`;
+
+async function newHolder(
+  width: number,
+  height: number,
+  device: DevicePreset | null,
+): Promise<ViewHolder> {
+  const { view, recordingInstalled } = await createView(width, height);
+  const holder: ViewHolder = { view, recordingInstalled, device, width, height };
+  if (device) await applyDeviceEmulation(view, device);
+  return holder;
+}
+
+async function attachReset(holder: ViewHolder): Promise<void> {
+  if (!holder.recordingInstalled) return;
+  try {
+    await holder.view.evaluate(ATTACH_RESET_EXPR);
+  } catch {
+    // Page mid-navigation or renderer unhappy — the first drain forces a
+    // full snapshot when one is missing (drainExpr), so replay still works.
+  }
+}
+
+/**
+ * Acquire THE persistent desktop browser (creating it on first use). There
+ * is deliberately a single one — `ctx.browser()` always returns it — so a
+ * test DAG shares one browsing session along each branch. The first call's
+ * options win; later calls attach to the existing view as-is.
+ */
+export async function acquirePersistentBrowser(
+  opts: BrowserOptions = {},
+): Promise<PersistentBrowser> {
+  const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
+  let attached = true;
+  if (!SHARED_BROWSER) {
+    attached = false;
+    SHARED_BROWSER = await newHolder(
+      device ? device.viewport.width : opts.width ?? 1280,
+      device ? device.viewport.height : opts.height ?? 720,
+      device,
+    );
+  } else {
+    await attachReset(SHARED_BROWSER);
+  }
+  const holder = SHARED_BROWSER;
+  const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
+    },
+  });
+  if (!attached && opts.url !== undefined) await backend.navigate(opts.url);
+  return { browser: backend, attached, detach };
+}
+
+/**
+ * Acquire the persistent mobile session for an app URL (one per app). A
+ * fresh session navigates to the app; an attach continues on the live page.
+ */
+export async function acquirePersistentMobileBackend(
+  url: string,
+  recorder: BrowserSessionRecorder | null,
+): Promise<PersistentBrowser> {
+  const existing = SHARED_MOBILE.get(url);
+  const holder =
+    existing ??
+    (await newHolder(
+      LATEST_IPHONE.viewport.width,
+      LATEST_IPHONE.viewport.height,
+      LATEST_IPHONE,
+    ));
+  if (existing) {
+    await attachReset(holder);
+  } else {
+    SHARED_MOBILE.set(url, holder);
+  }
+  const { backend, detach } = buildBackend(holder, recorder, {
+    persistent: true,
+    onDestroy: () => {
+      if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
+    },
+  });
+  if (!existing) await backend.navigate(url);
+  return { browser: backend, attached: existing !== undefined, detach };
+}
+
+/** True when a navigation failed on Chromium name resolution. */
+function isNameNotResolved(err: unknown): boolean {
+  return String((err as Error)?.message ?? err).includes("ERR_NAME_NOT_RESOLVED");
+}
+
+/**
+ * Whether the daemon's own resolver can look the URL's host up. Chromium
+ * runs with AsyncDns disabled (see CHROME_ARGV) so it uses the same
+ * getaddrinfo path — a host the daemon resolves but Chrome can't means
+ * the RENDERER is broken, not the name.
+ */
+async function daemonResolves(url: string): Promise<boolean> {
+  try {
+    await dns.lookup(new URL(url).hostname);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace a persistent holder's view with a freshly-spawned one in the same
+ * Chrome. Profile state — cookies, localStorage, the in-VM CA trust — is
+ * per-Chrome, so it survives; only renderer-held page state is lost, and
+ * this path only runs when that renderer already can't navigate.
+ *
+ * Known trigger: a renderer created before a snapshot fails its first
+ * post-restore navigation with `net::ERR_NAME_NOT_RESOLVED` even though a
+ * fresh view in the SAME restored Chrome resolves fine (root cause never
+ * found — see the disabled-prewarm note at the end of /bootstrap in
+ * daemon.ts). Persistent sessions walk into exactly that scenario whenever
+ * a child test navigates, so the recovery lives here: rebuild the view,
+ * retry once.
+ */
+async function rebuildView(holder: ViewHolder): Promise<void> {
+  try {
+    holder.view.close();
+  } catch {
+    /* view may already be gone */
+  }
+  const fresh = await createView(holder.width, holder.height);
+  holder.view = fresh.view;
+  holder.recordingInstalled = fresh.recordingInstalled;
+  if (holder.device) await applyDeviceEmulation(holder.view, holder.device);
+}
+
+interface BackendBuildOptions {
+  /** Persistent views get the DNS-recovery navigate and a close() that
+   *  clears them out of the shared registry; ephemeral views just close. */
+  persistent: boolean;
+  /** Called when close() destroys the underlying view — the acquire
+   *  functions use it to drop the holder from the shared registry. */
+  onDestroy?: () => void;
+}
+
+function buildBackend(
+  holder: ViewHolder,
   recorder: BrowserSessionRecorder | null,
-  recordingInstalled: boolean,
-): MobileBackend {
-  let closed = false;
+  buildOpts: BackendBuildOptions,
+): { backend: MobileBackend; detach(): Promise<void> } {
+  // All page access goes through `holder.view` — never capture the view in
+  // a local — because the DNS-recovery rebuild swaps it mid-wrapper.
+  // `recordingEnded` stops this wrapper's recorder writes (test end);
+  // `viewClosed` tracks actual destruction (author called close()).
+  let recordingEnded = false;
+  let viewClosed = false;
   const sessionStart = Date.now();
   let stepSeq = 0;
   // URL observed at the previous drain. A change means the main frame
@@ -713,11 +948,11 @@ function wrapView(
   let lastDrainUrl: string | null = null;
 
   async function drain(action: BrowserAction | "close"): Promise<void> {
-    if (!recordingInstalled || !recorder || closed) return;
+    if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
-      const urlChanged = view.url !== lastDrainUrl;
-      const events = await view.evaluate<unknown[]>(drainExpr(urlChanged));
-      lastDrainUrl = view.url;
+      const urlChanged = holder.view.url !== lastDrainUrl;
+      const events = await holder.view.evaluate<unknown[]>(drainExpr(urlChanged));
+      lastDrainUrl = holder.view.url;
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
           stepSeq: stepSeq++,
@@ -783,16 +1018,37 @@ function wrapView(
     }
   }
 
-  return {
+  async function endRecording(): Promise<void> {
+    if (recordingEnded) return;
+    // Final drain before we stop writing to this recorder.
+    await drain("close");
+    recordingEnded = true;
+  }
+
+  const backend: MobileBackend = {
     get url() {
-      return view.url;
+      return holder.view.url;
     },
     get title() {
-      return view.title;
+      return holder.view.title;
     },
     navigate(url) {
       recorder?.noteNavigation?.(url);
-      return instrumented("navigate", { url }, () => view.navigate(url));
+      return instrumented("navigate", { url }, async () => {
+        try {
+          await holder.view.navigate(url);
+        } catch (err) {
+          // Restored-renderer DNS bug (see `rebuildView`): only when the
+          // view is persistent (so it may have lived through a snapshot
+          // restore) and the daemon itself CAN resolve the host — a name
+          // that's genuinely unknown must fail without discarding the live
+          // page state a rebuild would cost.
+          if (!buildOpts.persistent || !isNameNotResolved(err)) throw err;
+          if (!(await daemonResolves(url))) throw err;
+          await rebuildView(holder);
+          await holder.view.navigate(url);
+        }
+      });
     },
     async evaluate<T = unknown>(
       description: string,
@@ -809,7 +1065,7 @@ function wrapView(
           scriptTruncated: truncatedScript.truncated,
         },
         async () => {
-          const v = await view.evaluate<T>(script);
+          const v = await holder.view.evaluate<T>(script);
           return v;
         },
       ) as Promise<Wrapped<T>>;
@@ -842,7 +1098,7 @@ function wrapView(
           fields.attempts = (fields.attempts ?? 0) + 1;
           let v: unknown;
           try {
-            v = await view.evaluate<unknown>(expression);
+            v = await holder.view.evaluate<unknown>(expression);
           } catch (err) {
             if (Date.now() >= deadline) throw err;
             await new Promise((r) => setTimeout(r, intervalMs));
@@ -859,41 +1115,41 @@ function wrapView(
       }) as Promise<Wrapped<T>>;
     },
     click(selector) {
-      return instrumented("click", { selector }, () => view.click(selector));
+      return instrumented("click", { selector }, () => holder.view.click(selector));
     },
     clickAt(x, y) {
-      return instrumented("click", { x, y }, () => view.click(x, y));
+      return instrumented("click", { x, y }, () => holder.view.click(x, y));
     },
     type(text) {
       const t = truncateUtf8(text);
       return instrumented(
         "type",
         { text: t.value, textTruncated: t.truncated },
-        () => view.type(text),
+        () => holder.view.type(text),
       );
     },
     press(key) {
-      return instrumented("press", { key }, () => view.press(key));
+      return instrumented("press", { key }, () => holder.view.press(key));
     },
     scroll(dx, dy) {
-      return instrumented("scroll", { dx, dy }, () => view.scroll(dx, dy));
+      return instrumented("scroll", { dx, dy }, () => holder.view.scroll(dx, dy));
     },
     scrollTo(selector) {
-      return instrumented("scrollTo", { selector }, () => view.scrollTo(selector));
+      return instrumented("scrollTo", { selector }, () => holder.view.scrollTo(selector));
     },
     back() {
-      return instrumented("back", {}, () => view.back());
+      return instrumented("back", {}, () => holder.view.back());
     },
     forward() {
-      return instrumented("forward", {}, () => view.forward());
+      return instrumented("forward", {}, () => holder.view.forward());
     },
     reload() {
-      return instrumented("reload", {}, () => view.reload());
+      return instrumented("reload", {}, () => holder.view.reload());
     },
     async screenshot(options) {
       const format = options?.format ?? "png";
       return instrumented("screenshot", { format }, async () => {
-        const buf = await view.screenshot({
+        const buf = await holder.view.screenshot({
           encoding: "buffer",
           format,
           quality: options?.quality,
@@ -902,12 +1158,18 @@ function wrapView(
       });
     },
     async close() {
-      if (closed) return;
-      // Final drain before the page evaporates.
-      await drain("close");
-      closed = true;
+      // Ends this wrapper's recording AND destroys the view. For a
+      // persistent view this is the author-facing escape hatch to a fresh
+      // browser: `onDestroy` drops the holder from the shared registry, so
+      // the next `ctx.browser()`/`ctx.mobile()` creates a new one. The
+      // routine test-end path is `detach` (recording stops, view lives on
+      // into the post-test snapshot).
+      await endRecording();
+      if (viewClosed) return;
+      viewClosed = true;
+      buildOpts.onDestroy?.();
       try {
-        view.close();
+        holder.view.close();
       } catch {
         /* already closed by the runtime */
       }
@@ -918,11 +1180,11 @@ function wrapView(
       // mobile facade owns the author-facing "tap" vocabulary). Dispatches
       // a real touch so RN-Web's responder system fires.
       return instrumented("click", { x, y }, async () => {
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
@@ -931,26 +1193,27 @@ function wrapView(
     swipeBy(x, y, dx, dy) {
       return instrumented("scroll", { dx, dy }, async () => {
         const steps = 8;
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchStart",
           touchPoints: [{ x, y, id: 0 }],
         });
         for (let i = 1; i <= steps; i++) {
-          await view.cdp("Input.dispatchTouchEvent", {
+          await holder.view.cdp("Input.dispatchTouchEvent", {
             type: "touchMove",
             touchPoints: [{ x: x + (dx * i) / steps, y: y + (dy * i) / steps, id: 0 }],
           });
         }
-        await view.cdp("Input.dispatchTouchEvent", {
+        await holder.view.cdp("Input.dispatchTouchEvent", {
           type: "touchEnd",
           touchPoints: [],
         });
       });
     },
     probe<T = unknown>(expression: string): Promise<T> {
-      return view.evaluate<T>(expression);
+      return holder.view.evaluate<T>(expression);
     },
   };
+  return { backend, detach: endRecording };
 }
 
 interface RecordableFields {