@specific.dev/spectest 0.121.0 → 0.123.0

package/src/index.ts

@@ -1,3 +1,5 @@
+import { stripVTControlCharacters } from "node:util";
+import type { LocatorAssertionRequest } from "./playwright-assertions.js";
 import type { InjectRule, SignConfig } from "./fake-upstream.js";
 export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
@@ -134,26 +136,16 @@ import {
   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,
   type TextMatchOptions,
 } from "./text-match.js";
 
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
-import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { describeUrlPattern } from "./url-match.js";
 
 // Mobile (Expo / React Native Web) surface: a phone-emulated session driven
 // with the same locators + touch gestures, replayed inside a phone bezel.
@@ -547,7 +539,8 @@ export interface SpectestContext<
    */
   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
@@ -555,19 +548,20 @@ export interface SpectestContext<
    * 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,
@@ -2951,9 +2945,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. */
@@ -2963,8 +2958,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.
@@ -2978,7 +2974,8 @@ export interface LocatorMatchers {
   ): 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.
@@ -3004,8 +3001,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 {
   /**
@@ -3063,8 +3060,57 @@ function expectValue(actual: Provenanced, message?: string): Expectation {
 
 // ── 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: string,
+  expected: unknown,
+  negated: boolean,
+  message: string | undefined,
+  assert: () => Promise<void>,
+  settle: (durationMs: number, error?: string) => Promise<number | undefined>,
+  diagnostics?: (error: string) => Promise<string>,
+): Promise<void> {
+  const started = Date.now();
+  let failure: ExpectationError | undefined;
+  let actual: unknown;
+  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 as { matcherResult?: { actual?: unknown } } | null)?.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: unknown): unknown {
+  return value instanceof RegExp ? String(value)
+    : Array.isArray(value) ? value.map(assertionExpected) : value;
+}
 
 function buildLocatorAssertion(loc: Locator, message?: string): LocatorAssertion {
   return Object.assign(buildLocatorMatchers(loc, false, message), {
@@ -3072,294 +3118,38 @@ function buildLocatorAssertion(loc: Locator, message?: string): LocatorAssertion
   });
 }
 
-function buildLocatorMatchers(
-  loc: Locator,
-  negated: boolean,
-  message?: string,
-): LocatorMatchers {
+function buildLocatorMatchers(loc: Locator, negated: boolean, message?: string): LocatorMatchers {
   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: string,
-    timeout: number | undefined,
-    check: () => Promise<{ satisfied: boolean; actual: unknown }>,
-    describe: (actual: unknown) => string,
-    expected?: unknown,
-  ): Promise<void> => {
-    const started = Date.now();
-    const budget = timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
-    const deadline = started + budget;
-    let actual: unknown;
-    // 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: LocatorAssertionRequest): Promise<void> => {
+    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 (): Promise<string> => {
-      try {
-        return await probe.nearMiss();
-      } catch {
-        return "";
-      }
-    };
-    const elementFailure = async (err: unknown): Promise<string | undefined> => {
-      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: unknown;
-    for (;;) {
-      let satisfied: boolean;
-      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 as Error)?.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?: TextMatcherOptions): Promise<string> =>
-    opts?.useInnerText
-      ? await probe.innerText(opts.timeout)
-      : ((await probe.textContent(opts?.timeout)) ?? "");
-  const readTexts = async (opts?: TextMatcherOptions): Promise<string[]> =>
-    opts?.useInnerText ? await probe.allInnerTexts() : await probe.allTextContents();
-  const isArrayExpectation = (
-    v: string | RegExp | Array<string | RegExp>,
-  ): v is Array<string | RegExp> => Array.isArray(v);
-  /** Expected values render as themselves; a RegExp renders as its source. */
-  const fmtExpected = (v: string | RegExp | Array<string | RegExp>): string =>
-    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: string | RegExp | Array<string | RegExp>,
-  ): unknown => (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: unknown, message?: string): BrowserAssertion {
   return Object.assign(buildBrowserMatchers(session, false, message), {
@@ -3367,55 +3157,14 @@ function buildBrowserAssertion(session: unknown, message?: string): BrowserAsser
   });
 }
 
