@specific.dev/spectest 0.41.0 → 0.44.0

package/src/components/google.ts

@@ -0,0 +1,104 @@
+// `google()` — Google, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with Google: OpenID Connect discovery, the account
+// picker, PKCE, the token exchange, refresh, and userinfo. The component is
+// named for the provider rather than for the feature, because the backing
+// emulator also carries Gmail, Calendar and Drive — claiming
+// `gmail.googleapis.com` and routing it here is a table entry, not a new
+// design.
+
+import type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import {
+  emulatorService,
+  familyName,
+  givenName,
+  oauthClients,
+  resolveUsers,
+} from "./emulate/service.js";
+
+export type GoogleOptions = ProviderOptions;
+
+function spec(users: ProviderUser[], opts: GoogleOptions): ProviderSpec {
+  return {
+    name: "google",
+    module: "@emulators/google",
+    pluginExport: "googlePlugin",
+    baseUrl: "https://accounts.google.com",
+    hosts: [
+      "accounts.google.com",
+      "oauth2.googleapis.com",
+      "www.googleapis.com",
+      "openidconnect.googleapis.com",
+    ],
+    discovery: {
+      issuer: "https://accounts.google.com",
+      authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+      token_endpoint: "https://oauth2.googleapis.com/token",
+      userinfo_endpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+      revocation_endpoint: "https://oauth2.googleapis.com/revoke",
+      jwks_uri: "https://www.googleapis.com/oauth2/v3/certs",
+    },
+    jwksPath: "^/oauth2/v3/certs$",
+    rewrites: [
+      // oauth2.googleapis.com serves these at the root; the emulator puts
+      // them under /oauth2.
+      { from: "^/token$", to: "/oauth2/token" },
+      { from: "^/revoke$", to: "/oauth2/revoke" },
+      // openidconnect.googleapis.com and the v3 alias both mean userinfo.
+      { from: "^/v1/userinfo$", to: "/oauth2/v2/userinfo" },
+      { from: "^/oauth2/v3/userinfo$", to: "/oauth2/v2/userinfo" },
+    ],
+    fallbackUser: { login: users[0]!.email, id: 1, scopes: ["openid", "email", "profile"] },
+    seed: {
+      users: users.map((u) => ({
+        email: u.email,
+        name: u.name,
+        given_name: givenName(u),
+        family_name: familyName(u),
+        picture: u.picture,
+        email_verified: true,
+      })),
+      ...oauthClients(opts.client),
+    },
+  };
+}
+
+/**
+ * Google, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { google } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   // Accounts default to Alice and Bob Example; declare `users` to
+ *   // choose your own. A `client` makes the environment validate the
+ *   // app's client id, secret and callback URL.
+ *   google: google({
+ *     client: {
+ *       clientId: "1234.apps.googleusercontent.com",
+ *       clientSecret: "GOCSPX-test",
+ *       redirectUris: ["https://app.test/callback/google"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["google"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://accounts.google.com/o/oauth2/v2/auth`, exchanges the code at
+ * `https://oauth2.googleapis.com/token`, and verifies the id_token against
+ * `https://www.googleapis.com/oauth2/v3/certs`, exactly as it does live.
+ *
+ * A test signs in the way a user does, through the browser:
+ *
+ * ```ts
+ * await page.getByTestId("login-google").click();
+ * await page.getByTestId("spectest-user-alice@example.com").click();
+ * ```
+ */
+export function google(opts: GoogleOptions = {}) {
+  const users = resolveUsers("google", opts.users);
+  return emulatorService(spec(users, opts));
+}

package/src/components/index.ts

@@ -62,6 +62,20 @@ export {
   type AwsOptions,
   type LambdaOptions,
 } from "./aws.js";
