@specific.dev/spectest 0.41.0 → 0.43.0

package/dist/browser.d.ts

@@ -60,6 +60,14 @@ export interface BrowserSessionRecorder {
      * the dashboard can link a browser event to its replay player.
      */
     readonly sessionId: string;
+    /**
+     * Author-given name of this session (`ctx.browser("alice")`), absent
+     * for the default unnamed one. Echoed onto every op's event so the
+     * step list can say WHICH browser acted without having to resolve the
+     * session record — which the CLI's failure detail can't do (it renders
+     * from the persisted events alone, with no replay bundle).
+     */
+    readonly sessionName?: string;
     /** Called for each drained chunk of rrweb events. */
     recordStep(step: BrowserSessionStep): void;
     /** Optional: called whenever `Browser.goto(url)` is invoked. */
@@ -302,6 +310,9 @@ export declare function openBrowser(opts?: BrowserOptions): Promise<Browser>;
  * the same object.
  */
 export declare function openMobileBackend(opts?: BrowserOptions): Promise<MobileBackend>;
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export declare function mobileKey(name: string, url: string): string;
 /**
  * What acquiring a persistent session returns. `detach` is the test-end
  * hook (final rrweb drain, stop writing to this test's recorder, keep the
@@ -318,17 +329,19 @@ export interface PersistentBrowser {
     detach(): Promise<void>;
 }
 /**
- * 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.
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
  */
-export declare function acquirePersistentBrowser(opts?: BrowserOptions): Promise<PersistentBrowser>;
+export declare function acquirePersistentBrowser(name?: string, opts?: BrowserOptions): Promise<PersistentBrowser>;
 /**
- * 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.
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
  */
-export declare function acquirePersistentMobileBackend(url: string, recorder: BrowserSessionRecorder | null, initScript?: string): Promise<PersistentBrowser>;
+export declare function acquirePersistentMobileBackend(url: string, name: string, recorder: BrowserSessionRecorder | null, initScript?: string): Promise<PersistentBrowser>;
 export interface RecordableFields {
     url: string;
     selector: string;

package/dist/browser.js

@@ -872,16 +872,45 @@ export async function openMobileBackend(opts = {}) {
 // ────────────────────────────────────────────────────────────────────────
 // Persistent sessions (the default behind ctx.browser / ctx.mobile)
 // ────────────────────────────────────────────────────────────────────────
-// One long-lived desktop browser plus one mobile session per app URL.
+// Long-lived sessions, keyed by NAME: one desktop browser per name, one
+// mobile session per (name, app URL). The default name is `""` — what
+// `ctx.browser()` / `ctx.mobile(app)` use — so an unnamed project keeps
+// exactly the one-session-per-device behaviour it had before names
+// existed. A name is the key and nothing else: two names are two
+// BrowserContexts in the one Chromium, i.e. two independent cookie jars
+// and localStorage, which is what modelling two users needs.
+//
 // 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
+// same way fake `state` and TEST_DATA do: a test's browsers — their live
+// pages, cookies, localStorage, in-memory SPA state — are 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 = null;
+// re-navigating and re-authenticating. The name is a plain string, so it
+// keys the same session on both sides of a fork.
+const SHARED_BROWSERS = new Map();
 const SHARED_MOBILE = new Map();
+/**
+ * Ceiling on live persistent sessions of one kind (desktop / mobile).
+ * Every session is a Chromium BrowserContext that rides every snapshot
+ * from here down the DAG, so a test that mints names in a loop
+ * (`ctx.browser(userId)`) would grow the VM's memory floor for the rest
+ * of the run. Failing loudly at a sane count beats a wedged guest.
+ */
+const MAX_PERSISTENT_SESSIONS = 8;
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export function mobileKey(name, url) {
+    return `${name}\u0000${url}`;
+}
+/** Guard the session cap, naming the offender and what to do about it. */
+function checkSessionCap(kind, live, name) {
+    if (live < MAX_PERSISTENT_SESSIONS)
+        return;
+    throw new Error(`too many ${kind} sessions: ${MAX_PERSISTENT_SESSIONS} are already open and "${name}" would be another. ` +
+        `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
+        `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`);
+}
 async function newHolder(width, height, device) {
     const context = await newViewContext(width, height, device);
     const spawned = await spawnPage(context);
@@ -941,58 +970,65 @@ async function attachReset(holder) {
     }
 }
 /**
- * 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.
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
  */
-export async function acquirePersistentBrowser(opts = {}) {
+export async function acquirePersistentBrowser(name = "", opts = {}) {
     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);
+    let holder = SHARED_BROWSERS.get(name);
+    const attached = holder !== undefined;
+    if (holder) {
+        await attachReset(holder);
     }
     else {
-        await attachReset(SHARED_BROWSER);
+        checkSessionCap("browser", SHARED_BROWSERS.size, name);
+        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device);
+        SHARED_BROWSERS.set(name, holder);
     }
-    const holder = SHARED_BROWSER;
-    const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+    const view = holder;
+    const { backend, detach } = buildBackend(view, opts.recorder ?? null, {
         persistent: true,
         onDestroy: () => {
-            if (SHARED_BROWSER === holder)
-                SHARED_BROWSER = null;
+            if (SHARED_BROWSERS.get(name) === view)
+                SHARED_BROWSERS.delete(name);
         },
     });
     // Fresh session only: an attached view already carries the init script on
     // its (forked) holder, and first-call-wins means a later call's options
     // don't retroactively apply.
     if (!attached && opts.initScript !== undefined) {
-        await installInitScript(holder, opts.initScript);
+        await installInitScript(view, opts.initScript);
     }
     if (!attached && opts.url !== undefined)
         await backend.goto(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.
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
  */
-export async function acquirePersistentMobileBackend(url, recorder, initScript) {
-    const existing = SHARED_MOBILE.get(url);
+export async function acquirePersistentMobileBackend(url, name, recorder, initScript) {
+    const key = mobileKey(name, url);
+    const existing = SHARED_MOBILE.get(key);
+    if (!existing)
+        checkSessionCap("mobile", SHARED_MOBILE.size, name);
     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);
+        SHARED_MOBILE.set(key, holder);
     }
     const { backend, detach } = buildBackend(holder, recorder, {
         persistent: true,
         onDestroy: () => {
-            if (SHARED_MOBILE.get(url) === holder)
-                SHARED_MOBILE.delete(url);
+            if (SHARED_MOBILE.get(key) === holder)
+                SHARED_MOBILE.delete(key);
         },
     });
     if (!existing) {
@@ -1069,6 +1105,18 @@ function buildBackend(holder, recorder, buildOpts) {
     // when rrweb's load-deferred full snapshot is most likely to be
     // missing from the chunk we're about to drain (see `drainExpr`).
     let lastDrainUrl = null;
+    /** Session provenance stamped on every recorded op: which replay player
+     *  the step belongs to, which named browser it acted on, and where in
+     *  the player to seek (`endT`, in rrweb's clock). */
+    function sessionFields(endT) {
+        if (!recorder)
+            return {};
+        return {
+            sessionId: recorder.sessionId,
+            sessionTimestamp: endT,
+            ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
+        };
+    }
     async function drain(action) {
         if (!holder.recordingInstalled || !recorder || recordingEnded)
             return;
@@ -1112,9 +1160,7 @@ function buildBackend(holder, recorder, buildOpts) {
             const seq = recordBrowser({
                 action,
                 ...fields,
-                ...(recorder
-                    ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-                    : {}),
+                ...sessionFields(endT),
                 durationMs: endT - t,
             }, resv);
             await drain(action);
@@ -1132,9 +1178,7 @@ function buildBackend(holder, recorder, buildOpts) {
             recordBrowser({
                 action,
                 ...fields,
-                ...(recorder
-                    ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-                    : {}),
+                ...sessionFields(endT),
                 durationMs: endT - t,
                 error: e?.message ?? String(err),
             }, resv);
@@ -1459,9 +1503,7 @@ function buildBackend(holder, recorder, buildOpts) {
             const seq = recordBrowser({
                 action,
                 ...fields,
-                ...(recorder
-                    ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-                    : {}),
+                ...sessionFields(endT),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
             }, reserveBackdated(waitedMs));

package/dist/daemon.js

@@ -22,7 +22,7 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
-import { acquirePersistentBrowser } from "./browser.js";
+import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
@@ -2686,6 +2686,19 @@ function newArtifactCollector() {
         },
     };
 }
+/**
+ * Normalise `ctx.browser(...)`'s two call shapes — `(opts?)` for the
+ * default session and `(name, opts?)` for a named one — into the
+ * `(name, opts)` pair the session registry keys on. The overloads make
+ * these the only two shapes that typecheck, but the implementation still
+ * has to tell them apart at runtime: an untyped caller (`eval`, plain JS)
+ * reaches the same function.
+ */
+function browserArgs(nameOrOpts, opts) {
+    return typeof nameOrOpts === "string"
+        ? { name: nameOrOpts, opts }
+        : { name: "", opts: nameOrOpts };
+}
 /**
  * Build the recorder sink + bookkeeping for a single Browser session.
  * The returned `recorder` is what `openBrowser` writes into; the
@@ -2694,11 +2707,15 @@ function newArtifactCollector() {
  * test-run sessions don't pass it, which is exactly what makes
  * `screenshot()` throw outside eval.
  */
-function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
+function newBrowserSession(testStart, idScope, frame = "browser", artifacts, name = "") {
     const record = {
         sessionId: newSessionId(idScope),
         openedAtMs: Date.now() - testStart,
         frame,
+        // Omit the key entirely for the default session rather than storing
+        // `""` — every consumer treats "no name" as "don't render a label",
+        // and an empty string would have to be special-cased in each of them.
+        ...(name ? { name } : {}),
         steps: [],
     };
     let closed = false;
@@ -2706,6 +2723,7 @@ function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
         record,
         recorder: {
             sessionId: record.sessionId,
+            ...(name ? { sessionName: name } : {}),
             recordStep(step) {
                 if (closed)
                     return;
@@ -3537,31 +3555,37 @@ async function runOne(testCase) {
     // an ancestor fork; its TEST_DATA entry travels with the snapshot.
     const parentId = testCase.dependsOn?.id;
     const parent = parentId !== undefined ? TEST_DATA.get(parentId) : undefined;
-    // 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
+    // Browser/mobile sessions are PERSISTENT and keyed by NAME:
+    // `ctx.browser(name?)` acquires the desktop browser called `name` and
+    // `ctx.mobile(app, name?)` that name's session for that app (browser.ts's
+    // module-scoped registry, which forks with the snapshot like fake state).
+    // The default name is `""`, so an unnamed project has exactly the one
+    // session per device it always had. 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.
+    // children resume the live pages (cookies, localStorage, signed-in SPA
+    // state) instead of re-navigating; that inheritance is per name, so a
+    // parent that signed "alice" and "bob" in hands both down. Each test
+    // still gets its own session record per name (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
+    // calls for the SAME name return the same handle (memoized below) so one
+    // test = one session per (device, name). An explicit `.close()` destroys
+    // that name's instance — its memo entry is cleared so a later call for
+    // the same name starts fresh, and other names are untouched.
     const browserDetaches = [];
     const sessions = [];
-    let sharedBrowser = null;
+    const sharedBrowsers = new Map();
     const sharedMobiles = new Map();
-    const trackedOpenBrowser = async (opts) => {
-        if (sharedBrowser)
-            return sharedBrowser;
-        const session = newBrowserSession(start, testCase.id);
+    const trackedOpenBrowser = async (nameOrOpts, maybeOpts) => {
+        const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+        const memo = sharedBrowsers.get(name);
+        if (memo)
+            return memo;
+        const session = newBrowserSession(start, testCase.id, "browser", undefined, name);
         sessions.push(session);
-        const { browser, attached, detach } = await acquirePersistentBrowser({
+        const { browser, attached, detach } = await acquirePersistentBrowser(name, {
             ...(opts ?? {}),
             recorder: session.recorder,
         });
@@ -3580,23 +3604,25 @@ async function runOne(testCase) {
         const innerClose = browser.close.bind(browser);
         browser.close = async () => {
             await innerClose();
-            if (sharedBrowser === browser)
-                sharedBrowser = null;
+            if (sharedBrowsers.get(name) === browser)
+                sharedBrowsers.delete(name);
         };
-        sharedBrowser = browser;
+        sharedBrowsers.set(name, browser);
         return browser;
     };
-    const trackedOpenMobile = async (app) => {
+    const trackedOpenMobile = async (app, name = "") => {
         if (!isMobileApp(app)) {
             throw new Error("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);
+        const key = mobileKey(name, app.url);
+        const existing = sharedMobiles.get(key);
         if (existing)
             return existing;
-        const session = newBrowserSession(start, testCase.id, "mobile");
+        const session = newBrowserSession(start, testCase.id, "mobile", undefined, name);
         sessions.push(session);
         const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
             url: app.url,
+            name,
             recorder: session.recorder,
             initScript: app.initScript,
         });
@@ -3612,10 +3638,10 @@ async function runOne(testCase) {
         const innerClose = mobile.close.bind(mobile);
         mobile.close = async () => {
             await innerClose();
-            if (sharedMobiles.get(app.url) === mobile)
-                sharedMobiles.delete(app.url);
+            if (sharedMobiles.get(key) === mobile)
+                sharedMobiles.delete(key);
         };
-        sharedMobiles.set(app.url, mobile);
+        sharedMobiles.set(key, mobile);
         return mobile;
     };
     // The shared context (svc/fakes handles, poll, project files, dnsName,
@@ -3975,14 +4001,16 @@ async function evalCode(code, secrets) {
     // Eval-only artifact sink — wiring it here (and nowhere in runOne) is
     // what gates screenshot() to eval context.
     const artifactCollector = newArtifactCollector();
-    let sharedBrowser = null;
+    const sharedBrowsers = new Map();
     const sharedMobiles = new Map();
-    const trackedOpenBrowser = async (opts) => {
-        if (sharedBrowser)
-            return sharedBrowser;
-        const session = newBrowserSession(start, "eval", "browser", artifactCollector);
+    const trackedOpenBrowser = async (nameOrOpts, maybeOpts) => {
+        const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+        const memo = sharedBrowsers.get(name);
+        if (memo)
+            return memo;
+        const session = newBrowserSession(start, "eval", "browser", artifactCollector, name);
         sessions.push(session);
-        const { browser, attached, detach } = await acquirePersistentBrowser({
+        const { browser, attached, detach } = await acquirePersistentBrowser(name, {
             ...(opts ?? {}),
             recorder: session.recorder,
         });
@@ -3999,23 +4027,25 @@ async function evalCode(code, secrets) {
         const innerClose = browser.close.bind(browser);
         browser.close = async () => {
             await innerClose();
-            if (sharedBrowser === browser)
-                sharedBrowser = null;
+            if (sharedBrowsers.get(name) === browser)
+                sharedBrowsers.delete(name);
         };
-        sharedBrowser = browser;
+        sharedBrowsers.set(name, browser);
         return browser;
     };
-    const trackedOpenMobile = async (app) => {
+    const trackedOpenMobile = async (app, name = "") => {
         if (!isMobileApp(app)) {
             throw new Error("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);
+        const key = mobileKey(name, app.url);
+        const existing = sharedMobiles.get(key);
         if (existing)
             return existing;
-        const session = newBrowserSession(start, "eval", "mobile", artifactCollector);
+        const session = newBrowserSession(start, "eval", "mobile", artifactCollector, name);
         sessions.push(session);
         const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
             url: app.url,
+            name,
             recorder: session.recorder,
             initScript: app.initScript,
         });
@@ -4031,10 +4061,10 @@ async function evalCode(code, secrets) {
         const innerClose = mobile.close.bind(mobile);
         mobile.close = async () => {
             await innerClose();
-            if (sharedMobiles.get(app.url) === mobile)
-                sharedMobiles.delete(app.url);
+            if (sharedMobiles.get(key) === mobile)
+                sharedMobiles.delete(key);
         };
-        sharedMobiles.set(app.url, mobile);
+        sharedMobiles.set(key, mobile);
         return mobile;
     };
     // Terminal sessions — same shape as runOne, but eval has no active

package/dist/index.d.ts

@@ -936,20 +936,57 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
     /**
      * 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).
+     * There is one persistent browser PER NAME, and `ctx.browser()` is the
+     * default (unnamed) one: every 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).
+     *
+     * For a second, independent browser — a second user — name it:
+     * `ctx.browser("alice")`. See the named overload.
      *
      * `.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>;
+    /**
+     * Open the persistent browser called `name`, creating it on first use.
+     * Each name is its own browser — its own cookies, localStorage and page —
+     * so naming them is how one test drives two users.
+     *
+     * **Only name a browser when the test needs two or more isolated sessions
+     * at once.** Otherwise use `ctx.browser()`: a name is a second identity,
+     * not a label, and a lone `ctx.browser("main")` buys nothing over the
+     * default while adding its name to every step title in the dashboard.
+     *
+     * ```ts
+     * const alice = await ctx.browser("alice", { url: "https://app.test" });
+     * const bob = await ctx.browser("bob", { url: "https://app.test" });
+     * await alice.getByRole("button", { name: "Share" }).click();
+     * await bob.reload();
+     * await expect(bob.getByText("Shared with you")).toBeVisible();
+     * ```
+     *
+     * Every rule of the default browser applies per name: the session rides
+     * the snapshot, so a `dependsOn` child inherits *each* named browser
+     * exactly where its parent left it (sign both users in once, in the
+     * parent); repeat calls with the same name in one test return the same
+     * handle; the first call for a name wins its options; `.close()` discards
+     * only that name. Sessions are named for the roles under test, not per
+     * row of data — each one is a live browser captured in every snapshot
+     * from here on, and opening too many is an error.
+     *
+     * The dashboard titles each step with the browser that performed it
+     * (`bob: click "Share"`) and labels the replay with the same name, so a
+     * two-user timeline stays readable and selecting a step shows that
+     * browser's session.
+     */
+    browser(name: string, opts?: BrowserOptions): Promise<Browser>;
     /**
      * Open a phone-emulated session for a mobile app and return a {@link Mobile}
      * handle already pointed at it — no `navigate`. Pass the app handle a
@@ -968,13 +1005,18 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * The session emulates the latest iPhone (viewport + DPR + mobile UA +
      * 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;
+     * Sessions are persistent, one per app per `name`: 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.
+     *
+     * Pass a `name` for a second phone running the same app — two users in
+     * one test: `ctx.mobile(ctx.svc.app, "alice")`. Names are independent
+     * sessions and are inherited per name by `dependsOn` children, exactly
+     * like named desktop browsers.
      */
-    mobile(app: MobileApp): Promise<Mobile>;
+    mobile(app: MobileApp, name?: string): Promise<Mobile>;
     /** The test's display name. */
     readonly testName: string;
     /**

package/dist/mobile.d.ts

@@ -49,14 +49,18 @@ export declare function openMobile(opts: {
     recorder: BrowserSessionRecorder | null;
 }): Promise<Mobile>;
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). 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.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` 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 declare function openPersistentMobile(opts: {
     url: string;
+    /** Session name — `""` (the default) is the unnamed session every
+     *  `ctx.mobile(app)` call shares. Two names on one app are two phones. */
+    name?: string;
     recorder: BrowserSessionRecorder | null;
     /** Installed before the fresh session's first navigation (ignored on an
      *  attached session, which already carries it on the forked holder). */

package/dist/mobile.js

@@ -48,14 +48,15 @@ export async function openMobile(opts) {
     return backend;
 }
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). 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.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` 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) {
-    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.recorder, opts.initScript);
+    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.name ?? "", opts.recorder, opts.initScript);
     return {
         mobile: browser,
         attached,

package/dist/recorder.d.ts

@@ -379,6 +379,16 @@ export interface BrowserEvent extends BaseEvent {
      * with a `BrowserSessionRecorder` attached (the daemon always does).
      */
     sessionId?: string;
+    /**
+     * Author-given name of that session — `ctx.browser("alice")` — absent
+     * for the default unnamed browser, so a single-browser test's steps
+     * carry no name and render exactly as they always have. Present, it is
+     * what the step list badges to say which browser acted. Duplicated here
+     * rather than resolved from the session record because the CLI's
+     * failure detail renders from persisted events alone, with no replay
+     * bundle to look the session up in.
+     */
+    sessionName?: string;
     /**
      * Wall-clock `Date.now()` captured at the moment this op *finished*.
      * Lives in the same time base as rrweb's `event.timestamp` fields,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser.ts

@@ -136,6 +136,14 @@ export interface BrowserSessionRecorder {
    * the dashboard can link a browser event to its replay player.
    */
   readonly sessionId: string;
+  /**
+   * Author-given name of this session (`ctx.browser("alice")`), absent
+   * for the default unnamed one. Echoed onto every op's event so the
+   * step list can say WHICH browser acted without having to resolve the
+   * session record — which the CLI's failure detail can't do (it renders
+   * from the persisted events alone, with no replay bundle).
+   */
+  readonly sessionName?: string;
   /** Called for each drained chunk of rrweb events. */
   recordStep(step: BrowserSessionStep): void;
   /** Optional: called whenever `Browser.goto(url)` is invoked. */
@@ -1304,17 +1312,50 @@ export async function openMobileBackend(
 // Persistent sessions (the default behind ctx.browser / ctx.mobile)
 // ────────────────────────────────────────────────────────────────────────
 
-// One long-lived desktop browser plus one mobile session per app URL.
+// Long-lived sessions, keyed by NAME: one desktop browser per name, one
+// mobile session per (name, app URL). The default name is `""` — what
+// `ctx.browser()` / `ctx.mobile(app)` use — so an unnamed project keeps
+// exactly the one-session-per-device behaviour it had before names
+// existed. A name is the key and nothing else: two names are two
+// BrowserContexts in the one Chromium, i.e. two independent cookie jars
+// and localStorage, which is what modelling two users needs.
+//
 // 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
+// same way fake `state` and TEST_DATA do: a test's browsers — their live
+// pages, cookies, localStorage, in-memory SPA state — are 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;
+// re-navigating and re-authenticating. The name is a plain string, so it
+// keys the same session on both sides of a fork.
+const SHARED_BROWSERS = new Map<string, ViewHolder>();
 const SHARED_MOBILE = new Map<string, ViewHolder>();
 
+/**
+ * Ceiling on live persistent sessions of one kind (desktop / mobile).
+ * Every session is a Chromium BrowserContext that rides every snapshot
+ * from here down the DAG, so a test that mints names in a loop
+ * (`ctx.browser(userId)`) would grow the VM's memory floor for the rest
+ * of the run. Failing loudly at a sane count beats a wedged guest.
+ */
+const MAX_PERSISTENT_SESSIONS = 8;
+
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export function mobileKey(name: string, url: string): string {
+  return `${name}\u0000${url}`;
+}
+
+/** Guard the session cap, naming the offender and what to do about it. */
+function checkSessionCap(kind: string, live: number, name: string): void {
+  if (live < MAX_PERSISTENT_SESSIONS) return;
+  throw new Error(
+    `too many ${kind} sessions: ${MAX_PERSISTENT_SESSIONS} are already open and "${name}" would be another. ` +
+      `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
+      `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`,
+  );
+}
+
 async function newHolder(
   width: number,
   height: number,
@@ -1395,53 +1436,61 @@ async function attachReset(holder: ViewHolder): Promise<void> {
 }
 
 /**
- * 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.
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
  */
 export async function acquirePersistentBrowser(
+  name = "",
   opts: BrowserOptions = {},
 ): Promise<PersistentBrowser> {
   const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
-  let attached = true;
-  if (!SHARED_BROWSER) {
-    attached = false;
-    SHARED_BROWSER = await newHolder(
+  let holder = SHARED_BROWSERS.get(name);
+  const attached = holder !== undefined;
+  if (holder) {
+    await attachReset(holder);
+  } else {
+    checkSessionCap("browser", SHARED_BROWSERS.size, name);
+    holder = await newHolder(
       device ? device.viewport.width : opts.width ?? 1280,
       device ? device.viewport.height : opts.height ?? 720,
       device,
     );
-  } else {
-    await attachReset(SHARED_BROWSER);
+    SHARED_BROWSERS.set(name, holder);
   }
-  const holder = SHARED_BROWSER;
-  const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+  const view = holder;
+  const { backend, detach } = buildBackend(view, opts.recorder ?? null, {
     persistent: true,
     onDestroy: () => {
-      if (SHARED_BROWSER === holder) SHARED_BROWSER = null;
+      if (SHARED_BROWSERS.get(name) === view) SHARED_BROWSERS.delete(name);
     },
   });
   // Fresh session only: an attached view already carries the init script on
   // its (forked) holder, and first-call-wins means a later call's options
   // don't retroactively apply.
   if (!attached && opts.initScript !== undefined) {
-    await installInitScript(holder, opts.initScript);
+    await installInitScript(view, opts.initScript);
   }
   if (!attached && opts.url !== undefined) await backend.goto(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.
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
  */
 export async function acquirePersistentMobileBackend(
   url: string,
+  name: string,
   recorder: BrowserSessionRecorder | null,
   initScript?: string,
 ): Promise<PersistentBrowser> {
-  const existing = SHARED_MOBILE.get(url);
+  const key = mobileKey(name, url);
+  const existing = SHARED_MOBILE.get(key);
+  if (!existing) checkSessionCap("mobile", SHARED_MOBILE.size, name);
   const holder =
     existing ??
     (await newHolder(
@@ -1452,12 +1501,12 @@ export async function acquirePersistentMobileBackend(
   if (existing) {
     await attachReset(holder);
   } else {
-    SHARED_MOBILE.set(url, holder);
+    SHARED_MOBILE.set(key, holder);
   }
   const { backend, detach } = buildBackend(holder, recorder, {
     persistent: true,
     onDestroy: () => {
-      if (SHARED_MOBILE.get(url) === holder) SHARED_MOBILE.delete(url);
+      if (SHARED_MOBILE.get(key) === holder) SHARED_MOBILE.delete(key);
     },
   });
   if (!existing) {
@@ -1549,6 +1598,18 @@ function buildBackend(
   // missing from the chunk we're about to drain (see `drainExpr`).
   let lastDrainUrl: string | null = null;
 
+  /** Session provenance stamped on every recorded op: which replay player
+   *  the step belongs to, which named browser it acted on, and where in
+   *  the player to seek (`endT`, in rrweb's clock). */
+  function sessionFields(endT: number): Record<string, unknown> {
+    if (!recorder) return {};
+    return {
+      sessionId: recorder.sessionId,
+      sessionTimestamp: endT,
+      ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
+    };
+  }
+
   async function drain(action: BrowserAction | "close"): Promise<void> {
     if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
@@ -1595,9 +1656,7 @@ function buildBackend(
       const seq = recordBrowser({
         action,
         ...fields,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-          : {}),
+        ...sessionFields(endT),
         durationMs: endT - t,
       }, resv);
       await drain(action);
@@ -1614,9 +1673,7 @@ function buildBackend(
       recordBrowser({
         action,
         ...fields,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-          : {}),
+        ...sessionFields(endT),
         durationMs: endT - t,
         error: e?.message ?? String(err),
       }, resv);
@@ -1988,9 +2045,7 @@ function buildBackend(
       const seq = recordBrowser({
         action,
         ...fields,
-        ...(recorder
-          ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-          : {}),
+        ...sessionFields(endT),
         durationMs: waitedMs,
         ...(error ? { error } : {}),
       }, reserveBackdated(waitedMs));

package/src/daemon.ts

@@ -34,7 +34,7 @@ import {
   proxy as makeProxyDecl,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
-import { acquirePersistentBrowser } from "./browser.js";
+import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
@@ -3191,6 +3191,13 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
 /** Per-Browser rrweb session shipped to the control plane. */
 interface BrowserSessionRecord {
   sessionId: string;
+  /** Author-given session name — `ctx.browser("alice")` / `ctx.mobile(app,
+   * "alice")`. Absent for the default unnamed session, which is what makes
+   * a single-browser case render with no naming chrome at all. The
+   * dashboard labels this session's replay stage with it, and the step
+   * list badges each op with the same name (off the event, not this
+   * record). */
+  name?: string;
   openedAtMs: number;
   closedAtMs?: number;
   initialUrl?: string;
@@ -3277,6 +3284,23 @@ function newArtifactCollector(): {
   };
 }
 
+/**
+ * Normalise `ctx.browser(...)`'s two call shapes — `(opts?)` for the
+ * default session and `(name, opts?)` for a named one — into the
+ * `(name, opts)` pair the session registry keys on. The overloads make
+ * these the only two shapes that typecheck, but the implementation still
+ * has to tell them apart at runtime: an untyped caller (`eval`, plain JS)
+ * reaches the same function.
+ */
+function browserArgs(
+  nameOrOpts?: string | BrowserOptions,
+  opts?: BrowserOptions,
+): { name: string; opts: BrowserOptions | undefined } {
+  return typeof nameOrOpts === "string"
+    ? { name: nameOrOpts, opts }
+    : { name: "", opts: nameOrOpts };
+}
+
 /**
  * Build the recorder sink + bookkeeping for a single Browser session.
  * The returned `recorder` is what `openBrowser` writes into; the
@@ -3290,6 +3314,7 @@ function newBrowserSession(
   idScope: string,
   frame: "browser" | "mobile" = "browser",
   artifacts?: ReturnType<typeof newArtifactCollector>,
+  name = "",
 ): {
   recorder: BrowserSessionRecorder;
   record: BrowserSessionRecord;
@@ -3299,6 +3324,10 @@ function newBrowserSession(
     sessionId: newSessionId(idScope),
     openedAtMs: Date.now() - testStart,
     frame,
+    // Omit the key entirely for the default session rather than storing
+    // `""` — every consumer treats "no name" as "don't render a label",
+    // and an empty string would have to be special-cased in each of them.
+    ...(name ? { name } : {}),
     steps: [],
   };
   let closed = false;
@@ -3306,6 +3335,7 @@ function newBrowserSession(
     record,
     recorder: {
       sessionId: record.sessionId,
+      ...(name ? { sessionName: name } : {}),
       recordStep(step) {
         if (closed) return;
         record.steps.push(step);
@@ -4356,30 +4386,39 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   const parentId = testCase.dependsOn?.id;
   const parent = parentId !== undefined ? TEST_DATA.get(parentId) : undefined;
 
-  // 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
+  // Browser/mobile sessions are PERSISTENT and keyed by NAME:
+  // `ctx.browser(name?)` acquires the desktop browser called `name` and
+  // `ctx.mobile(app, name?)` that name's session for that app (browser.ts's
+  // module-scoped registry, which forks with the snapshot like fake state).
+  // The default name is `""`, so an unnamed project has exactly the one
+  // session per device it always had. 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.
+  // children resume the live pages (cookies, localStorage, signed-in SPA
+  // state) instead of re-navigating; that inheritance is per name, so a
+  // parent that signed "alice" and "bob" in hands both down. Each test
+  // still gets its own session record per name (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
+  // calls for the SAME name return the same handle (memoized below) so one
+  // test = one session per (device, name). An explicit `.close()` destroys
+  // that name's instance — its memo entry is cleared so a later call for
+  // the same name starts fresh, and other names are untouched.
   const browserDetaches: Array<() => Promise<void>> = [];
   const sessions: Array<ReturnType<typeof newBrowserSession>> = [];
-  let sharedBrowser: Browser | null = null;
+  const sharedBrowsers = new Map<string, Browser>();
   const sharedMobiles = new Map<string, Mobile>();
-  const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
-    if (sharedBrowser) return sharedBrowser;
-    const session = newBrowserSession(start, testCase.id);
+  const trackedOpenBrowser = async (
+    nameOrOpts?: string | BrowserOptions,
+    maybeOpts?: BrowserOptions,
+  ): Promise<Browser> => {
+    const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+    const memo = sharedBrowsers.get(name);
+    if (memo) return memo;
+    const session = newBrowserSession(start, testCase.id, "browser", undefined, name);
     sessions.push(session);
-    const { browser, attached, detach } = await acquirePersistentBrowser({
+    const { browser, attached, detach } = await acquirePersistentBrowser(name, {
       ...(opts ?? {}),
       recorder: session.recorder,
     });
@@ -4398,23 +4437,25 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     const innerClose = browser.close.bind(browser);
     browser.close = async () => {
       await innerClose();
-      if (sharedBrowser === browser) sharedBrowser = null;
+      if (sharedBrowsers.get(name) === browser) sharedBrowsers.delete(name);
     };
-    sharedBrowser = browser;
+    sharedBrowsers.set(name, browser);
     return browser;
   };
-  const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
+  const trackedOpenMobile = async (app: MobileApp, name = ""): Promise<Mobile> => {
     if (!isMobileApp(app)) {
       throw new Error(
         "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);
+    const key = mobileKey(name, app.url);
+    const existing = sharedMobiles.get(key);
     if (existing) return existing;
-    const session = newBrowserSession(start, testCase.id, "mobile");
+    const session = newBrowserSession(start, testCase.id, "mobile", undefined, name);
     sessions.push(session);
     const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
       url: app.url,
+      name,
       recorder: session.recorder,
       initScript: app.initScript,
     });
@@ -4429,9 +4470,9 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     const innerClose = mobile.close.bind(mobile);
     mobile.close = async () => {
       await innerClose();
-      if (sharedMobiles.get(app.url) === mobile) sharedMobiles.delete(app.url);
+      if (sharedMobiles.get(key) === mobile) sharedMobiles.delete(key);
     };
-    sharedMobiles.set(app.url, mobile);
+    sharedMobiles.set(key, mobile);
     return mobile;
   };
 
@@ -4840,13 +4881,18 @@ async function evalCode(
   // Eval-only artifact sink — wiring it here (and nowhere in runOne) is
   // what gates screenshot() to eval context.
   const artifactCollector = newArtifactCollector();
-  let sharedBrowser: Browser | null = null;
+  const sharedBrowsers = new Map<string, Browser>();
   const sharedMobiles = new Map<string, Mobile>();
-  const trackedOpenBrowser = async (opts?: BrowserOptions): Promise<Browser> => {
-    if (sharedBrowser) return sharedBrowser;
-    const session = newBrowserSession(start, "eval", "browser", artifactCollector);
+  const trackedOpenBrowser = async (
+    nameOrOpts?: string | BrowserOptions,
+    maybeOpts?: BrowserOptions,
+  ): Promise<Browser> => {
+    const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+    const memo = sharedBrowsers.get(name);
+    if (memo) return memo;
+    const session = newBrowserSession(start, "eval", "browser", artifactCollector, name);
     sessions.push(session);
-    const { browser, attached, detach } = await acquirePersistentBrowser({
+    const { browser, attached, detach } = await acquirePersistentBrowser(name, {
       ...(opts ?? {}),
       recorder: session.recorder,
     });
@@ -4863,23 +4909,25 @@ async function evalCode(
     const innerClose = browser.close.bind(browser);
     browser.close = async () => {
       await innerClose();
-      if (sharedBrowser === browser) sharedBrowser = null;
+      if (sharedBrowsers.get(name) === browser) sharedBrowsers.delete(name);
     };
-    sharedBrowser = browser;
+    sharedBrowsers.set(name, browser);
     return browser;
   };
-  const trackedOpenMobile = async (app: MobileApp): Promise<Mobile> => {
+  const trackedOpenMobile = async (app: MobileApp, name = ""): Promise<Mobile> => {
     if (!isMobileApp(app)) {
       throw new Error(
         "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);
+    const key = mobileKey(name, app.url);
+    const existing = sharedMobiles.get(key);
     if (existing) return existing;
-    const session = newBrowserSession(start, "eval", "mobile", artifactCollector);
+    const session = newBrowserSession(start, "eval", "mobile", artifactCollector, name);
     sessions.push(session);
     const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
       url: app.url,
+      name,
       recorder: session.recorder,
       initScript: app.initScript,
     });
@@ -4894,9 +4942,9 @@ async function evalCode(
     const innerClose = mobile.close.bind(mobile);
     mobile.close = async () => {
       await innerClose();
-      if (sharedMobiles.get(app.url) === mobile) sharedMobiles.delete(app.url);
+      if (sharedMobiles.get(key) === mobile) sharedMobiles.delete(key);
     };
-    sharedMobiles.set(app.url, mobile);
+    sharedMobiles.set(key, mobile);
     return mobile;
   };
 

package/src/index.ts

@@ -1405,20 +1405,57 @@ export interface TestContext<
   /**
    * 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).
+   * There is one persistent browser PER NAME, and `ctx.browser()` is the
+   * default (unnamed) one: every 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).
+   *
+   * For a second, independent browser — a second user — name it:
+   * `ctx.browser("alice")`. See the named overload.
    *
    * `.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>;
+  /**
+   * Open the persistent browser called `name`, creating it on first use.
+   * Each name is its own browser — its own cookies, localStorage and page —
+   * so naming them is how one test drives two users.
+   *
+   * **Only name a browser when the test needs two or more isolated sessions
+   * at once.** Otherwise use `ctx.browser()`: a name is a second identity,
+   * not a label, and a lone `ctx.browser("main")` buys nothing over the
+   * default while adding its name to every step title in the dashboard.
+   *
+   * ```ts
+   * const alice = await ctx.browser("alice", { url: "https://app.test" });
+   * const bob = await ctx.browser("bob", { url: "https://app.test" });
+   * await alice.getByRole("button", { name: "Share" }).click();
+   * await bob.reload();
+   * await expect(bob.getByText("Shared with you")).toBeVisible();
+   * ```
+   *
+   * Every rule of the default browser applies per name: the session rides
+   * the snapshot, so a `dependsOn` child inherits *each* named browser
+   * exactly where its parent left it (sign both users in once, in the
+   * parent); repeat calls with the same name in one test return the same
+   * handle; the first call for a name wins its options; `.close()` discards
+   * only that name. Sessions are named for the roles under test, not per
+   * row of data — each one is a live browser captured in every snapshot
+   * from here on, and opening too many is an error.
+   *
+   * The dashboard titles each step with the browser that performed it
+   * (`bob: click "Share"`) and labels the replay with the same name, so a
+   * two-user timeline stays readable and selecting a step shows that
+   * browser's session.
+   */
+  browser(name: string, opts?: BrowserOptions): Promise<Browser>;
   /**
    * Open a phone-emulated session for a mobile app and return a {@link Mobile}
    * handle already pointed at it — no `navigate`. Pass the app handle a
@@ -1437,13 +1474,18 @@ export interface TestContext<
    * The session emulates the latest iPhone (viewport + DPR + mobile UA +
    * 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;
+   * Sessions are persistent, one per app per `name`: 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.
+   *
+   * Pass a `name` for a second phone running the same app — two users in
+   * one test: `ctx.mobile(ctx.svc.app, "alice")`. Names are independent
+   * sessions and are inherited per name by `dependsOn` children, exactly
+   * like named desktop browsers.
    */
-  mobile(app: MobileApp): Promise<Mobile>;
+  mobile(app: MobileApp, name?: string): Promise<Mobile>;
   /** The test's display name. */
   readonly testName: string;
   /**

package/src/mobile.ts

@@ -99,14 +99,18 @@ export async function openMobile(opts: {
 }
 
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). 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.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` 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;
+  /** Session name — `""` (the default) is the unnamed session every
+   *  `ctx.mobile(app)` call shares. Two names on one app are two phones. */
+  name?: string;
   recorder: BrowserSessionRecorder | null;
   /** Installed before the fresh session's first navigation (ignored on an
    *  attached session, which already carries it on the forked holder). */
@@ -121,6 +125,7 @@ export async function openPersistentMobile(opts: {
 }> {
   const { browser, attached, detach } = await acquirePersistentMobileBackend(
     opts.url,
+    opts.name ?? "",
     opts.recorder,
     opts.initScript,
   );

package/src/recorder.ts

@@ -429,6 +429,16 @@ export interface BrowserEvent extends BaseEvent {
    * with a `BrowserSessionRecorder` attached (the daemon always does).
    */
   sessionId?: string;
+  /**
+   * Author-given name of that session — `ctx.browser("alice")` — absent
+   * for the default unnamed browser, so a single-browser test's steps
+   * carry no name and render exactly as they always have. Present, it is
+   * what the step list badges to say which browser acted. Duplicated here
+   * rather than resolved from the session record because the CLI's
+   * failure detail renders from persisted events alone, with no replay
+   * bundle to look the session up in.
+   */
+  sessionName?: string;
   /**
    * Wall-clock `Date.now()` captured at the moment this op *finished*.
    * Lives in the same time base as rrweb's `event.timestamp` fields,