@specific.dev/spectest 0.28.3 → 0.30.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) {
@@ -550,6 +551,87 @@ const RRWEB_BOOTSTRAP = `
       }, true);
     } catch (e) { log("init FAIL " + (e && e.message)); }
   })();
+  // ── Record form resets as synthetic Input events ───────────────────
+  // rrweb learns that a control's value changed through exactly two
+  // channels: the \`input\`/\`change\` events, and setters it hooks on the
+  // HTMLInput/TextArea/SelectElement prototypes. A **form reset** uses
+  // neither — the browser clears the controls internally — so the
+  // recording keeps the last typed value forever while the real page
+  // shows an empty field. Measured, not assumed: \`el.value = x\` IS
+  // captured (even through React's own per-node \`value\` accessor, since
+  // that delegates to the prototype descriptor we hooked first), and
+  // \`form.reset()\` is NOT. The shape is everywhere in chat/prompt UIs —
+  // shadcn/ai-elements' PromptInput resets the form on submit, as does
+  // React 19's automatic \`<form action>\` reset — where it reads as
+  // "clicking send didn't clear the box".
+  //
+  // The \`reset\` event is the hook: it fires (cancelable) BEFORE the
+  // controls are reset, for both \`form.reset()\` and a user-clicked
+  // \`type="reset"\` button. Snapshot the values there, diff on the next
+  // task, and push an Input event per control that actually moved —
+  // byte-identical in shape to what rrweb emits for a real input, so
+  // the replayer applies it the same way. A prevented or no-op reset
+  // changes nothing and therefore emits nothing. We never touch the
+  // page's DOM to provoke a recording (\`el.value = el.value\` would
+  // work, but it sets the control's dirty-value flag and would change
+  // how the app's own later attribute writes render).
+  (function () {
+    if (window.__spectestFormReset) return;
+    window.__spectestFormReset = true;
+    var INPUT_TAGS = ["INPUT", "TEXTAREA", "SELECT"];
+    function snap(form) {
+      var out = [], els;
+      try { els = form.elements; } catch (e) { return out; }
+      if (!els) return out;
+      for (var i = 0; i < els.length; i++) {
+        var el = els[i];
+        if (!el || !el.tagName) continue;
+        if (INPUT_TAGS.indexOf(String(el.tagName).toUpperCase()) < 0) continue;
+        out.push({ el: el, value: el.value, checked: !!el.checked });
+      }
+      return out;
+    }
+    function emitChanged(before) {
+      var mirror = rec && rec.mirror;
+      if (!mirror || typeof mirror.getId !== "function") return;
+      for (var i = 0; i < before.length; i++) {
+        var el = before[i].el;
+        if (el.value === before[i].value && !!el.checked === before[i].checked) continue;
+        if (el.classList && el.classList.contains("rr-ignore")) continue;
+        var id = mirror.getId(el);
+        if (!(id > 0)) continue;
+        var type = el.type ? String(el.type).toLowerCase() : "";
+        var text = String(el.value);
+        // rrweb masks password inputs by default (maskInputOptions
+        // \`{ password: true }\`, default maskInputFn = same-length '*').
+        if (type === "password") {
+          var masked = "";
+          for (var k = 0; k < text.length; k++) masked += "*";
+          text = masked;
+        }
+        window.__spectestRrwebEvents.push({
+          type: 3,
+          data: {
+            source: 5,
+            text: text,
+            isChecked: (type === "radio" || type === "checkbox") ? !!el.checked : false,
+            id: id,
+          },
+          timestamp: Date.now(),
+        });
+      }
+    }
+    try {
+      document.addEventListener("reset", function (ev) {
+        var form = ev.target;
+        if (!form || !form.tagName || String(form.tagName).toUpperCase() !== "FORM") return;
+        var before = snap(form);
+        if (!before.length) return;
+        // The controls are reset after dispatch returns — diff then.
+        setTimeout(function () { emitChanged(before); }, 0);
+      }, true);
+    } catch (e) { /* recording continues without reset capture. */ }
+  })();
 })();
 `;
 // The `;` between parts is load-bearing: a vendored bundle that ends
@@ -1132,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;
@@ -1316,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. */

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.28.3",
+  "version": "0.30.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",