@specific.dev/spectest 0.29.0 → 0.31.0

package/dist/browser.d.ts

@@ -1,4 +1,6 @@
 import type { Wrapped } from "./inspect.js";
+import type { UrlPattern } from "./url-match.js";
+export type { UrlPattern } from "./url-match.js";
 import type { GetByRoleOptions, GetByTextOptions, Locator } from "./locator.js";
 import type { Page } from "playwright-core";
 export interface BrowserOptions {
@@ -141,11 +143,43 @@ export interface Browser {
      * keeps it (the one deviation from Playwright's bare `evaluate`).
      */
     evaluate<T = unknown>(description: string, fn: string | ((arg?: unknown) => T | Promise<T>), arg?: unknown): Promise<Wrapped<T>>;
+    /**
+     * Wait until the page's URL matches `pattern` — Playwright's
+     * `page.waitForURL`. Resolves to the **matched URL** (provenance-wrapped,
+     * so `expect(...)` on it nests under this step), and returns immediately if
+     * the current URL already matches.
+     *
+     * This is the primitive for "the app redirected somewhere": an auth
+     * handoff, an OAuth callback, a post-login bounce. Reach for it instead of
+     * `waitForFunction("…", () => location.href.startsWith(…))` — that polls
+     * *inside* the page, so it races the navigation it's watching for (the
+     * `Execution context was destroyed` flake), misses any URL the browser only
+     * passes through between polls, and needs the destination to run JS at all.
+     * This one is driven by frame-navigation events, so it sees every commit.
+     *
+     * ```ts
+     * const url = await browser.waitForURL("https://api.workos.com/**");
+     * expect(url).toContain("code=");
+     * ```
+     *
+     * `waitUntil` defaults to **`"commit"`**, not Playwright's `"load"`: the
+     * destination is usually somewhere the hermetic VM can't fully load, and
+     * waiting for its load event would time out on exactly the case this
+     * exists for. Pass `"load"`/`"domcontentloaded"` when you own the page and
+     * intend to keep driving it. Timeout defaults to 5 s.
+     */
+    waitForURL(pattern: UrlPattern, options?: {
+        timeout?: number;
+        waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
+    }): Promise<Wrapped<string>>;
     /**
      * Poll `fn` in the page until it returns a truthy value (Playwright's
      * `page.waitForFunction`), recorded as ONE step with the total wait + poll
      * count. `fn` is a function (with optional `arg`) or a string expression.
      * `description` labels the step. Defaults: 5 s timeout, 100 ms polling.
+     *
+     * For "wait until the page navigates somewhere" use {@link waitForURL} —
+     * an in-page poll is the wrong tool for watching a navigation.
      */
     waitForFunction<T = unknown>(description: string, fn: string | ((arg?: unknown) => T), arg?: unknown, options?: {
         timeout?: number;

package/dist/browser.js

@@ -34,7 +34,8 @@ import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { recordBrowser, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
-import { DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
+import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
 import { chromium } from "playwright-core";
 /** Decoded byte count of a base64 string, without decoding it. */
 function base64ByteLength(b64) {
@@ -1213,6 +1214,35 @@ function buildBackend(holder, recorder, buildOpts) {
                 return (await holder.page.evaluate(fn, arg));
             }, { wrap: true });
         },
+        async waitForURL(pattern, options = {}) {
+            const timeoutMs = options.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+            const label = describeUrlPattern(pattern);
+            // `url` is stamped with the MATCHED url once we have it (the timeline
+            // wants where we landed, not the pattern); `description` carries the
+            // pattern so a timed-out step still says what it was waiting for.
+            const fields = { description: label };
+            return instrumented("waitForURL", fields, async () => {
+                try {
+                    // Always a predicate, never playwright's own glob: `matchesUrl`
+                    // is then the single matching implementation shared with
+                    // `expect(browser).toHaveURL`.
+                    await holder.page.waitForURL((u) => matchesUrl(u.href, pattern), {
+                        timeout: timeoutMs,
+                        waitUntil: options.waitUntil ?? "commit",
+                    });
+                }
+                catch (err) {
+                    // Playwright's timeout message is a wall of call-log; ours names
+                    // the pattern and where the page actually sat.
+                    if (err?.name !== "TimeoutError")
+                        throw err;
+                    throw new Error(`waitForURL ${label} timed out after ${timeoutMs}ms (current URL: ${holder.page.url()})`);
+                }
+                const matched = holder.page.url();
+                fields.url = matched;
+                return matched;
+            }, { wrap: true });
+        },
         async waitForFunction(description, fn, arg, options = {}) {
             const timeoutMs = options.timeout ?? 5_000;
             const intervalMs = options.polling ?? 100;
@@ -1397,5 +1427,13 @@ function buildBackend(holder, recorder, buildOpts) {
             return instrumented(action, fields, () => fn(holder.page), opts);
         },
     };
+    // The seam `expect(browser).toHaveURL(...)` polls: a silent URL read plus
+    // the single settled step its assertion nests under — the session twin of
+    // the locator probe, and what brands this object as a browser session for
+    // `expect`'s overload dispatch.
+    attachBrowserProbe(backend, {
+        url: () => holder.page.url(),
+        settle: (action, waitedMs, error) => backend.recordSettled(action, { url: holder.page.url() }, waitedMs, error),
+    });
     return { backend, detach: endRecording };
 }

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./br
 import type { Browser, BrowserOptions } from "./browser.js";
 export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, } from "./locator.js";
 import type { Locator } from "./locator.js";
+export type { UrlPattern } from "./url-match.js";
+import type { UrlPattern } from "./url-match.js";
 export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
@@ -1309,7 +1311,29 @@ export interface LocatorAssertion extends LocatorMatchers {
     /** Negate every matcher (retries until the negated condition holds). */
     not: LocatorMatchers;
 }
+/**
+ * Auto-retrying assertions for a browser/mobile **session** — Playwright's
+ * `expect(page)` matchers. Like the locator ones, they poll until the
+ * condition holds or the deadline elapses (default 5 s) and record one
+ * assertion under a settled browser step.
+ */
+export interface BrowserMatchers {
+    /**
+     * The page's URL matches `expected` — a glob string (`*` within a path
+     * segment, `**` across `/`), a RegExp, or a predicate over the parsed URL.
+     * The settling twin of {@link Browser.waitForURL}: use `waitForURL` when
+     * you want the matched URL back, this when you only mean to assert.
+     */
+    toHaveURL(expected: UrlPattern, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+export interface BrowserAssertion extends BrowserMatchers {
+    /** Negate every matcher (retries until the negated condition holds). */
+    not: BrowserMatchers;
+}
 export declare function expect(actual: Locator, message?: string): LocatorAssertion;
+export declare function expect(actual: Browser, message?: string): BrowserAssertion;
 export declare function expect(actual: Provenanced, message?: string): Expectation;
 /**
  * Assert on a value with **no provenance** — a computed number, a raw

package/dist/index.js

@@ -25,7 +25,8 @@ export { field } from "./inspect.js";
 export { SQL } from "./sql.js";
 export { RedisClient } from "./redis.js";
 export { S3Client } from "./s3.js";
-import { isLocator, getLocatorProbe, DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
+import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
+import { describeUrlPattern, matchesUrl } from "./url-match.js";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
@@ -458,6 +459,8 @@ export class ExpectationError extends Error {
 export function expect(actual, message) {
     if (isLocator(actual))
         return buildLocatorAssertion(actual, message);
+    if (isBrowserSession(actual))
+        return buildBrowserAssertion(actual, message);
     return expectValue(actual, message);
 }
 function expectValue(actual, message) {
@@ -593,6 +596,58 @@ function buildLocatorMatchers(loc, negated, message) {
         }, () => `expected ${probe.label}${not} to be checked`),
     };
 }
+// ── expect(browser): auto-retrying session matchers ───────────────────────
+function buildBrowserAssertion(session, message) {
+    return Object.assign(buildBrowserMatchers(session, false, message), {
+        not: buildBrowserMatchers(session, true, message),
+    });
+}
+function buildBrowserMatchers(session, negated, message) {
+    const probe = getBrowserProbe(session);
+    const not = negated ? " not" : "";
+    return {
+        toHaveURL: async (expected, opts) => {
+            const started = Date.now();
+            const deadline = started + (opts?.timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+            // `probe.url()` is a synchronous unrecorded read, so the poll costs
+            // nothing and emits nothing — one settled step at the end, exactly like
+            // the locator matchers.
+            const label = describeUrlPattern(expected);
+            for (;;) {
+                const actual = probe.url();
+                if (matchesUrl(actual, expected) !== negated) {
+                    const sourceSeq = await probe.settle("toHaveURL", Date.now() - started);
+                    recordAssertion({
+                        matcher: "toHaveURL",
+                        negated,
+                        passed: true,
+                        actual: safeSerialize(actual),
+                        expected: label,
+                        message,
+                        sourceSeq,
+                    });
+                    return;
+                }
+                if (Date.now() >= deadline) {
+                    const msg = `expected page URL${not} to match ${label}, got ${fmt(actual)}`;
+                    const sourceSeq = await probe.settle("toHaveURL", Date.now() - started, msg);
+                    recordAssertion({
+                        matcher: "toHaveURL",
+                        negated,
+                        passed: false,
+                        actual: safeSerialize(actual),
+                        expected: label,
+                        error: msg,
+                        message,
+                        sourceSeq,
+                    });
+                    throw new ExpectationError(msg);
+                }
+                await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
+            }
+        },
+    };
+}
 /**
  * Assert on a value with **no provenance** — a computed number, a raw
  * WebSocket frame, anything that didn't flow from a recorded op. `message` is

package/dist/locator.d.ts

@@ -141,6 +141,24 @@ export interface LocatorProbe {
      *  `undefined` when nothing is recording. */
     settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
 }
+/** Silent (non-recorded) reads an `expect(browser)` matcher polls — the
+ *  session twin of {@link LocatorProbe}. Lives here, next to it, so `index.ts`
+ *  can reach both seams without importing `browser.ts` (and with it
+ *  playwright) at runtime. */
+export interface BrowserProbe {
+    /** Current main-frame URL. Synchronous, unrecorded, no rrweb drain. */
+    url(): string;
+    /** After the silent poll settles, emit the single settled browser step the
+     *  matcher's assertion nests under, and return its seq. Same contract as
+     *  {@link LocatorProbe.settle}. */
+    settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+}
+/** Brand a browser/mobile session with its {@link BrowserProbe}. */
+export declare function attachBrowserProbe<T extends object>(session: T, probe: BrowserProbe): T;
+/** True if `x` is a spectest browser/mobile session (i.e. probe-branded). */
+export declare function isBrowserSession(x: unknown): boolean;
+/** The probe branded onto a browser/mobile session by `buildBackend`. */
+export declare function getBrowserProbe(session: unknown): BrowserProbe;
 /** The silent-read probe for a locator — the seam `expect(locator)` matchers
  *  poll (in index.ts) without pulling playwright types or the backend into
  *  that module. */
@@ -150,11 +168,12 @@ export declare function getLocatorProbe(loc: Locator): LocatorProbe;
 export interface ActionStrategy {
     /** Whether this session supports touch. Desktop → `tap()` throws. */
     readonly touch: boolean;
-    /** Perform a touch tap on the resolved element (mobile only). */
+    /** Perform a touch tap on the resolved element (mobile only). `rec` is the
+     *  gesture's own step, still open — see {@link stampActionPoint}. */
     tap(backend: LocatorBackend, loc: PWLocator, opts?: {
         timeout?: number;
         duration?: number;
-    }): Promise<void>;
+    }, rec?: Partial<RecordableFields>): Promise<void>;
 }
 /** Desktop: no touchscreen. `tap()` is a mobile gesture — steer authors to
  *  `click()`. */

package/dist/locator.js

@@ -164,6 +164,20 @@ export function chainLabel(chain) {
     return out;
 }
 const PROBE = Symbol.for("spectest.locatorProbe");
+const BROWSER_PROBE = Symbol.for("spectest.browserProbe");
+/** Brand a browser/mobile session with its {@link BrowserProbe}. */
+export function attachBrowserProbe(session, probe) {
+    session[BROWSER_PROBE] = probe;
+    return session;
+}
+/** True if `x` is a spectest browser/mobile session (i.e. probe-branded). */
+export function isBrowserSession(x) {
+    return typeof x === "object" && x !== null && BROWSER_PROBE in x;
+}
+/** The probe branded onto a browser/mobile session by `buildBackend`. */
+export function getBrowserProbe(session) {
+    return session[BROWSER_PROBE];
+}
 /** The silent-read probe for a locator — the seam `expect(locator)` matchers
  *  poll (in index.ts) without pulling playwright types or the backend into
  *  that module. */
@@ -182,15 +196,74 @@ export const desktopStrategy = {
  *  the press dwell RN Pressables need (playwright's `tap()` has no dwell). */
 export const mobileStrategy = {
     touch: true,
-    async tap(backend, loc, opts) {
+    async tap(backend, loc, opts, rec) {
         await loc.waitFor({ state: "visible", timeout: opts?.timeout });
         await loc.scrollIntoViewIfNeeded({ timeout: opts?.timeout });
         const box = await loc.boundingBox();
         if (!box)
             throw new Error("tap: element vanished before it could be tapped");
-        await backend.rawTap(box.x + box.width / 2, box.y + box.height / 2, opts?.duration);
+        const x = box.x + box.width / 2;
+        const y = box.y + box.height / 2;
+        // Exact, no probe needed: this IS the point the touch is dispatched at,
+        // measured after the scroll. Same field the replay reads — see
+        // stampActionPoint.
+        if (rec) {
+            rec.x = Math.round(x);
+            rec.y = Math.round(y);
+        }
+        await backend.rawTap(x, y, opts?.duration);
     },
 };
+/** How long the click-point probe waits for the element. Short on purpose:
+ *  either it is already on screen and the answer is one round trip away, or
+ *  the action's own actionability wait — with the author's timeout and a real
+ *  error message — is the one that should report it. */
+const POINT_PROBE_MS = 250;
+/** Stamp the viewport point an action is about to act on onto its (still
+ *  open) step, as the `x`/`y` a raw `browser.clickAt` records.
+ *
+ *  The replay cursor is normally positioned from rrweb's own recorded mouse
+ *  events — but a click that navigates loses them. The page-side event buffer
+ *  lives on `window`, so everything the click emitted dies with the document
+ *  before the post-op drain can collect it, and the step arrives carrying only
+ *  the destination page's load. The step's own coordinates are then the sole
+ *  record of where the click landed; without them the viewer has nothing to
+ *  put the cursor on.
+ *
+ *  Best-effort in every direction. A probe failure (not attached yet, strict
+ *  violation, frame detached) leaves the step unstamped and lets the action
+ *  itself report the problem. We only stamp a centre that is inside the
+ *  viewport of the top-level document, because that is exactly the case where
+ *  playwright clicks the element where it currently sits — one that is
+ *  off-screen (or in an iframe, whose rect is frame-relative) gets scrolled
+ *  into view first, which moves the point we measured. */
+async function stampActionPoint(loc, rec, position) {
+    try {
+        const pt = await loc.evaluate((el, pos) => {
+            if (window.top !== window)
+                return null;
+            const r = el.getBoundingClientRect();
+            if (!r.width || !r.height)
+                return null;
+            // Playwright clicks the element's centre unless the caller named a
+            // point — which it takes relative to the PADDING box, so an element
+            // with a border (a plain `<button>` has 2px of it) sits that far off
+            // the rect we measured.
+            const cs = pos ? getComputedStyle(el) : null;
+            const x = cs ? r.left + parseFloat(cs.borderLeftWidth) + pos.x : r.left + r.width / 2;
+            const y = cs ? r.top + parseFloat(cs.borderTopWidth) + pos.y : r.top + r.height / 2;
+            const onScreen = x >= 0 && y >= 0 && x <= window.innerWidth && y <= window.innerHeight;
+            return onScreen ? { x, y } : null;
+        }, position, { timeout: POINT_PROBE_MS });
+        if (pt) {
+            rec.x = Math.round(pt.x);
+            rec.y = Math.round(pt.y);
+        }
+    }
+    catch {
+        /* Element not ready / gone / strict violation — the action reports it. */
+    }
+}
 // ────────────────────────────────────────────────────────────────────────
 // Factory
 // ────────────────────────────────────────────────────────────────────────
@@ -202,6 +275,14 @@ export function makeLocator(backend, strategy, chain) {
     const extend = (step) => makeLocator(backend, strategy, { steps: [...chain.steps, step] });
     // One recorded event, result NOT wrapped (void/action).
     const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain), page));
+    // One recorded event whose fields the action itself finishes filling in:
+    // `rec` is the very object the recorder spreads once `fn` resolves (the
+    // same mutate-in-flight seam `screenshot`'s artifact id rides), so the
+    // click family can stamp the point it acted on. See stampActionPoint.
+    const actAt = (action, fn) => {
+        const rec = { selector: label };
+        return backend.pageOp(action, rec, (page) => fn(lower(page, chain), rec));
+    };
     // One recorded event, result provenance-wrapped for expect().
     const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain)), {
         wrap: true,
@@ -236,9 +317,15 @@ export function makeLocator(backend, strategy, chain) {
         last: () => extend({ m: "last", args: [] }),
         nth: (i) => extend({ m: "nth", args: [i] }),
         // actions
-        click: (opts) => act("click", {}, (l) => l.click(opts)),
-        dblclick: (opts) => act("dblclick", {}, (l) => l.dblclick(opts)),
-        tap: (opts) => act("tap", {}, (l) => strategy.tap(backend, l, opts)),
+        click: (opts) => actAt("click", async (l, rec) => {
+            await stampActionPoint(l, rec, opts?.position);
+            return l.click(opts);
+        }),
+        dblclick: (opts) => actAt("dblclick", async (l, rec) => {
+            await stampActionPoint(l, rec, opts?.position);
+            return l.dblclick(opts);
+        }),
+        tap: (opts) => actAt("tap", (l, rec) => strategy.tap(backend, l, opts, rec)),
         fill: (value, opts) => {
             const t = truncateUtf8(value);
             return act("fill", { text: t.value, textTruncated: t.truncated }, (l) => l.fill(value, { timeout: opts?.timeout }));

package/dist/url-match.d.ts

@@ -0,0 +1,11 @@
+/**
+ * How a URL is matched. A **glob string** (`*` stays inside one path segment,
+ * `**` crosses `/`; anything else is literal, so a plain URL is an exact
+ * match), a **RegExp** (tested against the full URL, unanchored), or a
+ * **predicate** over the parsed {@link URL}.
+ */
+export type UrlPattern = string | RegExp | ((url: URL) => boolean);
+/** Whether `current` (a full URL string) matches `pattern`. */
+export declare function matchesUrl(current: string, pattern: UrlPattern): boolean;
+/** Human display of a pattern, for timeline labels and failure messages. */
+export declare function describeUrlPattern(pattern: UrlPattern): string;

package/dist/url-match.js

@@ -0,0 +1,61 @@
+// URL pattern matching — shared by `browser.waitForURL(...)` and
+// `expect(browser).toHaveURL(...)`.
+//
+// Both take the same pattern forms as Playwright (glob string | RegExp |
+// predicate over a `URL`), and both lower to `matchesUrl` here so the two
+// can never disagree: `waitForURL` hands playwright a predicate that calls
+// this rather than letting playwright apply its own glob dialect, and the
+// matcher polls it directly. Deliberately dependency-free so `index.ts` (the
+// module a project imports on the host, where playwright isn't installed) can
+// use it without pulling in `browser.ts`.
+/** Whether `current` (a full URL string) matches `pattern`. */
+export function matchesUrl(current, pattern) {
+    if (typeof pattern === "function") {
+        let parsed;
+        try {
+            parsed = new URL(current);
+        }
+        catch {
+            // `about:blank`, a data: URL, or a page that never committed — nothing
+            // for a predicate to inspect, so it can't match.
+            return false;
+        }
+        return Boolean(pattern(parsed));
+    }
+    if (pattern instanceof RegExp)
+        return pattern.test(current);
+    return globToRegExp(pattern).test(current);
+}
+/** Human display of a pattern, for timeline labels and failure messages. */
+export function describeUrlPattern(pattern) {
+    if (typeof pattern === "function")
+        return "a URL predicate";
+    if (pattern instanceof RegExp)
+        return String(pattern);
+    return JSON.stringify(pattern);
+}
+// Compiled globs are cached: a matcher polls the same pattern every 50ms.
+const GLOB_CACHE = new Map();
+function globToRegExp(glob) {
+    const hit = GLOB_CACHE.get(glob);
+    if (hit)
+        return hit;
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                out += ".*";
+                i++;
+            }
+            else {
+                out += "[^/]*";
+            }
+            continue;
+        }
+        out += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    const re = new RegExp(`^${out}$`);
+    GLOB_CACHE.set(glob, re);
+    return re;
+}

package/package.json

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