@specific.dev/spectest 0.122.0 → 0.123.0

package/README.md

@@ -8,13 +8,22 @@ Install the SDK in your project's `spectest/` directory:
 
 ```sh
 mkdir -p spectest
-npm install --prefix spectest --save-exact @specific.dev/spectest@0.88.3
+npm install --prefix spectest --save-exact @specific.dev/spectest
 ```
 
 Install the [Spectest CLI](https://github.com/specific-dev/spectest/releases/latest)
 and run `spectest docs /installation` for project setup and authentication.
 `spectest docs` contains the complete offline authoring guide.
 
+For browser tests, read `spectest docs /tests/browser`; for phone-emulated Expo
+apps, read `spectest docs /tests/mobile`. The shared test model is in `/tests`. Prefer
+unique, scoped role/name or test-ID locators and awaited browser assertions:
+`await expect(browser.getByRole("status")).toHaveText("Saved")`. A one-time read
+inside `expect` does not retry. Observe the exact saved state before dependent
+work; do not replace readiness with sleeps or arbitrary `.first()` selections.
+SDK 0.123.0 uses native Playwright assertions while retaining Spectest's API and
+recording. Ambiguous single-element selectors fail immediately; make them unique.
+
 Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 `pubsub`/`pubsubClient` exports and `/components/gcp` entry point are removed.
 Use a local service definition or `serviceGroup()` wrapper; the repository’s

package/dist/browser.js

@@ -1554,9 +1554,8 @@ function buildBackend(holder, recorder, buildOpts) {
             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`.
+                    // Preserve Spectest's glob dialect. URL assertions use the same
+                    // glob compiler through their native matcher adapter.
                     await holder.page.waitForURL((u) => matchesUrl(u.href, pattern), {
                         timeout: timeoutMs,
                         waitUntil: options.waitUntil ?? "commit",
@@ -1763,12 +1762,15 @@ 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 seam `expect(browser).toHaveURL(...)` uses: a native assertion 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(),
+        assertURL: async (negated, expected, opts) => {
+            const { assertURL } = await import("./playwright-assertions.js");
+            await assertURL(holder.page, negated, expected, opts);
+        },
         settle: (action, waitedMs, error) => backend.recordSettled(action, { url: holder.page.url() }, waitedMs, error),
     });
     return { backend, detach: endRecording };

package/dist/index.d.ts

@@ -363,7 +363,8 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      */
     readonly fakes: FakeHandlesFor<F>;
     /**
-     * Poll a predicate until it returns a truthy value, then return that
+     * Poll a predicate until it returns a value other than null, undefined,
+     * or false, then return that
      * value. In a test it records one `wait` event for the whole loop (with
      * attempt count, total duration, and the description) instead of one
      * event per probe — useful for "wait until pod Running"-style checks
@@ -371,19 +372,20 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * timeline; it's just the loop you'd otherwise hand-roll.
      *
      * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
-     *   `intervalMs` and try again.
+     *   `intervalMs` and try again. A directly returned wrapped value is
+     *   checked using its underlying value. Use `.unwrap()` when branching
+     *   on wrapped primitives inside `fn`; wrapper objects are truthy.
      * - Anything else is the success value and is returned, tagged with
      *   the wait event's seq. Downstream `expect(...)` on it links to
      *   the wait (one logical step), not to N suppressed HTTP calls.
-     * - Throws from `fn` propagate out immediately; the wait event is
-     *   still recorded (with `error` set) so the timeline reflects the
-     *   abort.
+     * - Instrumented fetch transport failures are retried. Other throws
+     *   from `fn` propagate immediately; the wait event records the abort.
      * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
      *
-     * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
-     * don't show up on the event log — the recorder is paused for the
-     * duration. Use `ctx.poll` for read-only observation, not for
-     * stateful work you want recorded.
+     * The winning attempt's events, or the final failed attempt's events,
+     * are retained beneath the wait; earlier attempts are discarded. Use
+     * `ctx.poll` for read-only observation of the exact required state.
+     * Perform mutations once outside the poll so retries cannot repeat them.
      */
     poll<T>(description: string, fn: () => T | null | undefined | false | Promise<T | null | undefined | false>, opts?: {
         timeoutMs?: number;
@@ -1871,9 +1873,10 @@ export interface TextMatcherOptions extends TextMatchOptions {
 }
 /**
  * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
- * `expect(locator)` matchers. Each polls the element until it passes or a
- * deadline elapses (default 5 s, `{ timeout }` overrides) and records an
- * assertion event just like a value `expect`. `await` them — they are async.
+ * `expect(locator)` matchers. Playwright re-resolves the locator until it
+ * passes or a deadline elapses (default 10 s, `{ timeout }` overrides; 0
+ * disables the assertion timeout). Records an assertion event just like a
+ * value `expect`. `await` them — they are async.
  */
 export interface LocatorMatchers {
     /** The element is present and visible. */
@@ -1887,8 +1890,9 @@ export interface LocatorMatchers {
     /**
      * The element's text equals `expected`, or matches it when it is a RegExp.
      *
-     * **Whitespace is normalized on both sides**, exactly as playwright does
-     * it: the text is trimmed and every run of whitespace becomes one space.
+     * **String expectations normalize whitespace on both sides**, as Playwright
+     * does. Regex expectations test the original text. String comparisons trim
+     * the text and collapse every run of whitespace to one space.
      * So a typed space matches the no-break space (U+00A0) that
      * `Intl.NumberFormat` puts between thousands, and a value wrapped across
      * two lines in the markup matches the one-line string you wrote.
@@ -1899,7 +1903,8 @@ export interface LocatorMatchers {
     toHaveText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
     /**
      * The element's text contains `expected` — a substring, or a RegExp tested
-     * against the text. Whitespace is normalized as in {@link toHaveText}.
+     * against the text. Strings normalize whitespace as in {@link toHaveText};
+     * regexes test the original text.
      *
      * An **array** asserts that the matched elements contain these texts in
      * order; unlike `toHaveText` extra elements between them are allowed.
@@ -1930,8 +1935,8 @@ export interface LocatorAssertion extends 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.
+ * condition holds or the deadline elapses (default 10 s; 0 disables the
+ * assertion timeout) and record one assertion under a settled browser step.
  */
 export interface BrowserMatchers {
     /**

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,