@specific.dev/spectest 0.39.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/components/supabase.d.ts

@@ -50,17 +50,19 @@ export interface SupabaseOptions {
      */
     hostname?: string;
     /**
-     * Capture GoTrue's outgoing mail (magic links, OTPs, password recovery,
-     * invites — and signup confirmations with `autoconfirm: false`) with the
-     * standard `email()` component. **On by default**: the stack includes the
-     * capture server (`<name>-mail`) with GoTrue's SMTP wired at it, and tests
-     * read the mailbox through the typed helpers at `ctx.svc.<name>.mail`
-     * (`lastEmail` / `emails` / `clear`), each captured message rendering
-     * mail-client-style on the dashboard timeline.
+     * Capture GoTrue's outgoing mail (signup confirmations, magic links, OTPs,
+     * password recovery, invites) with the standard `email()` component. **On
+     * by default**: the stack includes the capture server (`<name>-mail`) with
+     * GoTrue's SMTP wired at it, and tests read the mailbox through the typed
+     * helpers at `ctx.svc.<name>.mail` (`lastEmail` / `emails` / `clear`), each
+     * captured message rendering mail-client-style on the dashboard timeline.
      *
-     * Signups stay one-step by default (`autoconfirm: true`) so the mailbox is
-     * purely additive; pass `{ autoconfirm: false }` to test real
-     * email-confirmation flows. Pass `{ service: "<key>" }` to point GoTrue at
+     * Signups complete in **one step** by default (`autoconfirm: true`), so
+     * the mailbox is purely additive and a suite that just needs accounts
+     * writes nothing extra. Pass `{ autoconfirm: false }` to run the real
+     * confirmation flow instead — the signup then issues no session until a
+     * test follows the emailed link out of the mailbox. Pass
+     * `{ service: "<key>" }` to point GoTrue at
      * an `email()` service the environment already declares — keep a single
      * mailbox per environment rather than one per component: if the app under
      * test also sends mail, share one `email()` between it and Supabase
@@ -81,24 +83,75 @@ export interface SupabaseOptions {
         serviceRole?: string[];
     };
     /**
-     * Auto-apply SQL migrations found in the project before any dependent service
-     * starts. `true` (default) applies every `*.sql` under `supabase/migrations/`
-     * (sorted, the Supabase convention), then `supabase/seed.sql` if present — a
-     * no-op when the directory is absent. Pass a string to point at a different
-     * directory (relative to the project root or absolute), or `false` to skip.
-     * An *explicitly configured* path that doesn't resolve is an error at env
-     * start (a silent no-op there surfaces much later as a confusing
-     * `relation … does not exist`).
+     * Where the project's SQL migrations live, e.g. `"supabase/migrations"`
+     * (relative to the project root, or absolute). **Nothing is applied unless
+     * you set this** — there is no assumed path, so a project whose schema
+     * arrives some other way (an app that migrates itself at boot, a dump
+     * restored in `setup`) never gets a second, surprising source of DDL.
+     *
+     * Every `*.sql` directly in the directory is applied in sorted filename
+     * order, then — the standard Supabase layout — the **`seed.sql` beside
+     * that directory**, if there is one:
+     *
+     * ```
+     * supabase/
+     *   migrations/0001_init.sql   ← applied, sorted
+     *   migrations/0002_todos.sql
+     *   seed.sql                   ← applied last
+     * ```
+     *
+     * It all runs **once the whole stack is up** — the same point `supabase db
+     * reset` applies migrations — so your SQL may use schema the services
+     * create when they boot (`storage.buckets`, the modern `auth.*` tables).
+     * PostgREST's schema cache is reloaded afterwards.
+     *
+     * A path that doesn't resolve is an error at env start; a silent no-op
+     * there surfaces much later as a confusing `relation … does not exist`.
      * Because `supabase/**` is project content, editing a migration correctly
      * forces a cold rebuild and re-apply (unlike `spectest/tests/**`).
      */
-    migrations?: boolean | string;
+    migrations?: string;
     /**
-     * Seed SQL applied after migrations. `true` (default) applies
-     * `supabase/seed.sql` if it exists; a string overrides the path; `false`
-     * skips it.
+     * Where the project's **edge functions** live, e.g.
+     * `"supabase/functions"` — one subdirectory per function, each with an
+     * entrypoint the runtime can serve (`supabase/functions/hello/index.ts`).
+     *
+     * **Nothing runs unless you set this.** Point at the directory and every
+     * function in it is served on the real Supabase edge runtime at
+     * `<url>/functions/v1/<name>` through the gateway — the same path
+     * `supabase.functions.invoke(...)` derives, so the app under test needs no
+     * override. Leave it unset and the runtime is left out of the stack
+     * entirely, along with the gateway's `/functions/v1` route.
+     *
+     * Function code is read straight from the repo — nothing is copied or
+     * bundled — so editing a function is an ordinary project edit.
+     *
+     * Pass an object instead of a path to turn JWT verification off, or to set
+     * the function secrets your code reads with `Deno.env.get(...)`.
      */
-    seed?: boolean | string;
+    functions?: string | SupabaseFunctionsOptions;
+}
+/** Tuning for `SupabaseOptions.functions`. */
+export interface SupabaseFunctionsOptions {
+    /**
+     * Directory holding one subdirectory per function, relative to the project
+     * root (or absolute). Required — there is no assumed location.
+     */
+    dir: string;
+    /**
+     * Reject a call that carries no valid JWT, exactly as hosted Supabase
+     * does. Default `true` — so a test that forgets the `Authorization`
+     * header fails here instead of in production. Set `false` for the
+     * `--no-verify-jwt` behaviour (webhooks, public endpoints).
+     */
+    verifyJwt?: boolean;
+    /**
+     * Extra environment variables the functions read (`Deno.env.get("…")`) —
+     * the local stand-in for function secrets. `SUPABASE_URL`,
+     * `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_DB_URL` and
+     * `JWT_SECRET` are already set for you.
+     */
+    env?: Record<string, string>;
 }
 /** Tuning for `SupabaseOptions.mail`. */
 export interface SupabaseMailOptions {
@@ -110,10 +163,17 @@ export interface SupabaseMailOptions {
      */
     service?: string;
     /**
-     * Whether GoTrue autoconfirms signups. `true` (default): signups complete
-     * in one step and send no confirmation mail — recovery, magic-link and OTP
-     * mail is still sent and captured. Set `false` to exercise real
-     * email-confirmation flows (signups require the emailed verification).
+     * Whether GoTrue confirms a signup without the emailed verification.
+     * **`true` by default**: signups complete in one step and send no
+     * confirmation mail, which keeps account creation a single call in the
+     * suites where it is setup rather than the thing under test.
+     *
+     * Set `false` to run the flow a hosted project runs: the signup issues no
+     * session, and the test follows the emailed link out of the mailbox
+     * exactly as a user would (see `examples/supabase-app`). Recovery,
+     * magic-link, OTP and invite mail is sent either way. Forced `true` when
+     * the stack has no mailbox (`mail: false`), since the confirmation would
+     * go nowhere.
      */
     autoconfirm?: boolean;
     /** Sender address GoTrue mails from. Default `admin@example.com`. */