+// Third-party providers, each answering at its own real endpoints. Named
+// for the provider rather than for sign-in, because each one's surface can
+// grow past auth (Gmail and Calendar for `google`, the REST API for
+// `github`, Graph for `microsoft`).
+export {
+  type ProviderOptions,
+  type ProviderUser,
+  type OAuthClient,
+} from "./emulate/service.js";
+export { google, type GoogleOptions } from "./google.js";
+export { github, type GithubOptions } from "./github.js";
+export { apple, type AppleOptions } from "./apple.js";
+export { microsoft, type MicrosoftOptions } from "./microsoft.js";
+export { okta, type OktaOptions } from "./okta.js";
 export {
   replayFake,
   type ReplayFakeOptions,

package/src/components/microsoft.ts

@@ -0,0 +1,89 @@
+// `microsoft()` — Microsoft, emulated inside the environment, answering at
+// its real endpoints.
+//
+// Today that is Sign in with Microsoft (Entra ID) plus the part of Graph an
+// app reads straight after: discovery, the account picker, the token
+// exchange, `/oidc/userinfo` and `/v1.0/me`. The component is named for the
+// provider rather than for the feature — Graph is already claimed, and
+// widening what it serves is a table entry.
+
+import type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import { emulatorService, oauthClients, resolveUsers } from "./emulate/service.js";
+
+export interface MicrosoftOptions extends ProviderOptions {
+  /**
+   * Directory (tenant) the app signs in against — whatever its authority
+   * URL uses. It appears in the issuer and in every endpoint path, so a
+   * client that checks the issuer sees what it expects. Default `"common"`.
+   */
+  tenantId?: string;
+}
+
+function spec(users: ProviderUser[], opts: MicrosoftOptions): ProviderSpec {
+  const authority = `https://login.microsoftonline.com/${opts.tenantId || "common"}`;
+  return {
+    name: "microsoft",
+    module: "@emulators/microsoft",
+    pluginExport: "microsoftPlugin",
+    baseUrl: "https://login.microsoftonline.com",
+    hosts: ["login.microsoftonline.com", "graph.microsoft.com"],
+    // The emulator has no tenant, so its issuer is the bare host. A client
+    // that checks the issuer against the authority it configured would
+    // reject that; the re-issue step corrects it.
+    issuer: `${authority}/v2.0`,
+    discovery: {
+      issuer: `${authority}/v2.0`,
+      authorization_endpoint: `${authority}/oauth2/v2.0/authorize`,
+      token_endpoint: `${authority}/oauth2/v2.0/token`,
+      jwks_uri: `${authority}/discovery/v2.0/keys`,
+      end_session_endpoint: `${authority}/oauth2/v2.0/logout`,
+      userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo",
+    },
+    jwksPath: "^/discovery/v2\\.0/keys$",
+    rewrites: [
+      // Real Entra paths carry the tenant; the emulator's do not. The
+      // discovery route is the exception — it handles the tenant itself.
+      { from: "^/[^/]+/(oauth2/v2\\.0/.*)$", to: "/$1" },
+      { from: "^/[^/]+/(discovery/v2\\.0/keys)$", to: "/$1" },
+    ],
+    fallbackUser: {
+      login: users[0]!.email,
+      id: 1,
+      scopes: ["openid", "email", "profile", "User.Read"],
+    },
+    seed: {
+      users: users.map((u) => ({ email: u.email, name: u.name })),
+      ...oauthClients(opts.client),
+    },
+  };
+}
+
+/**
+ * Microsoft, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { microsoft } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   microsoft: microsoft({
+ *     tenantId: "11111111-2222-3333-4444-555555555555",
+ *     users: [{ email: "bob@example.com", name: "Bob Example" }],
+ *     client: {
+ *       clientId: "6f1a2b3c-…",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/microsoft"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["microsoft"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration`,
+ * and the account read back from `https://graph.microsoft.com/v1.0/me`.
+ */
+export function microsoft(opts: MicrosoftOptions = {}) {
+  const users = resolveUsers("microsoft", opts.users);
+  return emulatorService(spec(users, opts));
+}

package/src/components/okta.ts

@@ -0,0 +1,93 @@
+// `okta()` — Okta, emulated inside the environment, answering at your org's
+// real domain.
+//
+// Today that is Okta sign-in: discovery, the account picker, the token
+// exchange, userinfo, introspection and revocation, on both the org
+// authorization server (`/oauth2/v1/…`) and a custom one
+// (`/oauth2/default/…`). The component is named for the provider rather
+// than for the feature — the backing emulator also carries the users,
+// groups and apps management API.
+//
+// Okta has no fixed hostname: every organization gets its own domain, so
+// `domain` is required where the other providers need nothing.
+
+import type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import {
+  emulatorService,
+  familyName,
+  givenName,
+  oauthClients,
+  resolveUsers,
+} from "./emulate/service.js";
+
+export interface OktaOptions extends ProviderOptions {
+  /** The org's domain, e.g. `"dev-12345.okta.com"`. */
+  domain: string;
+}
+
+/** Okta's picker identifies an account by its opaque Okta id, so the id has
+ *  to be seeded rather than generated — otherwise nothing on the page can be
+ *  mapped back to an address. */
+function oktaId(email: string): string {
+  return `u-${email.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
+}
+
+function spec(users: ProviderUser[], opts: OktaOptions): ProviderSpec {
+  const domain = opts.domain.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+  return {
+    name: "okta",
+    module: "@emulators/okta",
+    pluginExport: "oktaPlugin",
+    baseUrl: `https://${domain}`,
+    hosts: [domain],
+    // Okta's issuer is per authorization server and the emulator already
+    // builds it from the base URL, which here is the real org domain.
+    jwksPath: "^/oauth2/(?:[^/]+/)?v1/keys$",
+    aliases: Object.fromEntries(users.map((u) => [oktaId(u.email), u.email])),
+    fallbackUser: { login: users[0]!.email, id: 1, scopes: ["openid", "profile", "email"] },
+    seed: {
+      users: users.map((u) => ({
+        okta_id: oktaId(u.email),
+        // An Okta login is the address, not the GitHub-style handle that
+        // `login` carries — it comes back as `preferred_username`.
+        login: u.email,
+        email: u.email,
+        first_name: givenName(u),
+        last_name: familyName(u),
+        display_name: u.name,
+      })),
+      ...oauthClients(opts.client),
+    },
+  };
+}
+
+/**
+ * Okta, answering at your org's real domain. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { okta } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   okta: okta({
+ *     domain: "dev-12345.okta.com",
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "0oaexample",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/okta"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["okta"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://dev-12345.okta.com/.well-known/openid-configuration`, and
+ * everything it names.
+ */
+export function okta(opts: OktaOptions) {
+  const users = resolveUsers("okta", opts.users);
+  if (!opts.domain) throw new Error("okta(): `domain` is required (e.g. \"dev-12345.okta.com\")");
+  return emulatorService(spec(users, opts));
+}

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;
   /**