@specific.dev/spectest 0.66.0 → 0.68.0

package/src/index.ts

@@ -116,7 +116,20 @@ import {
   getBrowserProbe,
   DEFAULT_ACTION_TIMEOUT_MS,
 } from "./locator.js";
-import { formatWaited, locatorFailureMessage } from "./locator-errors.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";
@@ -182,7 +195,8 @@ export type { InterceptHandler, InterceptNext, InterceptedRequest };
  */
 export interface Interception {
   hostname: string;
-  /** The normalised mount path (`"/"` when none was given). */
+  /** The normalised mount path parsed off the target (`"/"` when the
+   *  target was a bare hostname). */
   path: string;
   /** How many requests the interceptor has seen. Provenance-wrapped, so an
    *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
@@ -545,12 +559,23 @@ export interface SpectestContext<
    * make your **own** backend misbehave for one test: force a 500 from an
    * API route, add latency, fail twice then pass, or just count calls.
    *
+   * `target` is the hostname, optionally with a mount path:
+   * `"app.test"` claims every request to that host, `"app.test/api/sync"`
+   * claims that path and everything below it (like `app.use(path, fn)`).
+   *
+   * `description` is what the environment now **does**, in the present
+   * tense — it is the step's whole title in the timeline and in the CLI's
+   * failure detail, so it is what tells a reader why the page under test
+   * went to its error state. Write the effect, not the act of intercepting
+   * (the step is already labelled INTERCEPT) and not the test's goal:
+   * `"the sync endpoint returns 503"`, not `"intercept sync"`, `"mock the
+   * API"` or `"test error handling"`. The handler's own source is shown
+   * under it, so the description carries the intent, never the mechanism.
+   *
    * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
    * response (a proxied service, or a fake). Return a `Response` to answer
    * yourself, `next()` to pass through, or change what `next()` returned.
-   * An optional mount `path` limits it to that path and everything below
-   * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
-   * registration order.
+   * Interceptors run in registration order.
    *
    * Only traffic that reaches the daemon can be intercepted: the browser,
    * `ctx.fetch`, and any container that calls the hostname — so the service
@@ -564,16 +589,18 @@ export interface SpectestContext<
    * `remove()`. Every request it sees is recorded under the intercept step.
    *
    * ```ts
-   * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
-   *   new Response("boom", { status: 500 }));
+   * const outage = ctx.intercept(
+   *   "api.test/functions/v1/sync",
+   *   "the sync function returns 500",
+   *   () => new Response("boom", { status: 500 }),
+   * );
    * await page.getByRole("button", { name: "Sync" }).click();
    * await expect(page.getByText("Retry")).toBeVisible();
    * expect(outage.calls).toBe(1);
    * outage.remove();                           // the retry now reaches the real function
    * ```
    */
-  intercept(hostname: string, handler: InterceptHandler): Interception;
-  intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
+  intercept(target: string, description: string, handler: InterceptHandler): Interception;
   /**
    * Mint a leaf certificate from the in-VM root CA and return the PEMs.
    *
@@ -2657,6 +2684,15 @@ export interface Expectation extends Matchers {
   not: Matchers;
 }
 
+/** Options for the text matchers — playwright's set, same names, same
+ *  meanings. */
+export interface TextMatcherOptions extends TextMatchOptions {
+  timeout?: number;
+  /** Read `innerText` (what the page renders — hidden elements dropped,
+   *  `text-transform` applied) instead of `textContent`. */
+  useInnerText?: boolean;
+}
+
 /**
  * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
  * `expect(locator)` matchers. Each polls the element until it passes or a
@@ -2668,10 +2704,33 @@ export interface LocatorMatchers {
   toBeVisible(opts?: { timeout?: number }): Promise<void>;
   /** The element is absent or hidden. */
   toBeHidden(opts?: { timeout?: number }): Promise<void>;
-  /** The element's (trimmed) text equals `expected` (or matches a RegExp). */
-  toHaveText(expected: string | RegExp, opts?: { timeout?: number }): Promise<void>;
-  /** The element's text contains `expected`. */
-  toContainText(expected: string, opts?: { timeout?: number }): Promise<void>;
+  /**
+   * 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.
+   * 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.
+   *
+   * Pass an **array** to assert over every element the locator matches, in
+   * order; the counts must then agree.
+   */
+  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}.
+   *
+   * An **array** asserts that the matched elements contain these texts in
+   * order; unlike `toHaveText` extra elements between them are allowed.
+   */
+  toContainText(
+    expected: string | RegExp | Array<string | RegExp>,
+    opts?: TextMatcherOptions,
+  ): Promise<void>;
   /** The input's value equals `expected` (or matches a RegExp). */
   toHaveValue(expected: string | RegExp, opts?: { timeout?: number }): Promise<void>;
   /** The locator resolves to exactly `expected` elements. */
