@specific.dev/spectest 0.13.0 → 0.15.0

package/src/index.ts

@@ -205,6 +205,69 @@ export interface ServiceConfig {
   cgroupns?: string;
 }
 
+/**
+ * The slice of the in-VM world a component's `setup` / `helpers` hooks can
+ * reach — beyond what the service definition itself declares. Handed to
+ * both hooks (see {@link ServiceSetupContext} / {@link ServiceHelpersContext})
+ * so components stop hand-rolling `child_process` docker execs and stop
+ * hard-coding control-plane paths like `/workspace`.
+ */
+export interface ComponentContext {
+  /**
+   * Absolute path of the extracted project root inside the VM — the
+   * directory the user's repo lands in, with `spectest/` directly under
+   * it. Use this (never a hard-coded path) to locate project files a
+   * component consumes, e.g. `supabase/migrations/**`.
+   */
+  projectRoot: string;
+  /** Read a project file as UTF-8. Relative paths resolve against
+   *  {@link projectRoot}; absolute paths are read as-is. */
+  readProjectFile(path: string): Promise<string>;
+  /**
+   * Run a command inside a service container (a raw `docker exec` — not
+   * recorded on any test timeline, result is plain, not
+   * provenance-wrapped). Pass an **array** for exact argv with no shell
+   * (`["psql", "-f", "-"]`), or a **string** to run via `sh -lc`.
+   * `opts.stdin` is piped to the process — the natural way to feed a SQL
+   * file to `psql -f -` or a manifest to `kubectl apply -f -`.
+   *
+   * Never throws on non-zero exit — inspect `exitCode` yourself.
+   */
+  exec(
+    service: string,
+    command: string | string[],
+    opts?: ComponentExecOpts,
+  ): Promise<ExecResult>;
+}
+
+/** Options for {@link ComponentContext.exec}. */
+export interface ComponentExecOpts {
+  /** Piped to the command's stdin, then closed. */
+  stdin?: string;
+  /** Working directory inside the container (`docker exec -w`). */
+  cwd?: string;
+  /** Kill the exec after this long. Default 120_000. */
+  timeoutMs?: number;
+}
+
+/** What a service's `setup` hook receives. */
+export interface ServiceSetupContext<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  H extends Record<string, any> = Record<string, never>,
+> extends ComponentContext {
+  /** The service's key in the services map (container + DNS name). */
+  name: string;
+  /** The record the service's `helpers` factory returned (cached — setup
+   *  and tests share one instance), or `{}` when it ships none. */
+  helpers: H;
+}
+
+/** What a service's `helpers` factory receives. */
+export interface ServiceHelpersContext extends ComponentContext {
+  /** The service's key in the services map (container + DNS name). */
+  name: string;
+}
+
 /**
  * Same shape as `ServiceConfig` plus an optional `helpers` factory that
  * opens a namespace under `ctx.svc.<name>` inside tests. The factory
@@ -225,10 +288,12 @@ export interface ServiceDefinition<
    * Build the helpers exposed at `ctx.svc.<name>.<key>`. Called by the
    * daemon the first time a test touches this service; the result is
    * cached for the lifetime of the daemon (it survives snapshot/fork
-   * along with the rest of daemon memory). `name` is the key the user
-   * chose in the services map and matches the in-VM DNS name.
+   * along with the rest of daemon memory). `args.name` is the key the
+   * user chose in the services map and matches the in-VM DNS name; the
+   * rest of the {@link ServiceHelpersContext} (exec, projectRoot) lets a
+   * component reach into its containers without daemon internals.
    */
-  helpers?: (args: { name: string }) => H | Promise<H>;
+  helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
   /**
    * One-shot setup after the container's `readyCheck` passes, before
    * dependents start and before any test runs. Awaited in-line with
@@ -238,9 +303,11 @@ export interface ServiceDefinition<
    *
    * `helpers` is the same record the `helpers` factory returns — building
    * it is cached, so `setup` and tests share one instance. If the service
-   * doesn't declare `helpers`, the field is the empty object.
+   * doesn't declare `helpers`, the field is the empty object. The rest of
+   * the {@link ServiceSetupContext} carries `exec` (docker exec with
+   * stdin) and `projectRoot`/`readProjectFile` for project-file access.
    */
-  setup?: (args: { name: string; helpers: H }) => void | Promise<void>;
+  setup?: (args: ServiceSetupContext<H>) => void | Promise<void>;
 }
 
 /** A services map — what users pass to `environment.services`. Entries
@@ -273,6 +340,329 @@ export type ServiceHandlesFor<S extends ServicesMap> = {
  * typed `ctx.svc` in test bodies is `ServiceHandlesFor<S>`. */
 export type ServiceHandles = Record<string, Record<string, unknown>>;
 
