@specific.dev/spectest 0.121.0 → 0.123.0

package/src/locator.ts

@@ -22,6 +22,7 @@
 // author-facing call is exactly one recorded browser event (with its rrweb
 // drain), whatever playwright work it composes underneath.
 
+import type { LocatorAssertionRequest } from "./playwright-assertions.js";
 import { Buffer } from "node:buffer";
 import type { Page, Locator as PWLocator } from "playwright-core";
 import type { RecordableFields } from "./browser.js";
@@ -346,7 +347,7 @@ export function chainLabel(chain: Chain): string {
 /** The slice of the browser backend a locator needs. `pageOp` records one
  *  browser event and (when `wrap`) provenance-wraps the result so a later
  *  `expect(...)` nests under the step. `silentRead` runs a lowered read with
- *  NO recording/drain — the poll path for `expect(locator)` matchers, which
+ *  NO recording/drain — the assertion path for `expect(locator)` matchers, which
  *  must not emit one browser event per retry. */
 export interface LocatorBackend {
   pageOp<T>(
@@ -369,30 +370,18 @@ export interface LocatorBackend {
   ): Promise<number | undefined>;
 }
 
-/** Silent (non-recorded) reads a locator exposes for `expect(...)` matchers to
- *  poll. See {@link getLocatorProbe}. */
+/** Native assertions and recording for a lazy Spectest locator. */
 export interface LocatorProbe {
-  /** Human label of the locator (for failure messages). */
   readonly label: string;
-  isVisible(): Promise<boolean>;
-  textContent(timeout?: number): Promise<string | null>;
-  innerText(timeout?: number): Promise<string>;
-  /** Every match's text — the array forms of `toHaveText`/`toContainText`,
-   *  which are about a list of elements and so must not go through the
-   *  single-element (strict) reads above. */
-  allTextContents(): Promise<string[]>;
-  allInnerTexts(): Promise<string[]>;
-  inputValue(timeout?: number): Promise<string>;
-  count(): Promise<number>;
-  /** The "did you mean…" block for a locator that matched nothing, or `""`.
-   *  See locator-hints.ts. */
+  /** Resolve the current page once per assertion; Playwright re-resolves the
+   * selector on that page throughout the assertion, including navigation. */
+  assert(request: LocatorAssertionRequest): Promise<void>;
+  /** Supplemental diagnostics, never part of deciding the assertion result. */
   nearMiss(): Promise<string>;
-  isEnabled(timeout?: number): Promise<boolean>;
-  isChecked(timeout?: number): Promise<boolean>;
-  /** After the silent poll settles, emit the single settled browser step this
+  /** After the native assertion settles, emit the single settled browser step this
    *  locator's `expect(...)` matcher assertion nests under, and return its seq
    *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
-   *  poll time, `error` marks the step failed on a timed-out matcher. Returns
+   *  assertion time, `error` marks the step failed on a failed matcher. Returns
    *  `undefined` when nothing is recording.
    *
    *  `opts.reveal` additionally stamps the element's rrweb node id for the
@@ -408,14 +397,11 @@ export interface LocatorProbe {
   ): 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. */
+/** Native page assertions, kept behind a seam so index.ts does not load
+ * Playwright when a project only imports configuration or value assertions. */
 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
+  assertURL(negated: boolean, expected: import("./url-match.js").UrlPattern, opts?: { timeout?: number }): Promise<void>;
+  /** After the native assertion 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>;
@@ -440,9 +426,7 @@ export function getBrowserProbe(session: unknown): BrowserProbe {
   return (session as Record<symbol, BrowserProbe>)[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. */
+/** The assertion/recording seam used by index.ts without loading Playwright. */
 export function getLocatorProbe(loc: Locator): LocatorProbe {
   return (loc as unknown as Record<symbol, LocatorProbe>)[PROBE];
 }
@@ -649,9 +633,9 @@ function lowerInputFiles(files: InputFiles): {
  * A lazy reference to element(s), resolved with auto-waiting at the moment an
  * action runs. Mirrors playwright-core's `Locator`: STRICT by default — a
  * locator resolving to multiple elements throws a strict-mode violation at
- * action time rather than silently acting on one. Narrow with `exact: true`,
- * a testid, `filter(...)`, or the explicit `first()`/`last()`/`nth(i)`
- * opt-outs.
+ * action time rather than silently acting on one. Scope to the intended
+ * container, an exact role/name, or a stable test ID. Use positional selection
+ * only when order is part of what the test verifies.
  */
 export interface Locator {
   // ── Composition (lazy; return a new Locator) ──────────────────────────
@@ -668,13 +652,15 @@ export interface Locator {
   filter(opts: FilterOptions): Locator;
   /** Intersect with another locator (both must match the same element). */
   and(other: Locator): Locator;
-  /** Union with another locator (either may match). */
+  /** Union with another locator (either may match). If both match, a
+   * single-element operation still fails strictness. */
   or(other: Locator): Locator;
-  /** Explicit strict-mode opt-out: the first resolved element. */
+  /** First resolved element. Use only when position is the intended contract;
+   * does not establish identity or relate this match to another locator. */
   first(): Locator;
-  /** Explicit strict-mode opt-out: the last resolved element. */
+  /** Last resolved element. Prefer a unique identity unless testing order. */
   last(): Locator;
-  /** Explicit strict-mode opt-out: the i-th resolved element (0-based). */
+  /** i-th resolved element (0-based). Prefer a unique identity unless testing order. */
   nth(index: number): Locator;
 
   // ── Actions (auto-wait; default 10s, `{ timeout }` overrides) ─────────
@@ -726,11 +712,15 @@ export interface Locator {
   dragTo(target: Locator, opts?: TimeoutOption): Promise<void>;
 
   // ── Reads (wrapped so `expect(...)` nests under the step) ─────────────
+  /** One observed value; use `await expect(locator).toHaveText(...)` to
+   * retry until expected text appears. Wrapping preserves provenance, not retries. */
   textContent(opts?: TimeoutOption): Promise<Wrapped<string | null>>;
   innerText(opts?: TimeoutOption): Promise<Wrapped<string>>;
   innerHTML(opts?: TimeoutOption): Promise<Wrapped<string>>;
   inputValue(opts?: TimeoutOption): Promise<Wrapped<string>>;
   getAttribute(name: string, opts?: TimeoutOption): Promise<Wrapped<string | null>>;
+  /** Immediate visibility observation. Use `await expect(locator).toBeVisible()`
+   * for readiness; use `.unwrap()` if branching on this observation. */
   isVisible(): Promise<Wrapped<boolean>>;
   isHidden(): Promise<Wrapped<boolean>>;
   isEnabled(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
@@ -738,8 +728,9 @@ export interface Locator {
   isChecked(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
   isEditable(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
   count(): Promise<Wrapped<number>>;
-  /** Resolve to one locator per current match (handle-free — each is pinned
-   *  with `nth(i)`). One recorded event. */
+  /** One locator per current match, using `nth(i)` (positions, not pinned
+   * identities). Does not wait for a list to finish loading; assert its ready
+   * state first, and prefer stable IDs if items can move during iteration. */
   all(): Promise<Locator[]>;
   allTextContents(): Promise<Wrapped<string[]>>;
   allInnerTexts(): Promise<Wrapped<string[]>>;
@@ -858,23 +849,22 @@ export function makeLocator(
     ) as Promise<Wrapped<T>>;
   };
 
-  // Silent, non-recorded reads for expect(locator) matchers to poll.
+  // Native assertion and recording seam for expect(locator).
   const probe: LocatorProbe = {
     label,
-    isVisible: () => backend.silentRead((page) => lower(page, chain).isVisible()),
-    textContent: (timeout) => backend.silentRead((page) => lower(page, chain).textContent({ timeout })),
-    innerText: (timeout) => backend.silentRead((page) => lower(page, chain).innerText({ timeout })),
-    allTextContents: () => backend.silentRead((page) => lower(page, chain).allTextContents()),
-    allInnerTexts: () => backend.silentRead((page) => lower(page, chain).allInnerTexts()),
-    inputValue: (timeout) => backend.silentRead((page) => lower(page, chain).inputValue({ timeout })),
-    count: () => backend.silentRead((page) => lower(page, chain).count()),
+    assert: async (request) => {
+      const { assertLocator } = await import("./playwright-assertions.js");
+      return backend.silentRead((page) => assertLocator(lower(page, chain), request));
+    },
     nearMiss: () => backend.silentRead((page) => hintBlock(page)),
-    isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
-    isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
     settle: async (action, waitedMs, error, opts) => {
       const fields: Partial<RecordableFields> = { selector: label, target };
       if (opts && opts.reveal) {
-        await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+        try {
+          await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+        } catch {
+          // A page closing after evaluation must not replace the assertion result.
+        }
       }
       return backend.recordSettled(action, fields, waitedMs, error);
     },

package/src/playwright-assertions.test.ts

@@ -0,0 +1,231 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { chromium, type Browser as PWBrowser, type Page } from "playwright-core";
+import { expect as assert, ExpectationError, type Browser, type LocatorMatchers } from "./index.js";
+import { attachBrowserProbe, desktopStrategy, getLocatorProbe, makeLocator, type LocatorBackend } from "./locator.js";
+import { assertURL } from "./playwright-assertions.js";
+import { recordBrowser, startRecording, stopRecording } from "./recorder.js";
+
+// Opt in after `bunx playwright install chromium --only-shell`, or run
+// automatically when a system/cached full Chromium is available.
+const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? undefined;
+const available = !!process.env.SPECTEST_TEST_BROWSER_ASSERTIONS || !!executablePath || existsSync(chromium.executablePath());
+
+describe.skipIf(!available)("Spectest assertions backed by real Playwright/Chromium", () => {
+  let browser: PWBrowser;
+  let page: Page;
+  let backend: LocatorBackend;
+  const locator = (css: string) => makeLocator(backend, desktopStrategy, { steps: [{ m: "locator", args: [css] }] });
+  const session = () => attachBrowserProbe({}, {
+    assertURL: (negated, expected, opts) => assertURL(page, negated, expected, opts),
+    settle: (action, durationMs, error) => backend.recordSettled(action, { url: page.url() }, durationMs, error),
+  }) as Browser;
+
+  beforeAll(async () => { browser = await chromium.launch({ executablePath }); });
+  beforeEach(async () => {
+    page = await browser.newPage();
+    backend = {
+      async pageOp() { throw new Error("assertions must not perform recorded reads"); },
+      silentRead: fn => fn(page),
+      async rawTap() {},
+      async recordSettled(action, fields, durationMs, error) {
+        return recordBrowser({ action, ...fields, durationMs, error });
+      },
+    };
+  });
+  afterEach(async () => {
+    stopRecording();
+    await page.context().close();
+  });
+  afterAll(async () => { await browser?.close(); });
+
+  test("re-resolves a scoped selector when its DOM node is replaced", async () => {
+    await page.setContent('<section aria-label="Order"><span role="status">Saving</span></section>');
+    const status = locator("section").filter({ has: locator('[role="status"]') }).getByRole("status");
+    startRecording();
+    // This timer simulates asynchronous application work, not a test wait.
+    await page.evaluate(() => setTimeout(() => {
+      document.querySelector('[role="status"]')!.outerHTML = '<span role="status">Saved</span>';
+    }, 150));
+    await assert(status, "order persisted").toHaveText("Saved", { timeout: 2000 });
+    const events = stopRecording();
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({ kind: "browser", action: "toHaveText" });
+    expect(events[1]).toMatchObject({ passed: true, sourceSeq: events[0]!.seq, message: "order persisted" });
+  });
+
+  test("waits through navigation and resolves an initially absent element", async () => {
+    const pending = assert(locator("#saved")).toHaveText("Saved", { timeout: 2000 });
+    await page.goto('data:text/html,<div id="saved">Saved</div>');
+    await pending;
+  });
+
+  test("an existing SDK locator resolves a replacement backend page at assertion time", async () => {
+    const target = locator("#saved");
+    const previous = page;
+    page = await browser.newPage();
+    await previous.context().close();
+    await page.setContent('<div id="saved">Saved</div>');
+    await assert(target).toHaveText("Saved");
+  });
+
+  test("all exposed matcher forms preserve positive and negative results", async () => {
+    await page.setContent('<input id="input" value="Saved"><input id="check" type="checkbox" checked><button disabled>Save</button><div id="text">Hello<span hidden> hidden</span></div><li>One</li><li>Two</li>');
+    await assert(locator("#input")).toBeVisible();
+    await assert(locator("#input")).not.toBeHidden();
+    await assert(locator("#input")).toBeEnabled();
+    await assert(locator("#input")).not.toBeDisabled();
+    await assert(locator("button")).toBeDisabled();
+    await assert(locator("button")).not.toBeEnabled();
+    await assert(locator("#check")).toBeChecked();
+    await page.locator("#check").uncheck();
+    await assert(locator("#check")).not.toBeChecked();
+    await assert(locator("#check")).not.toHaveValue("wrong");
+    await assert(locator("#input")).toHaveValue("Saved");
+    await assert(locator("#text")).toHaveText("Hello", { useInnerText: true });
+    await assert(locator("#text")).toContainText("hidden");
+    await assert(locator("#text span")).toBeHidden();
+    await assert(locator("#text")).not.toContainText("absent");
+    await assert(locator("li")).toHaveText(["One", /Two/]);
+    await assert(locator("li")).toContainText(["Two"]);
+    await assert(locator("li")).not.toContainText(["Two", "One"]);
+    await assert(locator("li")).not.toHaveText(["One"]);
+    await assert(locator("li")).toHaveCount(2);
+    await assert(locator("li")).not.toHaveCount(0);
+  });
+
+  test("absent elements pass disappearance/count checks but not negative text", async () => {
+    const absent = locator("#missing");
+    await assert(absent).toBeHidden();
+    await assert(absent).not.toBeVisible();
+    await assert(absent).toHaveCount(0);
+    await assert(absent).toHaveText([]);
+    await expect(assert(absent).not.toHaveText("Saved", { timeout: 60 })).rejects.toThrow("element(s) not found");
+    await expect(assert(absent).not.toHaveValue("Saved", { timeout: 60 })).rejects.toBeInstanceOf(ExpectationError);
+  });
+
+  test("string whitespace, raw regex text, case overrides and regex state use native semantics", async () => {
+    await page.setContent('<pre id="text">a\nb</pre><div id="saved">SAVED</div>');
+    await assert(locator("#text")).toHaveText("a b");
+    await assert(locator("#text")).toHaveText("a\u00a0b");
+    await assert(locator("#text")).toHaveText(/a\nb/);
+    await assert(locator("#text")).not.toHaveText(/a b/);
+    await assert(locator("#saved")).not.toHaveText(/saved/i, { ignoreCase: false });
+    await assert(locator("#saved")).toHaveText(/saved/, { ignoreCase: true });
+    for (const pattern of [/SAVED/g, /SAVED/y]) {
+      pattern.lastIndex = 3;
+      await assert(locator("#saved")).toHaveText(pattern);
+      await expect(assert(locator("#saved")).not.toHaveText(pattern, { timeout: 180 })).rejects.toThrow();
+      await assert(locator("#saved")).toHaveText(pattern);
+    }
+  });
+
+  test("input regexes cannot make a negative assertion pass on unchanged text", async () => {
+    await page.setContent('<input value="Saved">');
+    await expect(assert(locator("input")).not.toHaveValue(/Saved/g, { timeout: 180 })).rejects.toThrow();
+  });
+
+  test("one assertion deadline bounds a missing input regardless of action timeout", async () => {
+    page.setDefaultTimeout(10_000);
+    const started = performance.now();
+    const input = locator("input");
+    getLocatorProbe(input).nearMiss = async () => ""; // Measure assertion budget, excluding supplemental diagnostics.
+    await expect(assert(input).toHaveValue("Saved", { timeout: 100 })).rejects.toThrow();
+    expect(performance.now() - started).toBeLessThan(3000);
+  });
+
+  test("timeout zero disables the assertion timeout instead of checking once", async () => {
+    await page.setContent('<div id="status">Saving</div>');
+    await page.evaluate(() => setTimeout(() => { document.querySelector("div")!.textContent = "Saved"; }, 150));
+    await assert(locator("#status")).toHaveText("Saved", { timeout: 0 });
+  });
+
+  test("strictness and invalid selectors fail negative assertions with native details", async () => {
+    await page.setContent("<div>One</div><div>Two</div>");
+    await expect(assert(locator("div")).not.toHaveText("Saved", { timeout: 60 })).rejects.toThrow("strict mode violation");
+    await expect(assert(locator("[")).not.toHaveText("Saved", { timeout: 60 })).rejects.toThrow();
+  });
+
+  const checks: [string, (m: LocatorMatchers) => Promise<void>][] = [
+    ["visible", m => m.toBeVisible({ timeout: 100 })],
+    ["hidden", m => m.toBeHidden({ timeout: 100 })],
+    ["text", m => m.toHaveText("Saved", { timeout: 100 })],
+    ["contains", m => m.toContainText("Saved", { timeout: 100 })],
+    ["value", m => m.toHaveValue("Saved", { timeout: 100 })],
+    ["count", m => m.toHaveCount(1, { timeout: 100 })],
+    ["enabled", m => m.toBeEnabled({ timeout: 100 })],
+    ["disabled", m => m.toBeDisabled({ timeout: 100 })],
+    ["checked", m => m.toBeChecked({ timeout: 100 })],
+  ];
+  for (const [name, check] of checks) {
+    test(`a closed page cannot satisfy a negative ${name} assertion`, async () => {
+      const target = locator("input");
+      await page.close();
+      startRecording();
+      await expect(check(assert(target).not)).rejects.toBeInstanceOf(ExpectationError);
+      const events = stopRecording();
+      expect(events).toHaveLength(2);
+      expect(events[1]).toMatchObject({ passed: false, negated: true, sourceSeq: events[0]!.seq });
+    });
+  }
+
+  test("failure records the native received value and call log", async () => {
+    await page.setContent('<div id="status">Draft</div>');
+    startRecording();
+    await expect(assert(locator("#status")).toHaveText("Saved", { timeout: 60 })).rejects.toThrow("Call log:");
+    expect(stopRecording()[1]).toMatchObject({ passed: false, actual: "Draft", expected: "Saved" });
+  });
+
+  test("URL assertions wait for navigation and retain Spectest glob syntax", async () => {
+    const view = session();
+    await page.route("http://spectest.test/**", route => route.fulfill({ body: "ready" }));
+    const pending = assert(view).toHaveURL("**/dashboard", { timeout: 2000 });
+    await page.goto("http://spectest.test/dashboard");
+    await pending;
+    await assert(view).toHaveURL("http://spectest.test/*");
+    await assert(view).toHaveURL(/dashboard/g);
+    await assert(view).toHaveURL(url => url.pathname === "/dashboard");
+    await assert(view).not.toHaveURL("**/login");
+    await expect(assert(view).not.toHaveURL(/dashboard/g, { timeout: 180 })).rejects.toThrow();
+  });
+
+  test("closed pages fail negative URL assertions instead of accepting a cached URL", async () => {
+    await page.close();
+    startRecording();
+    await expect(assert(session()).not.toHaveURL("**/dashboard", { timeout: 60 })).rejects.toBeInstanceOf(ExpectationError);
+    const events = stopRecording();
+    expect(events[1]).toMatchObject({ passed: false, matcher: "toHaveURL", sourceSeq: events[0]!.seq });
+  });
+});
+
+// Exercise the production session branding/recording as well as the real
+// native engine above. browser.ts intentionally uses system Chromium.
+test.skipIf(!executablePath)("browser backend preserves assertion provenance and failure page capture", async () => {
+  const { openBrowser } = await import("./browser.js");
+  const replaySteps: unknown[] = [];
+  const view = await openBrowser({
+    url: 'data:text/html,<div id="status">Saved</div>',
+    recorder: { sessionId: "assertion-test", recordStep: step => { replaySteps.push(step); } },
+  });
+  try {
+    startRecording();
+    await assert(view.locator("#status"), "saved").toHaveText("Saved");
+    await assert(view).toHaveURL("data:text/html,**");
+    await expect(assert(view.locator("#status")).toHaveText("Draft", { timeout: 60 })).rejects.toThrow();
+    const events = stopRecording();
+    const assertions = events.filter(e => e.kind === "assertion");
+    const steps = events.filter(e => e.kind === "browser");
+    expect(assertions).toHaveLength(3);
+    expect(steps).toHaveLength(3);
+    expect(assertions.map(a => a.sourceSeq)).toEqual(steps.map(s => s.seq));
+    expect(assertions.map(a => a.passed)).toEqual([true, true, false]);
+    expect(assertions[2]).toMatchObject({ actual: "Saved", expected: "Draft" });
+    expect(steps[2]!.pageStructure).toContain("Saved");
+    expect(steps.every(step => step.sessionId === "assertion-test")).toBe(true);
+    expect(steps[0]!.targetNodeId).toBeGreaterThan(0);
+    expect(replaySteps.length).toBeGreaterThan(0);
+  } finally {
+    stopRecording();
+    await view.close();
+  }
+});

package/src/playwright-assertions.ts

@@ -0,0 +1,49 @@
+// Loaded only when a browser assertion runs. Use the public matcher API;
+// Playwright owns selector resolution, retries, deadlines and negation.
+import { expect } from "@playwright/test";
+import type { Locator, Page } from "playwright-core";
+import type { BrowserMatchers, LocatorMatchers } from "./index.js";
+import { DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
+import { globToRegExp } from "./url-match.js";
+
+export type LocatorAssertionRequest = {
+  [K in keyof LocatorMatchers]: {
+    matcher: K;
+    args: Parameters<LocatorMatchers[K]>;
+    negated: boolean;
+  }
+}[keyof LocatorMatchers];
+
+const browserExpect = expect.configure({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
+
+export async function assertLocator(locator: Locator, request: LocatorAssertionRequest): Promise<void> {
+  const positive = browserExpect(locator);
+  const assertion = request.negated ? positive.not : positive;
+  switch (request.matcher) {
+    case "toBeVisible": return assertion.toBeVisible(...request.args);
+    case "toBeHidden": return assertion.toBeHidden(...request.args);
+    case "toHaveText": return assertion.toHaveText(...request.args);
+    case "toContainText": return assertion.toContainText(...request.args);
+    case "toHaveValue": return assertion.toHaveValue(...request.args);
+    case "toHaveCount": return assertion.toHaveCount(...request.args);
+    case "toBeEnabled": return assertion.toBeEnabled(...request.args);
+    case "toBeDisabled": return assertion.toBeDisabled(...request.args);
+    case "toBeChecked": return assertion.toBeChecked(...request.args);
+    default: {
+      const unsupported: never = request;
+      throw new Error(`Unsupported locator assertion: ${String(unsupported)}`);
+    }
+  }
+}
+
+export async function assertURL(
+  page: Page,
+  negated: boolean,
+  ...[expected, options]: Parameters<BrowserMatchers["toHaveURL"]>
+): Promise<void> {
+  const positive = browserExpect(page);
+  // Spectest has always accepted URL globs. Convert just that syntax; use
+  // native URL assertions for evaluation (including predicates and .not).
+  const pattern = typeof expected === "string" ? globToRegExp(expected) : expected;
+  await (negated ? positive.not : positive).toHaveURL(pattern, options);
+}

package/src/text-match.test.ts

@@ -1,11 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import {
-  containsText,
-  containsTextArray,
   escapeInvisible,
-  matchesText,
-  matchesTextArray,
   normalizeWhiteSpace,
   textDifferenceNote,
 } from "./text-match.js";
@@ -31,59 +27,6 @@ describe("normalizeWhiteSpace", () => {
   });
 });
 
-describe("matchesText", () => {
-  test("a typed space matches a no-break space", () => {
-    expect(matchesText(SEK, "15 000 kr")).toBe(true);
-  });
-
-  test("markup that wraps the value over two lines still matches", () => {
-    expect(matchesText("\n  Total:\n  15 000 kr\n", "Total: 15 000 kr")).toBe(true);
-  });
-
-  test("is a whole-string comparison", () => {
-    expect(matchesText(SEK, "15 000")).toBe(false);
-    expect(containsText(SEK, "15 000")).toBe(true);
-  });
-
-  test("a RegExp is tested against the normalized text", () => {
-    expect(matchesText(SEK, /^15 000 kr$/)).toBe(true);
-    // The same pattern against the raw text would have to spell U+00A0 out.
-    expect(/^15 000 kr$/.test(SEK)).toBe(false);
-  });
-
-  test("ignoreCase covers both a string and a RegExp", () => {
-    expect(matchesText("SPARA", "spara")).toBe(false);
-    expect(matchesText("SPARA", "spara", { ignoreCase: true })).toBe(true);
-    expect(matchesText("SPARA", /spara/, { ignoreCase: true })).toBe(true);
-  });
-});
-
-describe("containsText", () => {
-  test("normalizes both sides", () => {
-    expect(containsText(`Summa: ${SEK} inkl. moms`, "15 000 kr")).toBe(true);
-  });
-
-  test("takes a RegExp, which the string-only signature could not", () => {
-    expect(containsText(SEK, /\d{2} \d{3}/)).toBe(true);
-  });
-});
-
-describe("array forms", () => {
-  const rows = ["Item one", "Item two", "Item three"];
-
-  test("toHaveText's array is position for position, and the counts must agree", () => {
-    expect(matchesTextArray(rows, ["Item one", "Item two", "Item three"])).toBe(true);
-    expect(matchesTextArray(rows, ["Item one", "Item three"])).toBe(false);
-    expect(matchesTextArray(rows, ["Item one", /two/, "Item three"])).toBe(true);
-  });
-
-  test("toContainText's array allows elements in between, but not out of order", () => {
-    expect(containsTextArray(rows, ["one", "three"])).toBe(true);
-    expect(containsTextArray(rows, ["three", "one"])).toBe(false);
-    expect(containsTextArray(rows, ["four"])).toBe(false);
-  });
-});
-
 describe("escapeInvisible", () => {
   test("spells out the characters that print as nothing", () => {
     expect(escapeInvisible(JSON.stringify(SEK))).toBe('"15\\u00a0000 kr"');

package/src/text-match.ts

@@ -1,25 +1,4 @@
-// Text comparison for the web-first matchers, and readable notes for the
-// failures that invisible characters cause.
-//
-// Two rules, and they are deliberately different:
-//
-//   * **Matching is Playwright's.** `expect(locator).toHaveText(...)` and
-//     `toContainText(...)` normalize whitespace on BOTH sides exactly as
-//     playwright's own text engine does (`normalizeWhiteSpace` in
-//     playwright-core). Without this the SDK disagreed with itself: the same
-//     string matched through `getByText("15 000 kr")` (playwright's engine,
-//     which normalizes) and failed through `toContainText("15 000 kr")`
-//     (ours, which did a raw `includes`). The case that reported it is
-//     Swedish number formatting — `Intl.NumberFormat("sv-SE")` groups
-//     thousands with U+00A0 NO-BREAK SPACE, and JavaScript's `\s` covers
-//     U+00A0, so normalization makes a typed space match it.
-//
-//   * **Diagnostics are wider.** A value the author compares themselves
-//     (`expect(body).toContain(...)`, `toHaveValue`) is still exact, as it
-//     must be — so when such a comparison fails on characters that print the
-//     same, the message has to say so. `textDifferenceNote` reports the
-//     invisible or look-alike characters that are the whole difference, and
-//     `escapeInvisible` makes the two printed strings differ on screen.
+// Text diagnostics only. Browser comparisons are delegated to Playwright.
 
 /** Characters that are invisible on screen (or print as an ordinary space)
  *  and their Unicode names, for a message a reader can act on. */
@@ -87,44 +66,10 @@ export function normalizeWhiteSpace(text: string): string {
 }
 
 export interface TextMatchOptions {
-  /** Compare without regard to letter case. On a RegExp this adds the `i`
-   *  flag, as playwright's own `ignoreCase` does. */
+  /** Override case sensitivity, including a RegExp's `i` flag. */
   ignoreCase?: boolean;
 }
 
-function caseFold(s: string, opts?: TextMatchOptions): string {
-  return opts?.ignoreCase ? s.toLowerCase() : s;
-}
-
-function withIgnoreCase(re: RegExp, opts?: TextMatchOptions): RegExp {
-  if (!opts?.ignoreCase || re.flags.includes("i")) return re;
-  return new RegExp(re.source, `${re.flags}i`);
-}
-
-/** The element's text equals `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export function matchesText(
-  actual: string,
-  expected: string | RegExp,
-  opts?: TextMatchOptions,
-): boolean {
-  const a = normalizeWhiteSpace(actual);
-  if (expected instanceof RegExp) return withIgnoreCase(expected, opts).test(a);
-  return caseFold(a, opts) === caseFold(normalizeWhiteSpace(expected), opts);
-}
-
-/** The element's text contains `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export function containsText(
-  actual: string,
-  expected: string | RegExp,
-  opts?: TextMatchOptions,
-): boolean {
-  const a = normalizeWhiteSpace(actual);
-  if (expected instanceof RegExp) return withIgnoreCase(expected, opts).test(a);
-  return caseFold(a, opts).includes(caseFold(normalizeWhiteSpace(expected), opts));
-}
-
 // ── Diagnostics ───────────────────────────────────────────────────────────
 
 /** `" "` for an invisible character, the character itself otherwise.
@@ -242,44 +187,3 @@ export function textDifferenceNote(
   }
   return "";
 }
-
-// ── Array forms (`toHaveText([...])` / `toContainText([...])`) ────────────
-//
-// Playwright's own rule, from its injected script: the expected items are
-// matched against the received texts **greedily, in order**, and the lengths
-// must agree for `toHaveText` but not for `toContainText`. So
-// `toContainText(["Two", "Four"])` passes against a four-row list, while
-// `toHaveText(["Two", "Four"])` does not.
-
-function matchesInOrder(
-  actual: string[],
-  expected: (string | RegExp)[],
-  item: (a: string, e: string | RegExp) => boolean,
-): boolean {
-  let want = 0;
-  for (let i = 0; i < actual.length && want < expected.length; i++) {
-    if (item(actual[i]!, expected[want]!)) want++;
-  }
-  return want === expected.length;
-}
-
-/** Every element's text equals the item at its position, and there are
- *  exactly as many elements as items. */
-export function matchesTextArray(
-  actual: string[],
-  expected: (string | RegExp)[],
-  opts?: TextMatchOptions,
-): boolean {
-  if (actual.length !== expected.length) return false;
-  return matchesInOrder(actual, expected, (a, e) => matchesText(a, e, opts));
-}
-
-/** The elements' texts contain every item, in order. Extra elements between
- *  the matches are allowed. */
-export function containsTextArray(
-  actual: string[],
-  expected: (string | RegExp)[],
-  opts?: TextMatchOptions,
-): boolean {
-  return matchesInOrder(actual, expected, (a, e) => containsText(a, e, opts));
-}