@@ -2805,12 +2864,32 @@ function buildLocatorMatchers(
     // 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) return locatorFailureMessage(probe.label, 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)})`;
+          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
@@ -2882,8 +2961,29 @@ function buildLocatorMatchers(
   };
 
   const not = negated ? " not" : "";
-  const matchesText = (v: string, expected: string | RegExp): boolean =>
-    expected instanceof RegExp ? expected.test(v) : v === expected;
+  // 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) =>
@@ -2911,33 +3011,53 @@ function buildLocatorMatchers(
         "toHaveText",
         opts?.timeout,
         async () => {
-          const t = (await probe.textContent(opts?.timeout)) ?? "";
-          return { satisfied: matchesText(t.trim(), expected), actual: t };
+          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 ${fmt(expected)}, got ${fmt(a)}`,
-        expected instanceof RegExp ? String(expected) : expected,
+        (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 () => {
-          const t = (await probe.textContent(opts?.timeout)) ?? "";
-          return { satisfied: t.includes(expected), actual: t };
+          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 ${fmt(expected)}, got ${fmt(a)}`,
-        expected,
+        (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);
-          return { satisfied: matchesText(v, expected), actual: v };
+          const satisfied = expected instanceof RegExp ? expected.test(v) : v === expected;
+          return { satisfied, actual: v };
         },
-        (a) => `expected ${probe.label}${not} to have value ${fmt(expected)}, got ${fmt(a)}`,
-        expected instanceof RegExp ? String(expected) : expected,
+        (a) =>
+          `expected ${probe.label}${not} to have value ${fmtExpected(expected)}, got ${fmt(a)}` +
+          textDifferenceNote(a, expected, "equal"),
+        expectedValue(expected),
       ),
     toHaveCount: (expected, opts) =>
       run(
@@ -3162,7 +3282,8 @@ function buildCore(
       run(
         "toBe",
         Object.is(actual, exp),
-        `expected ${fmt(actual)}${negated ? " not" : ""} to be ${fmt(exp)}`,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to be ${fmt(exp)}` +
+          textDifferenceNote(actual, exp, "equal"),
         exp,
       );
     },
@@ -3177,7 +3298,8 @@ function buildCore(
       run(
         "toEqual",
         equal,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to deep-equal ${fmt(exp)}`,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to deep-equal ${fmt(exp)}` +
+          textDifferenceNote(actual, exp, "equal"),
         exp,
       );
     },
@@ -3245,7 +3367,8 @@ function buildCore(
       run(
         "toContain",
         contained,
-        `expected ${fmt(actual)}${negated ? " not" : ""} to contain ${fmt(exp)}`,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to contain ${fmt(exp)}` +
+          textDifferenceNote(actual, exp, "contains"),
         exp,
       );
     },
@@ -3295,7 +3418,11 @@ function buildCore(
 }
 
 function fmt(v: unknown): string {
-  if (typeof v === "string") return JSON.stringify(v);
+  // A string is escaped down to its invisible characters, so two values that
+  // print the same on screen do not print the same in a failure. Without it a
+  // no-break space and a space are the same three characters wide, and the
+  // message reads "expected "15 000 kr", got "15 000 kr"".
+  if (typeof v === "string") return escapeInvisible(JSON.stringify(v));
   if (typeof v === "bigint") return `${v}n`;
   if (v === undefined) return "undefined";
   try {

package/src/locator-errors.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
 
-import { formatWaited, locatorFailureMessage, rewriteLocatorError } from "./locator-errors.js";
+import {
+  classifyLocatorFailure,
+  formatWaited,
+  locatorFailureMessage,
+  rewriteLocatorErrorWithHints,
+} from "./locator-errors.js";
 
 /** A playwright actionability timeout, shaped exactly as playwright-core
  *  1.61 raises one: `name`, the message with the call log appended, the same
@@ -83,22 +88,105 @@ describe("locatorFailureMessage", () => {
     );
   });
 
-  test("leaves errors that are not locator timeouts alone", () => {
-    const strict = new Error(
-      "click: Error: strict mode violation: locator('p') resolved to 2 elements",
-    );
-    expect(locatorFailureMessage('css "p"', strict)).toBeUndefined();
+  test("leaves errors that are neither a timeout nor a strict violation alone", () => {
     expect(locatorFailureMessage('css "p"', new Error("page closed"))).toBeUndefined();
     expect(locatorFailureMessage('css "p"', "not an error at all")).toBeUndefined();
   });
+
+  test("an ambiguous locator says how to narrow it, and lists the matches", () => {
+    // Playwright's own shape: the count, then one numbered line per match.
+    const strict = new Error(
+      "click: Error: strict mode violation: getByRole('button') resolved to 2 elements:\n" +
+        "    1) <button>Save</button> aka getByRole('button', { name: 'Save' })\n" +
+        "    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" +
+        "  - <button>Save</button> aka getByRole('button', { name: 'Save' })\n" +
+        "  - <button>Save all</button> aka getByRole('button', { name: 'Save all' })",
+    );
+  });
+
+  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",
+    );
+  });
+});
+
+describe("classifyLocatorFailure", () => {
+  test("only a locator that matched nothing is worth asking the page about", () => {
+    const missing = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for getByTestId('add')",
+    ]);
+    expect(classifyLocatorFailure('testid "add"', missing)?.kind).toBe("no-match");
+
+    const disabled = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for locator('#dis')",
+      '    - locator resolved to <button id="dis" disabled>Nope</button>',
+      "      - element is not enabled",
+    ]);
+    expect(classifyLocatorFailure('css "#dis"', disabled)?.kind).toBe("state");
+
+    const strict = new Error("strict mode violation: locator('p') resolved to 2 elements");
+    expect(classifyLocatorFailure('css "p"', strict)?.kind).toBe("strict");
+  });
+});
+
+describe("rewriteLocatorErrorWithHints", () => {
+  const missing = (): Error =>
+    timeoutError("click: Timeout 5000ms exceeded.", ["  - waiting for getByTestId('add')"]);
+
+  test("appends the near-miss block to a locator that matched nothing", async () => {
+    const err = (await rewriteLocatorErrorWithHints(missing(), 'testid "add"', async () =>
+      "\nClose matches on the page:\n  - testid \"add-todo\"",
+    )) as Error;
+    expect(err.message).toBe(
+      'No element matches testid "add" (waited 5s)\n' +
+        'Close matches on the page:\n  - testid "add-todo"',
+    );
+    // The stack's copy of the message is rewritten too, or the CLI would
+    // print the friendly sentence and the raw timeout under it.
+    expect(err.stack).toContain('Close matches on the page');
+    expect(err.stack).not.toContain("Timeout 5000ms exceeded");
+  });
+
+  test("never asks the page about a failure it could not explain", async () => {
+    const disabled = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for locator('#dis')",
+      '    - locator resolved to <button id="dis" disabled>Nope</button>',
+      "      - element is not enabled",
+    ]);
+    let asked = false;
+    const err = (await rewriteLocatorErrorWithHints(disabled, 'css "#dis"', async () => {
+      asked = true;
+      return "should not appear";
+    })) as Error;
+    expect(asked).toBe(false);
+    expect(err.message).toBe('Element css "#dis" is not enabled (waited 5s)');
+  });
+
+  test("a diagnostic that throws leaves the failure standing", async () => {
+    const err = (await rewriteLocatorErrorWithHints(missing(), 'testid "add"', async () => {
+      throw new Error("page closed");
+    })) as Error;
+    expect(err.message).toBe('No element matches testid "add" (waited 5s)');
+  });
 });
 
-describe("rewriteLocatorError", () => {
-  test("rewrites the message AND the copy embedded in the stack", () => {
+describe("rewriteLocatorErrorWithHints (stack)", () => {
+  test("rewrites the message AND the copy embedded in the stack", async () => {
     const err = timeoutError("click: Timeout 5000ms exceeded.", [
       "  - waiting for getByTestId('add')",
     ]);
-    const out = rewriteLocatorError(err, 'testid "add"') as Error;
+    const out = (await rewriteLocatorErrorWithHints(
+      err,
+      'testid "add"',
+      async () => "",
+    )) as Error;
 
     expect(out).toBe(err); // same error: the author's own frames survive
     expect(out.message).toBe('No element matches testid "add" (waited 5s)');
@@ -107,9 +195,9 @@ describe("rewriteLocatorError", () => {
     expect(out.stack).toContain("todo.ts:12:34");
   });
 
-  test("hands back anything it does not understand untouched", () => {
+  test("hands back anything it does not understand untouched", async () => {
     const err = new Error("page closed");
-    expect(rewriteLocatorError(err, 'css "p"')).toBe(err);
+    expect(await rewriteLocatorErrorWithHints(err, 'css "p"', async () => "")).toBe(err);
     expect(err.message).toBe("page closed");
   });
 });

package/src/locator-errors.ts

@@ -8,10 +8,15 @@
 // as an infrastructure problem and says nothing about the page.
 //
 // This module turns those into one sentence that names the element and what
-// was wrong with it. Anything it does not recognise (a strict-mode violation,
-// a closed page, an assertion of ours) is passed through untouched — the rule
-// is that a message is only ever replaced when we have something better to
-// say.
+// was wrong with it. A strict-mode violation — the opposite failure, where the
+// locator matched too much — is rewritten too, keeping playwright's own list
+// of matches, which is the useful half of it. Anything else (a closed page, an
+// assertion of ours) is passed through untouched: the rule is that a message is
+// only ever replaced when we have something better to say.
+//
+// `classifyLocatorFailure` also says WHICH failure it was, because only one of
+// them — a locator that matched nothing — can be explained further by asking
+// the page what it holds (see locator-hints.ts).
 //
 // The call log is read from the error's own `log` array (playwright attaches
 // it) and falls back to parsing the message, since only the message survives
@@ -92,38 +97,87 @@ function actionabilityReason(log: string[]): string | undefined {
   return undefined;
 }
 
+/** How a locator failed. `no-match` is the only kind worth asking the page
+ *  about (see locator-hints.ts) — for every other kind the element was found
+ *  and near misses would be noise. */
+export type LocatorFailureKind = "no-match" | "state" | "strict";
+
+export interface LocatorFailure {
+  message: string;
+  kind: LocatorFailureKind;
+}
+
+/** Playwright's strict-mode violation: the locator matched more than one
+ *  element and refused to act. It is an ordinary `Error`, not a
+ *  `TimeoutError`, and its message already lists the matches — which is the
+ *  useful half, so it is kept and only the wall of text around it is cut. */
+function parseStrictViolation(err: unknown, label: string): LocatorFailure | undefined {
+  const e = err as { message?: unknown } | null;
+  if (!e || typeof e.message !== "string") return undefined;
+  if (!e.message.includes("strict mode violation")) return undefined;
+  const m = /resolved to (\d+) elements/.exec(e.message);
+  if (!m) return undefined;
+  const matches = e.message
+    .split("\n")
+    .filter((l) => /^\s*\d+\)\s/.test(l))
+    .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";
+  return {
+    kind: "strict",
+    message: matches.length ? `${head}:\n${matches.join("\n")}` : head,
+  };
+}
+
 /**
- * The sentence to fail with, or `undefined` when `err` is not a locator
- * timeout we understand (in which case the caller must leave it alone).
+ * What to fail with, or `undefined` when `err` is not a locator failure we
+ * understand (in which case the caller must leave it alone).
  *
  * `label` is the locator's human chain label, the same string the timeline
  * step shows.
  */
-export function locatorFailureMessage(label: string, err: unknown): string | undefined {
+export function classifyLocatorFailure(
+  label: string,
+  err: unknown,
+): LocatorFailure | undefined {
+  const strict = parseStrictViolation(err, label);
+  if (strict) return strict;
   const detail = parseTimeout(err);
   if (!detail) return undefined;
   const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
-  if (!resolved(detail.log)) return `No element matches ${label} ${waited}`;
+  if (!resolved(detail.log)) {
+    return { kind: "no-match", message: `No element matches ${label} ${waited}` };
+  }
 
   // It matched, so the failure is about the element's state.
+  const state = (message: string): LocatorFailure => ({ kind: "state", message });
   switch (waitedForState(detail.log)) {
     case "hidden":
-      return `Element ${label} is still visible ${waited}`;
+      return state(`Element ${label} is still visible ${waited}`);
     case "detached":
-      return `Element ${label} is still attached to the page ${waited}`;
+      return state(`Element ${label} is still attached to the page ${waited}`);
     case "visible":
-      return `Element ${label} is not visible ${waited}`;
+      return state(`Element ${label} is not visible ${waited}`);
     default:
       break;
   }
   const reason = actionabilityReason(detail.log);
-  return reason
-    ? `Element ${label} ${reason} ${waited}`
-    : `Element ${label} never became ready for this action ${waited}`;
+  return state(
+    reason
+      ? `Element ${label} ${reason} ${waited}`
+      : `Element ${label} never became ready for this action ${waited}`,
+  );
+}
+
+/** The sentence alone. See {@link classifyLocatorFailure}. */
+export function locatorFailureMessage(label: string, err: unknown): string | undefined {
+  return classifyLocatorFailure(label, err)?.message;
 }
 
 /**
- * Replace a locator timeout's message in place and hand the error back, so the
+ * Replace a locator failure's message in place and hand the error back, so the
  * caller can `throw` it unchanged in every other respect.
  *
  * The error is mutated rather than wrapped: its stack holds the frames of the
@@ -132,10 +186,8 @@ export function locatorFailureMessage(label: string, err: unknown): string | und
  * too — otherwise the CLI's failure block would print the friendly message and
  * then the timeout wall right under it.
  */
-export function rewriteLocatorError(err: unknown, label: string): unknown {
-  const message = locatorFailureMessage(label, err);
-  if (message === undefined) return err;
-  const e = err as Error;
+/** Put `message` on `err`, in the message and in the stack's copy of it. */
+function setErrorMessage(e: Error, message: string): Error {
   const old = e.message;
   if (typeof e.stack === "string") {
     for (const [header, replacement] of [
@@ -151,3 +203,30 @@ export function rewriteLocatorError(err: unknown, label: string): unknown {
   e.message = message;
   return e;
 }
+
+/**
+ * The rewrite above, plus the near-miss block for the one failure that can
+ * carry one — a locator that matched nothing.
+ *
+ * `hints` is only called in that case, so a page query is never made for a
+ * failure it could not explain (a disabled element, a covered one, an
+ * ambiguous match). It is expected to be best-effort itself; anything it
+ * throws leaves the plain sentence standing.
+ */
+export async function rewriteLocatorErrorWithHints(
+  err: unknown,
+  label: string,
+  hints: () => Promise<string>,
+): Promise<unknown> {
+  const failure = classifyLocatorFailure(label, err);
+  if (!failure) return err;
+  let message = failure.message;
+  if (failure.kind === "no-match") {
+    try {
+      message += await hints();
+    } catch {
+      /* A diagnostic must never replace the failure it explains. */
+    }
+  }
+  return setErrorMessage(err as Error, message);
+}