+// ──────────────────────────────────────────────────────────────────────────
+// Service groups — one services-map entry that expands to several services.
+//
+// A single container is a `ServiceConfig`/`ServiceDefinition`; a component
+// that is inherently a *constellation* of containers (Supabase ≈ 7 of them)
+// is a `ServiceGroup`. The user mounts the whole group under ONE key:
+//
+//   services: { supabase: sb.group, app: { ... } }
+//
+// and `defineEnvironment` expands it: the group's `primary` part takes the
+// group's own key (`supabase`), every other part lands at `<key>-<part>`
+// (`supabase-db`, `supabase-auth`, …). Inside the group, `dependsOn`
+// entries naming a relative part are rewritten to the final keys, so a
+// group author never manually prefixes anything. Groups are pure sugar —
+// they expand to plain services before validation, so the wire config the
+// control plane sees is unchanged.
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Symbol marking a value in the services map as a group to expand.
+ * Enumerable-symbol convention (like the ingress `provides` decls): it
+ * survives object spread but `JSON.stringify` drops it — not that a group
+ * ever reaches the wire; expansion happens before the config exists. */
+const SERVICE_GROUP: unique symbol = Symbol.for("spectest.service.group");
+
+/**
+ * Naming context handed to a group's `services` factory. Lets the factory
+ * embed *final* DNS names in env vars and config files without knowing the
+ * key the user will mount the group under.
+ */
+export interface GroupNaming {
+  /** The services-map key the user chose for the group. */
+  name: string;
+  /** Final services-map key of a member part: `key(primary)` is `name`
+   *  itself; any other part maps to `` `${name}-${part}` ``. */
+  key(part: string): string;
+}
+
+export interface ServiceGroupInput<
+  P extends ServicesMap,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  H extends Record<string, any> = Record<string, never>,
+  Primary extends keyof P & string = keyof P & string,
+> {
+  /**
+   * Build the group's member services, keyed by RELATIVE part name
+   * (`db`, `auth`, …). Called at expansion time with the final naming
+   * context, so strings that must carry final DNS names (connection
+   * URLs, embedded config) use `g.key("db")`. `dependsOn` entries that
+   * name a relative part are rewritten to final keys automatically
+   * (entries that don't match a part pass through untouched, so a group
+   * service may still depend on an outside service).
+   */
+  services: (g: GroupNaming) => P;
+  /**
+   * The part that represents the group: it takes the group's own map key
+   * (so `dependsOn: ["<groupKey>"]` from outside waits for it), and it
+   * carries the group's consolidated `helpers`/`setup`. The primary is
+   * made the group's dependency **sink** — every other member is added to
+   * its `dependsOn` — so "the primary is ready" means "the whole group is
+   * up, setup included". Consequently no member may depend on the
+   * primary (that would be a cycle); pick a gateway/front-door part.
+   */
+  primary: Primary;
+  /**
+   * The group's consolidated handle: helpers exposed at
+   * `ctx.svc.<groupKey>` — one typed surface for the whole group (e.g.
+   * `{ sql, url, anonKey }` for Supabase). Attached to the primary
+   * service; the primary part itself must not also declare `helpers`.
+   */
+  helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
+  /**
+   * Group-level setup: runs once every member service is ready (run →
+   * probe → per-part setup), before anything that `dependsOn` the group
+   * starts and before any test runs. The home for "the whole stack is
+   * up, now do X". Runs after the primary part's own `setup`, if any.
+   */
+  setup?: (args: ServiceSetupContext<H>) => void | Promise<void>;
+  /**
+   * Pin the services-map key the group must be mounted under. For
+   * components whose *derived* surface (connection URLs, env for the app
+   * under test) is computed from a name option before expansion — a
+   * mismatched key would silently split the two. Expansion errors with a
+   * pointer to the component's `name` option instead.
+   */
+  expectKey?: string;
+}
+
+/**
+ * A multi-service component — the value `serviceGroup(...)` returns, and
+ * what a constellation component (e.g. `supabase()`) hands you to put in
+ * the services map. Opaque; `defineEnvironment` expands it.
+ */
+export interface ServiceGroup<
+  P extends ServicesMap = ServicesMap,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  H extends Record<string, any> = Record<string, never>,
+  Primary extends keyof P & string = keyof P & string,
+> extends ServiceGroupInput<P, H, Primary> {
+  readonly [SERVICE_GROUP]: true;
+}
+
+/**
+ * Define a multi-service group. See {@link ServiceGroupInput} for the
+ * fields; the result goes straight into a services map:
+ *
+ * ```ts
+ * const stack = serviceGroup({
+ *   primary: "gateway",
+ *   services: (g) => ({
+ *     db:      { image: ..., ... },
+ *     gateway: { image: ..., env: { DB_URL: `postgres://${g.key("db")}:5432/db` },
+ *                dependsOn: ["db"] },
+ *   }),
+ *   helpers: () => ({ url: "http://..." }),
+ * });
+ *
+ * defineEnvironment({ name: "app", services: { stack } });
+ * // expands to services `stack` (the gateway) + `stack-db`;
+ * // ctx.svc.stack is the helpers record.
+ * ```
+ */
+export function serviceGroup<
+  P extends ServicesMap,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  H extends Record<string, any> = Record<string, never>,
+  Primary extends keyof P & string = keyof P & string,
+>(input: ServiceGroupInput<P, H, Primary>): ServiceGroup<P, H, Primary> {
+  if (typeof input.services !== "function") {
+    throw new Error("serviceGroup: `services` must be a factory function");
+  }
+  if (!input.primary || typeof input.primary !== "string") {
+    throw new Error("serviceGroup: `primary` (a relative part name) is required");
+  }
+  const group = { ...input } as ServiceGroup<P, H, Primary>;
+  Object.defineProperty(group, SERVICE_GROUP, {
+    value: true,
+    enumerable: true,
+    configurable: true,
+    writable: false,
+  });
+  return group;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isServiceGroup(v: unknown): v is ServiceGroup<any, any, any> {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as Record<symbol, unknown>)[SERVICE_GROUP] === true
+  );
+}
+
+/** What users pass as `services` to `defineEnvironment`: plain services
+ * and/or groups to expand. */
+export type InputServicesMap = Record<
+  string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ServiceConfig | ServiceGroup<any, any, any>
+>;
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (x: U) => void : never
+) extends (x: infer I) => void
+  ? I
+  : never;
+
+/** Flatten an intersection of records into one mapped type (which also
+ * gives it the implicit index signature `ServicesMap` needs). */
+type Reify<T> = { [K in keyof T]: T[K] };
+
+/** The primary part with the group's consolidated `helpers` grafted on,
+ * so `ServiceHandlesFor` surfaces the group handle at the group key. */
+type PrimaryWithHandle<C, H> = [H] extends [Record<string, never>]
+  ? C
+  : Omit<C, "helpers"> & { helpers: (args: ServiceHelpersContext) => H };
+
+type ExpandGroupEntry<K extends string, G> = G extends ServiceGroup<
+  infer P,
+  infer H,
+  infer Primary
+>
+  ? {
+      [Q in Exclude<keyof P & string, Primary> as `${K}-${Q}`]: P[Q];
+    } & { [Q in K]: PrimaryWithHandle<P[Primary & keyof P], H> }
+  : never;
+
+/**
+ * The services map after group expansion — what `ctx.svc` and the wire
+ * config are typed against. Groups expand to `<key>` (primary, carrying
+ * the group handle) + `<key>-<part>` entries; plain services pass through.
+ */
+export type ExpandServices<SI extends InputServicesMap> = Reify<
+  UnionToIntersection<
+    {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      [K in keyof SI & string]: SI[K] extends ServiceGroup<any, any, any>
+        ? ExpandGroupEntry<K, SI[K]>
+        : { [Q in K]: SI[K] };
+    }[keyof SI & string]
+  >
+> extends infer S extends ServicesMap
+  ? S
+  : ServicesMap;
+
+/**
+ * Runtime counterpart of {@link ExpandServices}: expand every group entry
+ * into plain services. Throws on key collisions, a missing primary,
+ * nested groups, a violated `expectKey`, and members depending on the
+ * primary (the primary is the group's sink — see
+ * {@link ServiceGroupInput.primary}).
+ */
+function expandServiceGroups(input: InputServicesMap): ServicesMap {
+  const out: ServicesMap = {};
+  const ownerOf = new Map<string, string>();
+  const claim = (key: string, owner: string): void => {
+    const prior = ownerOf.get(key);
+    if (prior !== undefined) {
+      throw new Error(
+        `service key ${JSON.stringify(key)} is produced by both ${prior} and ${owner}`,
+      );
+    }
+    ownerOf.set(key, owner);
+  };
+
+  for (const [key, entry] of Object.entries(input)) {
+    if (!isServiceGroup(entry)) {
+      claim(key, "the services map");
+      out[key] = entry;
+      continue;
+    }
+    const owner = `group ${JSON.stringify(key)}`;
+    if (entry.expectKey !== undefined && entry.expectKey !== key) {
+      throw new Error(
+        `service group at key ${JSON.stringify(key)} expects to be mounted at ` +
+          `${JSON.stringify(entry.expectKey)} — its derived names (URLs, app env) were built ` +
+          `from that name. Mount it at ${JSON.stringify(entry.expectKey)}, or pass ` +
+          `\`name: ${JSON.stringify(key)}\` to the component so both agree.`,
+      );
+    }
+    const naming: GroupNaming = {
+      name: key,
+      key: (part: string) => (part === entry.primary ? key : `${key}-${part}`),
+    };
+    const parts: ServicesMap = entry.services(naming);
+    const partKeys = new Set(Object.keys(parts));
+    if (!partKeys.has(entry.primary)) {
+      throw new Error(
+        `${owner}: primary part ${JSON.stringify(entry.primary)} is not in the parts the ` +
+          `services factory returned (${[...partKeys].join(", ")})`,
+      );
+    }
+    // No member may depend on the primary (directly or transitively within
+    // the group): the primary is about to become the group's sink.
+    const reachesPrimary = (part: string, seen = new Set<string>()): boolean => {
+      if (seen.has(part)) return false;
+      seen.add(part);
+      for (const dep of parts[part]?.dependsOn ?? []) {
+        if (!partKeys.has(dep)) continue;
+        if (dep === entry.primary || reachesPrimary(dep, seen)) return true;
+      }
+      return false;
+    };
+    for (const part of partKeys) {
+      if (isServiceGroup(parts[part])) {
+        throw new Error(`${owner}: part ${JSON.stringify(part)} is itself a group — groups don't nest`);
+      }
+      if (part !== entry.primary && reachesPrimary(part)) {
+        throw new Error(
+          `${owner}: part ${JSON.stringify(part)} depends on the primary ` +
+            `${JSON.stringify(entry.primary)} — the primary must be the group's sink ` +
+            `(everything else becomes its dependency so "primary ready" means "group up")`,
+        );
+      }
+    }
+    for (const [part, svc] of Object.entries(parts)) {
+      const finalKey = naming.key(part);
+      claim(finalKey, owner);
+      // Rewrite relative dependsOn to final keys; a spread keeps function
+      // fields (helpers/setup) and the enumerable-symbol ingress decls.
+      const final: ServiceConfig = { ...svc };
+      if (svc.dependsOn?.length) {
+        final.dependsOn = svc.dependsOn.map((d) =>
+          partKeys.has(d) ? naming.key(d) : d,
+        );
+      }
+      if (part === entry.primary) {
+        // Sink: the primary waits for every other member, so an outside
+        // `dependsOn: ["<groupKey>"]` (and the group `setup` below) means
+        // the whole group. Members already in dependsOn stay put.
+        const deps = new Set(final.dependsOn ?? []);
+        for (const other of partKeys) {
+          if (other !== entry.primary) deps.add(naming.key(other));
+        }
+        final.dependsOn = [...deps];
+        const def = final as ServiceDefinition<Record<string, unknown>>;
+        if (entry.helpers) {
+          if (def.helpers) {
+            throw new Error(
+              `${owner}: both the group and its primary part declare \`helpers\` — ` +
+                `declare them once, on the group`,
+            );
+          }
+          def.helpers = entry.helpers as (
+            args: ServiceHelpersContext,
+          ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+        }
+        if (entry.setup) {
+          const partSetup = def.setup;
+          const groupSetup = entry.setup as (
+            args: ServiceSetupContext<Record<string, unknown>>,
+          ) => void | Promise<void>;
+          def.setup = async (args) => {
+            if (partSetup) await partSetup(args);
+            await groupSetup(args);
+          };
+        }
+      }
+      out[finalKey] = final;
+    }
+  }
+  return out;
+}
+
 /**
  * One TLS-terminated hostname for a service. The daemon binds the
  * hostname on `:443` (with a leaf cert signed by the in-VM root CA)
@@ -304,6 +694,17 @@ export type ServiceImage =
     };
 
 export interface VolumeMount {
+  /**
+   * Named shared volume. Two services mounting the same `name` share one
+   * backing directory — the fit for sidecar pairs that exchange files
+   * (e.g. an image proxy reading what a storage API wrote). The directory
+   * lives in the per-env state tree, so it snapshots/forks with the rest
+   * of the environment and is torn down for fresh-state like any other
+   * volume. Names are environment-global: prefix with your service/group
+   * name in a reusable component so two instances never collide.
+   * Mutually exclusive with `source`.
+   */
+  name?: string;
   /**
    * Host path. Relative paths resolve under
    * `.spectest/volumes/<service>/`. Defaults to a path derived from `target`.
@@ -342,7 +743,25 @@ export interface FileMount {
 
 export type ReadyCheck =
   | { type: "tcp"; port: number; timeoutSecs?: number }
-  | { type: "http"; port: number; path?: string; timeoutSecs?: number }
+  | {
+      type: "http";
+      port: number;
+      path?: string;
+      /**
+       * Extra request headers sent with each probe — for health endpoints
+       * behind auth (`{ Authorization: "Bearer …" }`). Keeps the probe
+       * image-agnostic where an `exec` + curl would depend on curl being
+       * in the image.
+       */
+      headers?: Record<string, string>;
+      /**
+       * Exact status code that counts as ready. Default: any 2xx. Use for
+       * endpoints whose healthy answer isn't 2xx (e.g. a root path that
+       * 301s or 401s once the server is actually up).
+       */
+      expectStatus?: number;
+      timeoutSecs?: number;
+    }
   /**
    * Run a shell command inside the container; exit 0 = ready. Used when
    * the readiness signal isn't reachable via plain TCP/HTTP from outside
@@ -451,6 +870,18 @@ function validateEnvironmentConfig<S extends ServicesMap>(
         );
       }
     }
+    for (const vol of svc.volumes ?? []) {
+      if (vol.name !== undefined && vol.source !== undefined) {
+        throw new Error(
+          `service "${name}" volume for ${JSON.stringify(vol.target)} sets both \`name\` and \`source\` — a named shared volume derives its backing dir from the name`,
+        );
+      }
+      if (vol.name !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(vol.name)) {
+        throw new Error(
+          `service "${name}" volume name ${JSON.stringify(vol.name)} must be alphanumeric plus [._-]`,
+        );
+      }
+    }
     for (const raw of svc.hostnames ?? []) {
       const h = raw.toLowerCase();
       if (!HOSTNAME_RE.test(h)) {
@@ -630,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>;
   /**
@@ -651,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. */
@@ -1111,11 +1558,22 @@ export interface ProjectOpts<
  * creates a test — that's what makes `ctx.fakes.<key>` strongly typed.
  * `fakes` is stripped from `config` before it's stored/serialised, so the
  * wire `EnvironmentConfig` the Rust control plane sees never carries it.
