@specific.dev/spectest 0.121.0 → 0.123.0

package/dist/index.js

@@ -1,3 +1,4 @@
+import { stripVTControlCharacters } from "node:util";
 import { resolveEntrypoints } from "./interactive.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
@@ -35,10 +36,9 @@ export { S3Client } from "./s3.js";
 // way a real AI client would, with the OAuth flow a test runs through its
 // own browser. See `mcp.ts`.
 export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
-import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
-import { classifyLocatorFailure, formatWaited, locatorFailureMessage, } from "./locator-errors.js";
-import { containsText, containsTextArray, escapeInvisible, matchesText, matchesTextArray, textDifferenceNote, } from "./text-match.js";
-import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, } from "./locator.js";
+import { escapeInvisible, textDifferenceNote, } from "./text-match.js";
+import { describeUrlPattern } from "./url-match.js";
 import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 export { ca } from "./environment-ca.js";
@@ -690,8 +690,53 @@ function expectValue(actual, message) {
     return buildMatchers(adoptNullishTag(actual), false, message);
 }
 // ── expect(locator): auto-retrying web-first matchers ─────────────────────
-/** Poll interval for locator matchers. */
-const LOCATOR_POLL_MS = 50;
+/** Keep the public error type and recording, but never decide whether a
+ * browser condition passed here. That belongs entirely to Playwright. */
+async function recordWebAssertion(matcher, expected, negated, message, assert, settle, diagnostics) {
+    const started = Date.now();
+    let failure;
+    let actual;
+    try {
+        await assert();
+    }
+    catch (cause) {
+        // matcherResult is diagnostic metadata, not an API we use for evaluation.
+        // Terminal errors need not carry it. Never re-read the page to manufacture
+        // an observed value: it may already differ from the assertion's result.
+        actual = cause?.matcherResult?.actual;
+        let error = stripVTControlCharacters(cause instanceof Error ? cause.message : String(cause));
+        if (typeof actual === "string" && typeof expected === "string") {
+            error += textDifferenceNote(actual, expected, matcher === "toContainText" ? "contains" : "equal");
+        }
+        if (diagnostics) {
+            try {
+                error += await diagnostics(error);
+            }
+            catch { /* best effort */ }
+        }
+        failure = new ExpectationError(error);
+        failure.cause = cause;
+    }
+    const sourceSeq = await settle(Date.now() - started, failure?.message);
+    recordAssertion({
+        matcher,
+        negated,
+        passed: !failure,
+        // The public Playwright API returns void on success. Omit actual rather
+        // than recording a later read as though it were the value that passed.
+        actual: actual === undefined ? undefined : safeSerialize(actual),
+        expected: expected === undefined ? undefined : safeSerialize(expected),
+        error: failure?.message,
+        message,
+        sourceSeq,
+    });
+    if (failure)
+        throw failure;
+}
+function assertionExpected(value) {
+    return value instanceof RegExp ? String(value)
+        : Array.isArray(value) ? value.map(assertionExpected) : value;
+}
 function buildLocatorAssertion(loc, message) {
     return Object.assign(buildLocatorMatchers(loc, false, message), {
         not: buildLocatorMatchers(loc, true, message),
@@ -699,212 +744,30 @@ function buildLocatorAssertion(loc, message) {
 }
 function buildLocatorMatchers(loc, negated, message) {
     const probe = getLocatorProbe(loc);
-    // Poll `check` (a silent, non-recorded read) until the desired condition
-    // holds or the deadline elapses, then emit ONE settled browser step (the
-    // locator label + replay seek point) and record ONE assertion nested under
-    // it via `sourceSeq` — so a web-first `expect(locator)` assertion carries
-    // the same provenance a value assertion does (`expect(await loc.isVisible())`
-    // renders identically). Without the anchor step these assertions floated as
-    // disconnected top-level "value ✓" rows with no element and no replay seek.
-    // `check` returns whether the base condition is satisfied plus the observed
-    // value for the timeline.
-    const run = async (matcher, timeout, check, describe, expected) => {
-        const started = Date.now();
-        const budget = timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
-        const deadline = started + budget;
-        let actual;
-        // Whether this matcher's subject is meant to be on screen, i.e. whether
-        // the step should carry a reveal target for the replay (see
-        // `LocatorProbe.settle`). Only the visibility matchers flip with `negated`
-        // — `not.toHaveText(...)` is still an element the reader should be looking
-        // at — and `toHaveCount(0)` is the third way of saying "expect nothing".
+    const run = (request) => {
+        const { matcher, args } = request;
+        const expected = matcher.startsWith("toHave") || matcher === "toContainText" ? args[0] : undefined;
         const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
         const expectsGone = (visibility && (matcher === "toBeHidden") !== negated) ||
-            (matcher === "toHaveCount" && expected === 0);
-        const settleOpts = { reveal: !expectsGone };
-        // "That element is not there" said plainly, or `undefined` when the
-        // element IS there and the matcher's own description is the better
-        // sentence.
-        //
-        // Two ways to learn it. A matcher whose probe waits (textContent,
-        // inputValue, isEnabled …) has already been told, by the playwright
-        // timeout it caught. One whose probe answers instantly (isVisible) has
-        // not — `toBeVisible()` on a selector that matches nothing and one that
-        // matches a hidden element fail identically — so the count is read once,
-        // at failure time only. `toHaveCount` is left alone: "expected count 2,
-        // got 0" already says it, and better.
-        //
-        // Either way the message ends with the near-miss block — what the page
-        // holds that is close to what was asked for (see locator-hints.ts) — so
-        // the author does not have to run again to find out.
-        const nearMiss = async () => {
-            try {
-                return await probe.nearMiss();
-            }
-            catch {
-                return "";
-            }
-        };
-        const elementFailure = async (err) => {
-            if (err !== undefined) {
-                const failure = classifyLocatorFailure(probe.label, err);
-                if (!failure)
-                    return undefined;
-                return failure.kind === "no-match"
-                    ? failure.message + (await nearMiss())
-                    : failure.message;
-            }
-            if (expectsGone || matcher === "toHaveCount")
-                return undefined;
-            try {
-                if ((await probe.count()) === 0) {
-                    return (`No element matches ${probe.label} (waited ${formatWaited(budget)})` +
-                        (await nearMiss()));
-                }
-            }
-            catch {
-                /* The page is gone or the chain is invalid — the matcher's own
-                   description still says what was expected. */
-            }
-            return undefined;
-        };
-        // The last error a probe threw, kept for the failure message: a matcher
-        // whose read waits for the element (textContent, inputValue, isEnabled …)
-        // reports a missing element as a playwright timeout, and that — not
-        // "got <error: Timeout 10000ms exceeded …>" — is the sentence to fail with.
-        let probeError;
-        for (;;) {
-            let satisfied;
-            try {
-                const r = await check();
-                satisfied = r.satisfied;
-                actual = r.actual;
-                probeError = undefined;
-            }
-            catch (err) {
-                probeError = err;
-                if (Date.now() < deadline) {
-                    await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
-                    continue;
-                }
-                satisfied = false;
-                // The recorded "actual" is what the timeline shows next to the
-                // matcher, so it gets the readable summary too — never the call-log
-                // wall a playwright timeout carries.
-                actual =
-                    locatorFailureMessage(probe.label, err) ??
-                        `<error: ${err?.message ?? String(err)}>`;
-            }
-            const passed = satisfied !== negated;
-            if (passed) {
-                const sourceSeq = await probe.settle(matcher, Date.now() - started, undefined, settleOpts);
-                recordAssertion({
-                    matcher,
-                    negated,
-                    passed: true,
-                    actual: safeSerialize(actual),
-                    expected: expected === undefined ? undefined : safeSerialize(expected),
-                    message,
-                    sourceSeq,
-                });
-                return;
-            }
-            if (Date.now() >= deadline) {
-                // The deadline, not the stopwatch: every one of these polled until it
-                // ran out, and "(waited 10s)" is both what the author set and the same
-                // number twice in a row — a measured 9_987ms is neither.
-                const msg = (await elementFailure(probeError)) ??
-                    `${describe(actual)} (waited ${formatWaited(budget)})`;
-                const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);
-                recordAssertion({
-                    matcher,
-                    negated,
-                    passed: false,
-                    actual: safeSerialize(actual),
-                    expected: expected === undefined ? undefined : safeSerialize(expected),
-                    error: msg,
-                    message,
-                    sourceSeq,
-                });
-                throw new ExpectationError(msg);
-            }
-            await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
-        }
+            (matcher === "toHaveCount" && expected === 0 && !negated);
+        return recordWebAssertion(matcher, assertionExpected(expected), negated, message, () => probe.assert(request), (duration, error) => probe.settle(matcher, duration, error, { reveal: !expectsGone }), 
+        // Preserve native diagnostics, adding suggestions only for missing
+        // elements. A mismatch/strictness/closed-page failure needs no new read.
+        (error) => error.includes("element(s) not found") ? probe.nearMiss() : Promise.resolve(""));
     };
-    const not = negated ? " not" : "";
-    // The element's text, read the way the caller asked for it. `useInnerText`
-    // is playwright's option and means the same here: what the page renders,
-    // rather than every character in the subtree.
-    const readText = async (opts) => opts?.useInnerText
-        ? await probe.innerText(opts.timeout)
-        : ((await probe.textContent(opts?.timeout)) ?? "");
-    const readTexts = async (opts) => opts?.useInnerText ? await probe.allInnerTexts() : await probe.allTextContents();
-    const isArrayExpectation = (v) => Array.isArray(v);
-    /** Expected values render as themselves; a RegExp renders as its source. */
-    const fmtExpected = (v) => v instanceof RegExp
-        ? String(v)
-        : Array.isArray(v)
-            ? `[${v.map(fmtExpected).join(", ")}]`
-            : fmt(v);
-    /** What goes on the assertion event: a RegExp cannot be serialized. */
-    const expectedValue = (v) => (v instanceof RegExp ? String(v) : Array.isArray(v) ? v.map(expectedValue) : v);
     return {
-        toBeVisible: (opts) => run("toBeVisible", opts?.timeout, async () => {
-            const v = await probe.isVisible();
-            return { satisfied: v, actual: v };
-        }, () => `expected ${probe.label}${not} to be visible`),
-        toBeHidden: (opts) => run("toBeHidden", opts?.timeout, async () => {
-            const v = await probe.isVisible();
-            return { satisfied: !v, actual: v };
-        }, () => `expected ${probe.label}${not} to be hidden`),
-        toHaveText: (expected, opts) => run("toHaveText", opts?.timeout, async () => {
-            if (isArrayExpectation(expected)) {
-                const texts = await readTexts(opts);
-                return { satisfied: matchesTextArray(texts, expected, opts), actual: texts };
-            }
-            const t = await readText(opts);
-            return { satisfied: matchesText(t, expected, opts), actual: t };
-        }, (a) => `expected ${probe.label}${not} to have text ${fmtExpected(expected)}, got ${fmt(a)}` +
-            textDifferenceNote(a, expected, "equal"), expectedValue(expected)),
-        toContainText: (expected, opts) => run("toContainText", opts?.timeout, async () => {
-            if (isArrayExpectation(expected)) {
-                const texts = await readTexts(opts);
-                return { satisfied: containsTextArray(texts, expected, opts), actual: texts };
-            }
-            const t = await readText(opts);
-            return { satisfied: containsText(t, expected, opts), actual: t };
-        }, (a) => `expected ${probe.label}${not} to contain text ${fmtExpected(expected)}, got ${fmt(a)}` +
-            textDifferenceNote(a, expected, "contains"), expectedValue(expected)),
-        // Deliberately NOT whitespace-normalized: an input's value is data the
-        // user typed or the app set, not rendered text, and playwright compares
-        // it exactly for the same reason. When that exactness is what failed,
-        // `textDifferenceNote` says so instead of leaving two identical-looking
-        // strings on screen.
-        toHaveValue: (expected, opts) => run("toHaveValue", opts?.timeout, async () => {
-            const v = await probe.inputValue(opts?.timeout);
-            const satisfied = expected instanceof RegExp ? expected.test(v) : v === expected;
-            return { satisfied, actual: v };
-        }, (a) => `expected ${probe.label}${not} to have value ${fmtExpected(expected)}, got ${fmt(a)}` +
-            textDifferenceNote(a, expected, "equal"), expectedValue(expected)),
-        toHaveCount: (expected, opts) => run("toHaveCount", opts?.timeout, async () => {
-            const c = await probe.count();
-            return { satisfied: c === expected, actual: c };
-        }, (a) => `expected ${probe.label}${not} to have count ${expected}, got ${fmt(a)}`, expected),
-        toBeEnabled: (opts) => run("toBeEnabled", opts?.timeout, async () => {
-            const v = await probe.isEnabled(opts?.timeout);
-            return { satisfied: v, actual: v };
-        }, () => `expected ${probe.label}${not} to be enabled`),
-        toBeDisabled: (opts) => run("toBeDisabled", opts?.timeout, async () => {
-            const v = await probe.isEnabled(opts?.timeout);
-            return { satisfied: !v, actual: v };
-        }, () => `expected ${probe.label}${not} to be disabled`),
-        toBeChecked: (opts) => run("toBeChecked", opts?.timeout, async () => {
-            const v = await probe.isChecked(opts?.timeout);
-            return { satisfied: v, actual: v };
-        }, () => `expected ${probe.label}${not} to be checked`),
+        toBeVisible: (...args) => run({ matcher: "toBeVisible", args, negated }),
+        toBeHidden: (...args) => run({ matcher: "toBeHidden", args, negated }),
+        toHaveText: (...args) => run({ matcher: "toHaveText", args, negated }),
+        toContainText: (...args) => run({ matcher: "toContainText", args, negated }),
+        toHaveValue: (...args) => run({ matcher: "toHaveValue", args, negated }),
+        toHaveCount: (...args) => run({ matcher: "toHaveCount", args, negated }),
+        toBeEnabled: (...args) => run({ matcher: "toBeEnabled", args, negated }),
+        toBeDisabled: (...args) => run({ matcher: "toBeDisabled", args, negated }),
+        toBeChecked: (...args) => run({ matcher: "toBeChecked", args, negated }),
     };
 }
-// ── expect(browser): auto-retrying session matchers ───────────────────────
+// ── expect(browser): native page assertions ─────────────────────────────
 function buildBrowserAssertion(session, message) {
     return Object.assign(buildBrowserMatchers(session, false, message), {
         not: buildBrowserMatchers(session, true, message),
@@ -912,48 +775,8 @@ function buildBrowserAssertion(session, 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));
-            }
-        },
+        toHaveURL: (expected, opts) => recordWebAssertion("toHaveURL", describeUrlPattern(expected), negated, message, () => probe.assertURL(negated, expected, opts), (duration, error) => probe.settle("toHaveURL", duration, error)),
     };
 }
 /**

package/dist/locator-errors.js

@@ -104,7 +104,8 @@ function parseStrictViolation(err, label) {
         .slice(0, 3)
         .map((l) => `  - ${l.trim().replace(/^\d+\)\s*/, "")}`);
     const head = `${label} matches ${m[1]} elements, so it is ambiguous` +
-        " — narrow it with .first(), .nth(i), .filter({ hasText }) or a more specific query";
+        " — scope to the intended container, use an exact role/name, or a stable test ID; " +
+        "use .first()/.nth(i) only when position is part of the test's contract";
     return {
         kind: "strict",
         message: matches.length ? `${head}:\n${matches.join("\n")}` : head,

package/dist/locator.d.ts

@@ -1,3 +1,4 @@
+import type { LocatorAssertionRequest } from "./playwright-assertions.js";
 import type { Page, Locator as PWLocator } from "playwright-core";
 import type { RecordableFields } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
@@ -140,7 +141,7 @@ export declare 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>(action: string, fields: Partial<RecordableFields>, fn: (page: Page) => Promise<T>, opts?: {
@@ -154,30 +155,18 @@ export interface LocatorBackend {
      *  See {@link "./browser".MobileBackend.recordSettled}. */
     recordSettled(action: string, fields: Partial<RecordableFields>, waitedMs: number, error?: string): 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
@@ -189,14 +178,13 @@ export interface LocatorProbe {
         reveal?: boolean;
     }): 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>;
@@ -207,9 +195,7 @@ export declare function attachBrowserProbe<T extends object>(session: T, probe:
 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. */
+/** The assertion/recording seam used by index.ts without loading Playwright. */
 export declare function getLocatorProbe(loc: Locator): LocatorProbe;
 /** Per-session flavor of the `tap()` gesture. Desktop and mobile differ only
  *  here; every other locator method is platform-agnostic. */
@@ -233,9 +219,9 @@ export declare const mobileStrategy: ActionStrategy;
  * 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 {
     /** Descendant CSS query, scoped to this locator's subtree. */
@@ -251,13 +237,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;
     click(opts?: ClickOptions): Promise<void>;
     dblclick(opts?: ClickOptions): Promise<void>;
@@ -312,11 +300,15 @@ export interface Locator {
     blur(opts?: TimeoutOption): Promise<void>;
     scrollIntoViewIfNeeded(opts?: TimeoutOption): Promise<void>;
     dragTo(target: Locator, opts?: TimeoutOption): Promise<void>;
+    /** 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>>;
@@ -324,8 +316,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[]>>;

package/dist/locator.js

@@ -244,9 +244,7 @@ export function isBrowserSession(x) {
 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. */
+/** The assertion/recording seam used by index.ts without loading Playwright. */
 export function getLocatorProbe(loc) {
     return loc[PROBE];
 }
@@ -476,23 +474,23 @@ export function makeLocator(backend, strategy, chain) {
         const rec = { selector: label, target, ...fields };
         return backend.pageOp(action, rec, (page) => readable(page, () => withTarget(page, action, rec, fn)), { wrap: true });
     };
-    // Silent, non-recorded reads for expect(locator) matchers to poll.
+    // Native assertion and recording seam for expect(locator).
     const probe = {
         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 = { 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/dist/playwright-assertions.d.ts

@@ -0,0 +1,11 @@
+import type { Locator, Page } from "playwright-core";
+import type { BrowserMatchers, LocatorMatchers } from "./index.js";
+export type LocatorAssertionRequest = {
+    [K in keyof LocatorMatchers]: {
+        matcher: K;
+        args: Parameters<LocatorMatchers[K]>;
+        negated: boolean;
+    };
+}[keyof LocatorMatchers];
+export declare function assertLocator(locator: Locator, request: LocatorAssertionRequest): Promise<void>;
+export declare function assertURL(page: Page, negated: boolean, ...[expected, options]: Parameters<BrowserMatchers["toHaveURL"]>): Promise<void>;

package/dist/playwright-assertions.js

@@ -0,0 +1,32 @@
+// 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 { DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
+import { globToRegExp } from "./url-match.js";
+const browserExpect = expect.configure({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
+export async function assertLocator(locator, request) {
+    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 = request;
+            throw new Error(`Unsupported locator assertion: ${String(unsupported)}`);
+        }
+    }
+}
+export async function assertURL(page, negated, ...[expected, options]) {
+    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/dist/text-match.d.ts

@@ -7,16 +7,9 @@
  */
 export declare 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;
 }
-/** The element's text equals `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export declare function matchesText(actual: string, expected: string | RegExp, opts?: TextMatchOptions): boolean;
-/** The element's text contains `expected`, with whitespace normalized on both
- *  sides. A RegExp is tested against the normalized text. */
-export declare function containsText(actual: string, expected: string | RegExp, opts?: TextMatchOptions): boolean;
 /** `" "` for an invisible character, the character itself otherwise.
  *  Applied to an ALREADY `JSON.stringify`-ed string, so the result stays a
  *  valid JSON string literal. */
@@ -31,9 +24,3 @@ export declare function escapeInvisible(s: string): string;
  * `"contains"` for the substring ones.
  */
 export declare function textDifferenceNote(actual: unknown, expected: unknown, mode: "equal" | "contains"): string;
-/** Every element's text equals the item at its position, and there are
- *  exactly as many elements as items. */
-export declare function matchesTextArray(actual: string[], expected: (string | RegExp)[], opts?: TextMatchOptions): boolean;
-/** The elements' texts contain every item, in order. Extra elements between
- *  the matches are allowed. */
-export declare function containsTextArray(actual: string[], expected: (string | RegExp)[], opts?: TextMatchOptions): boolean;