-function buildBrowserMatchers(
-  session: unknown,
-  negated: boolean,
-  message?: string,
-): BrowserMatchers {
+function buildBrowserMatchers(session: unknown, negated: boolean, message?: string): BrowserMatchers {
   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/src/locator-assertions.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, expect, test } from "bun:test";
+import { expect as assert, ExpectationError } from "./index.js";
+import { desktopStrategy, getLocatorProbe, makeLocator, type LocatorBackend } from "./locator.js";
+import { recordBrowser, startRecording, stopRecording } from "./recorder.js";
+
+afterEach(() => stopRecording());
+
+// Test our recording/error boundary separately from native browser semantics.
+function subject(evaluate: () => Promise<void>) {
+  const backend: LocatorBackend = {
+    async pageOp() { throw new Error("unexpected action"); },
+    async silentRead() { throw new Error("unexpected backend read"); },
+    async rawTap() {},
+    async recordSettled() { throw new Error("unexpected backend recording"); },
+  };
+  const locator = makeLocator(backend, desktopStrategy, { steps: [{ m: "locator", args: ["#target"] }] });
+  Object.assign(getLocatorProbe(locator), {
+    assert: evaluate,
+    nearMiss: async () => { throw new Error("diagnostics unavailable"); },
+    settle: async (action: string, durationMs: number, error?: string) =>
+      recordBrowser({ action, selector: 'css "#target"', durationMs, error }),
+  });
+  return locator;
+}
+
+for (const cause of [undefined, new Error("Connection closed")]) {
+  for (const negated of [false, true]) {
+    test(`records a failed ${negated ? "negative" : "positive"} assertion even for ${String(cause)}`, async () => {
+      const locator = subject(async () => { throw cause; });
+      startRecording();
+      const matcher = negated ? assert(locator).not : assert(locator);
+      await expect(matcher.toHaveText("Saved")).rejects.toBeInstanceOf(ExpectationError);
+      const events = stopRecording();
+      expect(events).toHaveLength(2);
+      expect(events[0]).toMatchObject({ kind: "browser", error: expect.any(String) });
+      expect(events[1]).toMatchObject({ kind: "assertion", passed: false, negated, sourceSeq: events[0]!.seq });
+    });
+  }
+}
+
+test("records native failure evidence even if supplemental diagnostics fail", async () => {
+  const cause = Object.assign(new Error("\u001b[31melement(s) not found\u001b[0m"), { matcherResult: { actual: [] } });
+  startRecording();
+  await expect(assert(subject(async () => { throw cause; }), "saved state").toHaveText(["Saved"]))
+    .rejects.toMatchObject({ message: "element(s) not found", cause });
+  expect(stopRecording()[1]).toMatchObject({
+    kind: "assertion", passed: false, actual: [], expected: ["Saved"], message: "saved state",
+    error: "element(s) not found",
+  });
+});
+
+test("success records provenance without fabricating an observed value", async () => {
+  startRecording();
+  await assert(subject(async () => {})).toHaveText(/Saved/);
+  const events = stopRecording();
+  expect(events).toHaveLength(2);
+  expect(events[1]).toMatchObject({ kind: "assertion", passed: true, expected: "/Saved/", sourceSeq: events[0]!.seq });
+  expect(events[1]!.actual).toBeUndefined();
+});

package/src/locator-errors.test.ts

@@ -101,8 +101,8 @@ describe("locatorFailureMessage", () => {
         "    2) <button>Save all</button> aka getByRole('button', { name: 'Save all' })\n",
     );
     expect(locatorFailureMessage("role button", strict)).toBe(
-      "role button matches 2 elements, so it is ambiguous — narrow it with .first(), " +
-        ".nth(i), .filter({ hasText }) or a more specific query:\n" +
+      "role button matches 2 elements, so it is ambiguous — 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:\n" +
         "  - <button>Save</button> aka getByRole('button', { name: 'Save' })\n" +
         "  - <button>Save all</button> aka getByRole('button', { name: 'Save all' })",
     );
@@ -111,8 +111,8 @@ describe("locatorFailureMessage", () => {
   test("an ambiguous locator with no listed matches still says what to do", () => {
     const strict = new Error("strict mode violation: locator('p') resolved to 7 elements");
     expect(locatorFailureMessage('css "p"', strict)).toBe(
-      'css "p" matches 7 elements, so it is ambiguous — narrow it with .first(), ' +
-        ".nth(i), .filter({ hasText }) or a more specific query",
+      'css "p" matches 7 elements, so it is ambiguous — 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",
     );
   });
 });

package/src/locator-errors.ts

@@ -124,7 +124,8 @@ function parseStrictViolation(err: unknown, label: string): LocatorFailure | und
     .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,