+ *
+ * Unlike the wire {@link EnvironmentConfig}, `services` entries here may
+ * be {@link ServiceGroup}s — they're expanded to plain services (primary
+ * at the group's key, other parts at `<key>-<part>`) before validation.
  */
 export interface EnvironmentInput<
-  S extends ServicesMap,
+  SI extends InputServicesMap,
   F extends FakesMap = FakesMap,
-> extends EnvironmentConfig<S> {
+> {
+  /** Human-friendly name for the environment, e.g. "my-app". */
+  name: string;
+  /** Services and/or service groups, keyed by name. See
+   *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
+  services: SI;
+  /** Sandbox timeout in seconds (default 1h). */
+  timeoutSecs?: number;
   /** Fake servers — see {@link defineFake}. Keyed by stable name; the key
    * shows up as `ctx.fakes.<key>` in tests, typed as that fake's helpers
    * record. */
@@ -1148,12 +1606,18 @@ export interface DefinedEnvironment<
  * produces the file's default export.
  */
 export function defineEnvironment<
-  S extends ServicesMap,
+  SI extends InputServicesMap,
   F extends FakesMap = FakesMap,
->(input: EnvironmentInput<S, F>): DefinedEnvironment<S, F> {
-  // Split fakes off the wire config; only { name, services, timeoutSecs }
+>(input: EnvironmentInput<SI, F>): DefinedEnvironment<ExpandServices<SI>, F> {
+  type S = ExpandServices<SI>;
+  // Split fakes off the wire config and expand service groups; only
+  // { name, services, timeoutSecs } — with plain, fully-expanded services —
   // is stored as `config` and shipped to the control plane.
-  const { fakes, ...config } = input;
+  const { fakes, services: rawServices, ...rest } = input;
+  const config: EnvironmentConfig<S> = {
+    ...rest,
+    services: expandServiceGroups(rawServices) as S,
+  };
   validateEnvironmentConfig(config);
   if (fakes) validateFakes(config, fakes);
 

package/src/mobile.ts

@@ -14,7 +14,7 @@
 // `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,
@@ -362,9 +362,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 +377,22 @@ 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> }> {
+  const { browser, attached, detach } = await acquirePersistentMobileBackend(
+    opts.url,
+    opts.recorder,
+  );
+  return { mobile: wrapMobile(browser), attached, detach };
+}