@specific.dev/spectest 0.66.0 → 0.68.0

package/src/locator-hints.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from "bun:test";
+
+// The ranking and the snapshot parsing are pure, so they are tested here. The
+// collection half needs a real browser, and was verified against one — every
+// fixture below is captured from that run rather than imagined. To repeat it,
+// write a script under `sdk/` (so it resolves this SDK's own playwright-core,
+// not a newer one from bun's cache), `page.setContent(...)` a page with the
+// cases you care about, and call `nearMissHints(page, target)` directly:
+//
+//   cd sdk && LD_LIBRARY_PATH=/tmp/chromium-scratch/root/usr/lib/aarch64-linux-gnu \
+//     FONTCONFIG_FILE=/tmp/chromium-scratch/fonts.conf bun my-harness.ts
+//
+// (that library path is the no-sudo Chromium recipe this box already carries;
+// `chromium.launch({ args: ["--no-sandbox"] })` then works.) Measured there:
+// 3–20 ms per diagnostic, which is why it can run on every failed locator.
+
+import {
+  buildSuggestions,
+  closeness,
+  EMPTY_DOM_FACTS,
+  parseAriaSnapshot,
+  suggestionLine,
+  type DomFacts,
+} from "./locator-hints.js";
+
+/** A page's accessibility tree exactly as `page.ariaSnapshot()` rendered it —
+ *  captured from playwright-core 1.61.1 driving headless Chromium against the
+ *  fixture page in this module's verification harness. Note the shapes a
+ *  hand-written fixture would have missed: a node's own text after the name
+ *  (`: Spara`), property lines (`/placeholder:`), state suffixes
+ *  (`[selected]`) and unnamed nodes (`- text:`). */
+const SNAPSHOT = `- banner:
+  - heading "Fakturor" [level=1]
+  - button "Spara ändringar": Spara
+- main:
+  - combobox "Sortera":
+    - option "Datum" [selected]
+  - button "Ny faktura"
+  - button "Ta bort"
+  - button "Ta bort allt"
+  - textbox "Sök":
+    - /placeholder: Sök fakturor
+  - paragraph: "Summa: 15 000 kr"
+  - button "Skicka till kund": Skicka
+  - text: Skicka till kund`;
+
+describe("parseAriaSnapshot", () => {
+  test("reads the role and accessible name off every named node", () => {
+    expect(parseAriaSnapshot(SNAPSHOT)).toEqual([
+      { role: "heading", name: "Fakturor" },
+      { role: "button", name: "Spara ändringar" },
+      { role: "combobox", name: "Sortera" },
+      { role: "option", name: "Datum" },
+      { role: "button", name: "Ny faktura" },
+      { role: "button", name: "Ta bort" },
+      { role: "button", name: "Ta bort allt" },
+      { role: "textbox", name: "Sök" },
+      { role: "button", name: "Skicka till kund" },
+    ]);
+  });
+
+  test("skips nodes with no name, and lines it does not recognise", () => {
+    // A container with no accessible name cannot be suggested by name, and a
+    // property line ("/url: …") is not a node at all.
+    expect(parseAriaSnapshot("- generic:\n  - /url: /x\nnot yaml at all")).toEqual([]);
+  });
+
+  test("unescapes a quoted name", () => {
+    expect(parseAriaSnapshot('- button "Say \\"hi\\""')).toEqual([
+      { role: "button", name: 'Say "hi"' },
+    ]);
+  });
+});
+
+describe("closeness", () => {
+  test("the same string, whitespace and case aside, is the closest", () => {
+    expect(closeness("Spara", "spara")).toBe(4);
+    expect(closeness("15 000 kr", "15 000 kr")).toBe(4);
+  });
+
+  test("a name that carries a suffix scores above a typo", () => {
+    expect(closeness("Spara", "Spara ändringar")).toBeGreaterThan(
+      closeness("Spara", "Spraa"),
+    );
+  });
+
+  test("an unrelated name scores nothing", () => {
+    expect(closeness("Spara", "Avbryt")).toBe(0);
+    expect(closeness("Spara", "")).toBe(0);
+  });
+});
+
+describe("buildSuggestions", () => {
+  const aria = parseAriaSnapshot(SNAPSHOT);
+
+  test("a role query finds the same role under a longer name", () => {
+    const [first] = buildSuggestions(
+      { kind: "role", role: "button", query: "Spara" },
+      aria,
+      EMPTY_DOM_FACTS,
+    );
+    expect(first?.fact).toBe('button "Spara ändringar"');
+    expect(suggestionLine(first!, 1)).toBe(
+      '  - button "Spara ändringar" → getByRole("button", { name: "Spara ändringar" })',
+    );
+  });
+
+  test("a name under the wrong role says which role it really is", () => {
+    const lines = buildSuggestions(
+      { kind: "role", role: "button", query: "Sortera" },
+      aria,
+      EMPTY_DOM_FACTS,
+    );
+    expect(lines[0]?.fact).toBe('combobox "Sortera" — this is a combobox, not a button');
+    expect(lines[0]?.locator).toEqual({
+      m: "getByRole",
+      role: "combobox",
+      name: "Sortera",
+    });
+  });
+
+  test("an aria-label that hides the visible text is called out by name", () => {
+    const dom: DomFacts = {
+      ...EMPTY_DOM_FACTS,
+      mismatches: [
+        { tag: "button", text: "Spara", name: "Spara ändringar", from: "aria-label" },
+      ],
+    };
+    const lines = buildSuggestions(
+      { kind: "role", role: "button", query: "Spara" },
+      [],
+      dom,
+    );
+    expect(lines[0]?.fact).toBe(
+      '<button> shows "Spara" but its accessible name is "Spara ändringar" (from aria-label)',
+    );
+    expect(lines[0]?.locator).toEqual({
+      m: "getByRole",
+      role: "button",
+      name: "Spara ändringar",
+    });
+  });
+
+  test("a test id suggests the test ids the page really carries", () => {
+    const dom: DomFacts = { ...EMPTY_DOM_FACTS, testIds: ["add-todo", "remove-todo"] };
+    const lines = buildSuggestions({ kind: "testId", query: "add" }, [], dom);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]?.locator).toEqual({ m: "getByTestId", id: "add-todo" });
+  });
+
+  test("a RegExp query suggests nothing — a pattern has no near miss", () => {
+    expect(buildSuggestions({ kind: "role", role: "button" }, aria, EMPTY_DOM_FACTS)).toEqual(
+      [],
+    );
+  });
+
+  test("nothing close means nothing is said", () => {
+    expect(
+      buildSuggestions(
+        { kind: "role", role: "button", query: "Ladda upp kvitto" },
+        aria,
+        EMPTY_DOM_FACTS,
+      ),
+    ).toEqual([]);
+  });
+
+  test("at most three lines, best first, one per proposed locator", () => {
+    const dom: DomFacts = {
+      ...EMPTY_DOM_FACTS,
+      texts: ["Faktura 1", "Faktura 2", "Faktura 3", "Faktura 4", "Faktura 5"],
+    };
+    const lines = buildSuggestions({ kind: "text", query: "Faktura 1" }, aria, dom);
+    expect(lines).toHaveLength(3);
+    expect(lines[0]?.locator).toEqual({ m: "getByText", text: "Faktura 1" });
+    expect(new Set(lines.map((l) => JSON.stringify(l.locator))).size).toBe(3);
+  });
+
+  test("the count rides the line when a suggestion is itself ambiguous", () => {
+    const [first] = buildSuggestions(
+      { kind: "role", role: "button", query: "Ta bort" },
+      aria,
+      EMPTY_DOM_FACTS,
+    );
+    expect(suggestionLine(first!, 4)).toBe(
+      '  - button "Ta bort" → getByRole("button", { name: "Ta bort" }) (matches 4 elements)',
+    );
+  });
+});

package/src/locator-hints.ts

@@ -0,0 +1,514 @@
+// "Did you mean…" for a locator that matched nothing.
+//
+// `locator-errors.ts` turns a playwright timeout into one sentence about the
+// element. This module answers the next question, which that sentence cannot:
+// *what IS on the page?* A locator that matches nothing usually misses by a
+// little — the accessible name carries a suffix, an `aria-label` overrides the
+// visible text, the control is a `combobox` and not the `button` it looks
+// like — and every one of those costs a full edit/run round trip to discover.
+//
+// Two sources, both authoritative, neither guessed at:
+//
+//   * **The ARIA snapshot** (`page.ariaSnapshot()`) — playwright's own
+//     accessibility tree, so the accessible names here are exactly the ones
+//     `getByRole(role, { name })` matches against. We never compute an
+//     accessible name ourselves.
+//   * **One DOM pass** for the facts the snapshot drops: visible text of leaf
+//     elements, test ids, placeholders, labels, and — the case that prompted
+//     this — every interactive element whose visible text and name-giving
+//     attribute disagree.
+//
+// Nothing is printed on trust. Each candidate carries the locator that would
+// select it, and `nearMissHints` runs that locator before the line reaches the
+// author: a suggestion that resolves to nothing is dropped rather than sent
+// out to be tried. The whole pass runs only on the failure path, inside a
+// budget, and any error in it is swallowed — a diagnostic must never replace
+// the failure it is explaining.
+
+import type { Page, Locator as PWLocator } from "playwright-core";
+
+import { escapeInvisible, normalizeWhiteSpace } from "./text-match.js";
+
+/** What the author asked for — the last selecting step of a failed chain. */
+export interface HintTarget {
+  kind:
+    | "role"
+    | "text"
+    | "label"
+    | "placeholder"
+    | "altText"
+    | "title"
+    | "testId"
+    | "other";
+  /** The ARIA role, for `kind: "role"`. */
+  role?: string;
+  /** The string the author asked for. Absent for a RegExp query, which we
+   *  make no suggestions from — a near-miss on a pattern is not a near-miss. */
+  query?: string;
+}
+
+/** One role/name pair from the page's accessibility tree. */
+export interface AriaCandidate {
+  role: string;
+  name: string;
+}
+
+/** An interactive element whose visible text is not its accessible name. */
+export interface NameMismatch {
+  tag: string;
+  text: string;
+  name: string;
+  /** The attribute the name came from: `aria-label`, `aria-labelledby`, … */
+  from: string;
+}
+
+/** What the DOM pass brings back. Every list is deduplicated and capped. */
+export interface DomFacts {
+  texts: string[];
+  testIds: string[];
+  placeholders: string[];
+  labels: string[];
+  titles: string[];
+  alts: string[];
+  mismatches: NameMismatch[];
+}
+
+export const EMPTY_DOM_FACTS: DomFacts = {
+  texts: [],
+  testIds: [],
+  placeholders: [],
+  labels: [],
+  titles: [],
+  alts: [],
+  mismatches: [],
+};
+
+/** The locator a suggestion proposes, as data — so the ranking stays pure and
+ *  testable and only `nearMissHints` touches a page. */
+export type SuggestedLocator =
+  | { m: "getByRole"; role: string; name: string }
+  | { m: "getByText"; text: string }
+  | { m: "getByLabel"; text: string }
+  | { m: "getByPlaceholder"; text: string }
+  | { m: "getByAltText"; text: string }
+  | { m: "getByTitle"; text: string }
+  | { m: "getByTestId"; id: string };
+
+export interface Suggestion {
+  /** What is on the page, in the reader's terms. */
+  fact: string;
+  /** The locator that selects it. */
+  locator: SuggestedLocator;
+  /** Higher is closer. Ranking only; never shown. */
+  score: number;
+}
+
+// ── Similarity ────────────────────────────────────────────────────────────
+
+/** Levenshtein distance, with an early exit once `max` is passed. */
+function distance(a: string, b: string, max: number): number {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const v = Math.min(prev[j]! + 1, cur[j - 1]! + 1, prev[j - 1]! + cost);
+      cur.push(v);
+      if (v < best) best = v;
+    }
+    if (best > max) return max + 1;
+    prev = cur;
+  }
+  return prev[b.length]!;
+}
+
+function key(s: string): string {
+  return normalizeWhiteSpace(s).toLowerCase();
+}
+
+/**
+ * How close `candidate` is to what the author asked for, from 0 (unrelated)
+ * to 4 (the same string). Everything at or above `NEAR` is worth showing.
+ */
+export function closeness(query: string, candidate: string): number {
+  const q = key(query);
+  const c = key(candidate);
+  if (!q || !c) return 0;
+  if (q === c) return 4;
+  // A name that carries a suffix or a prefix ("Spara" vs "Spara ändringar")
+  // is the single most common near miss, and `{ exact: false }` or a
+  // substring query would already have matched it.
+  if (c.includes(q) || q.includes(c)) return 3;
+  const max = Math.max(2, Math.floor(Math.max(q.length, c.length) * 0.34));
+  const d = distance(q, c, max);
+  if (d > max) return 0;
+  return 2 - d / (max + 1);
+}
+
+/** The score at which a candidate is close enough to show. */
+const NEAR = 1;
+
+/** How many lines an author can absorb below a failure. */
+const MAX_SUGGESTIONS = 3;
+
+// ── Ranking ───────────────────────────────────────────────────────────────
+
+/** A page string, quoted for reading — with its invisible characters spelled
+ *  out. A suggestion whose only difference from what the author typed is a
+ *  no-break space would otherwise print as the very string that just failed. */
+function quoted(s: string): string {
+  return escapeInvisible(JSON.stringify(s));
+}
+
+function code(loc: SuggestedLocator): string {
+  switch (loc.m) {
+    case "getByRole":
+      return `getByRole(${quoted(loc.role)}, { name: ${quoted(loc.name)} })`;
+    case "getByTestId":
+      return `getByTestId(${quoted(loc.id)})`;
+    default:
+      return `${loc.m}(${quoted(loc.text)})`;
+  }
+}
+
+/** Render one verified suggestion as the line the author reads. */
+export function suggestionLine(s: Suggestion, matches: number): string {
+  const extra = matches > 1 ? ` (matches ${matches} elements)` : "";
+  return `  - ${s.fact} → ${code(s.locator)}${extra}`;
+}
+
+function byScore(a: Suggestion, b: Suggestion): number {
+  return b.score - a.score;
+}
+
+/** Drop repeats of the same proposed locator, keeping the best-scoring one. */
+function dedupe(items: Suggestion[]): Suggestion[] {
+  const seen = new Map<string, Suggestion>();
+  for (const s of items.slice().sort(byScore)) {
+    const k = code(s.locator);
+    if (!seen.has(k)) seen.set(k, s);
+  }
+  return [...seen.values()];
+}
+
+function fromValues(
+  query: string,
+  values: string[],
+  make: (v: string) => SuggestedLocator,
+  fact: (v: string) => string,
+): Suggestion[] {
+  const out: Suggestion[] = [];
+  for (const v of values) {
+    const score = closeness(query, v);
+    if (score >= NEAR) out.push({ fact: fact(v), locator: make(v), score });
+  }
+  return out;
+}
+
+/**
+ * Rank what the page holds against what the author asked for. Pure: the
+ * caller collects `aria`/`dom` and verifies the winners.
+ */
+export function buildSuggestions(
+  target: HintTarget,
+  aria: AriaCandidate[],
+  dom: DomFacts,
+): Suggestion[] {
+  const q = target.query;
+  if (!q) return [];
+  const out: Suggestion[] = [];
+
+  if (target.kind === "role") {
+    const role = target.role ?? "";
+    for (const c of aria) {
+      const score = closeness(q, c.name);
+      if (score < NEAR) continue;
+      if (c.role === role) {
+        // Same role, near name: the everyday miss.
+        out.push({
+          fact: `${c.role} ${quoted(c.name)}`,
+          locator: { m: "getByRole", role: c.role, name: c.name },
+          score: score + 1,
+        });
+      } else {
+        // The name is right and the role is not — a `combobox` styled as a
+        // button, a `link` that looks like one. Worth saying out loud,
+        // because the author's own reading of the page is what is wrong.
+        out.push({
+          fact: `${c.role} ${quoted(c.name)} — this is a ${c.role}, not a ${role}`,
+          locator: { m: "getByRole", role: c.role, name: c.name },
+          score,
+        });
+      }
+    }
+    // An element whose visible text is what the author typed, but whose
+    // accessible name — the thing `getByRole` matches — is something else.
+    for (const m of dom.mismatches) {
+      const score = closeness(q, m.text);
+      if (score < NEAR) continue;
+      out.push({
+        fact: `<${m.tag}> shows ${quoted(m.text)} but its accessible name is ${quoted(m.name)} (from ${m.from})`,
+        locator: { m: "getByRole", role: role || "button", name: m.name },
+        score: score + 0.5,
+      });
+    }
+  }
+
+  if (target.kind === "text") {
+    out.push(
+      ...fromValues(q, dom.texts, (v) => ({ m: "getByText", text: v }), (v) => `text ${quoted(v)}`),
+    );
+    for (const c of aria) {
+      const score = closeness(q, c.name);
+      if (score >= NEAR) {
+        out.push({
+          fact: `${c.role} ${quoted(c.name)}`,
+          locator: { m: "getByRole", role: c.role, name: c.name },
+          score,
+        });
+      }
+    }
+  }
+
+  if (target.kind === "testId") {
+    out.push(
+      ...fromValues(
+        q,
+        dom.testIds,
+        (v) => ({ m: "getByTestId", id: v }),
+        (v) => `testid ${quoted(v)}`,
+      ),
+    );
+  }
+
+  if (target.kind === "label") {
+    out.push(
+      ...fromValues(q, dom.labels, (v) => ({ m: "getByLabel", text: v }), (v) => `label ${quoted(v)}`),
+    );
+  }
+
+  if (target.kind === "placeholder") {
+    out.push(
+      ...fromValues(
+        q,
+        dom.placeholders,
+        (v) => ({ m: "getByPlaceholder", text: v }),
+        (v) => `placeholder ${quoted(v)}`,
+      ),
+    );
+  }
+
+  if (target.kind === "title") {
+    out.push(
+      ...fromValues(q, dom.titles, (v) => ({ m: "getByTitle", text: v }), (v) => `title ${quoted(v)}`),
+    );
+  }
+
+  if (target.kind === "altText") {
+    out.push(
+      ...fromValues(q, dom.alts, (v) => ({ m: "getByAltText", text: v }), (v) => `alt ${quoted(v)}`),
+    );
+  }
+
+  return dedupe(out).sort(byScore).slice(0, MAX_SUGGESTIONS);
+}
+
+// ── Page-side collection ──────────────────────────────────────────────────
+
+/**
+ * Pull `- button "Save"` lines out of an ARIA snapshot.
+ *
+ * The snapshot is YAML, but only its leading token carries what we need, so
+ * this reads it line by line rather than pulling in a parser. A line we do not
+ * recognise is skipped — the worst case is one fewer suggestion.
+ */
+export function parseAriaSnapshot(yaml: string): AriaCandidate[] {
+  const out: AriaCandidate[] = [];
+  const seen = new Set<string>();
+  for (const raw of yaml.split("\n")) {
+    // `- role "name" [level=1]:` — the role is a bare word, the name a
+    // double-quoted string, and both the name and the trailing parts are
+    // optional. A quoted name may contain escaped quotes.
+    const m = /^\s*-\s+([a-zA-Z]+)(?:\s+"((?:[^"\\]|\\.)*)")?/.exec(raw);
+    if (!m) continue;
+    const role = m[1]!;
+    if (m[2] === undefined) continue; // No accessible name: nothing to match.
+    const name = m[2].replace(/\\(.)/g, "$1");
+    const k = `${role} "${name}"`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push({ role, name });
+    if (out.length >= 400) break;
+  }
+  return out;
+}
+
+/**
+ * Read the page facts the ARIA snapshot does not carry.
+ *
+ * Runs in the browser, so it must stay self-contained (no closure over
+ * anything here) and cheap: it walks a bounded number of elements and caps
+ * every list it fills.
+ */
+/* c8 ignore start — executes in the browser, not under bun test */
+function domFactsScript(): DomFacts {
+  const MAX_ELEMENTS = 4000;
+  const MAX_ITEMS = 200;
+  const norm = (s: string | null | undefined): string =>
+    (s ?? "").replace(/[\u200b\u00ad]/g, "").trim().replace(/\s+/g, " ").slice(0, 120);
+  const push = (arr: string[], v: string): void => {
+    if (v && arr.length < MAX_ITEMS && !arr.includes(v)) arr.push(v);
+  };
+  const out: DomFacts = {
+    texts: [],
+    testIds: [],
+    placeholders: [],
+    labels: [],
+    titles: [],
+    alts: [],
+    mismatches: [],
+  };
+  const visible = (el: Element): boolean => {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return false;
+    const st = getComputedStyle(el);
+    return st.visibility !== "hidden" && st.display !== "none";
+  };
+  const INTERACTIVE =
+    "a,button,summary,select,textarea,input,[role],[onclick],[tabindex]";
+  let n = 0;
+  for (const el of Array.from(document.querySelectorAll("*"))) {
+    if (++n > MAX_ELEMENTS) break;
+    const tag = el.tagName.toLowerCase();
+    if (tag === "script" || tag === "style" || tag === "head") continue;
+    push(out.testIds, norm(el.getAttribute("data-testid")));
+    push(out.placeholders, norm(el.getAttribute("placeholder")));
+    push(out.titles, norm(el.getAttribute("title")));
+    push(out.alts, norm(el.getAttribute("alt")));
+    const ariaLabel = norm(el.getAttribute("aria-label"));
+    push(out.labels, ariaLabel);
+    if (tag === "label") push(out.labels, norm((el as HTMLElement).innerText));
+    if (el.children.length === 0 && visible(el)) {
+      push(out.texts, norm((el as HTMLElement).innerText || el.textContent));
+    }
+    if (!el.matches(INTERACTIVE) || !visible(el)) continue;
+    const text = norm((el as HTMLElement).innerText || el.textContent);
+    let name = ariaLabel;
+    let from = "aria-label";
+    if (!name) {
+      const ids = (el.getAttribute("aria-labelledby") ?? "").split(/\s+/).filter(Boolean);
+      const parts: string[] = [];
+      for (const id of ids) {
+        const ref = document.getElementById(id);
+        if (ref) parts.push(norm((ref as HTMLElement).innerText || ref.textContent));
+      }
+      if (parts.length) {
+        name = norm(parts.join(" "));
+        from = "aria-labelledby";
+      }
+    }
+    if (!name && el.getAttribute("title")) {
+      name = norm(el.getAttribute("title"));
+      from = "title";
+    }
+    if (!name && tag === "input" && el.getAttribute("value")) {
+      name = norm(el.getAttribute("value"));
+      from = "value";
+    }
+    if (name && text && name !== text && out.mismatches.length < 50) {
+      out.mismatches.push({ tag, text, name, from });
+    }
+  }
+  return out;
+}
+/* c8 ignore stop */
+
+/** Build the playwright locator a suggestion proposes, for verification. */
+function resolve(page: Page, loc: SuggestedLocator): PWLocator {
+  switch (loc.m) {
+    case "getByRole":
+      return page.getByRole(loc.role as Parameters<Page["getByRole"]>[0], {
+        name: loc.name,
+        exact: true,
+      });
+    case "getByTestId":
+      return page.getByTestId(loc.id);
+    case "getByText":
+      return page.getByText(loc.text, { exact: true });
+    case "getByLabel":
+      return page.getByLabel(loc.text, { exact: true });
+    case "getByPlaceholder":
+      return page.getByPlaceholder(loc.text, { exact: true });
+    case "getByAltText":
+      return page.getByAltText(loc.text, { exact: true });
+    case "getByTitle":
+      return page.getByTitle(loc.text, { exact: true });
+  }
+}
+
+/** How long the whole diagnostic may take. It runs after a failure that has
+ *  already waited seconds, so a short budget costs nothing and a hung page
+ *  cannot make a failing test hang. */
+const HINT_BUDGET_MS = 2_000;
+
+async function withBudget<T>(work: Promise<T>, fallback: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<T>((resolve) => {
+        timer = setTimeout(() => resolve(fallback), HINT_BUDGET_MS);
+      }),
+    ]);
+  } catch {
+    return fallback;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * The lines to append to a "no element matches" failure — at most
+ * {@link MAX_SUGGESTIONS}, each verified against the live page, and empty
+ * whenever the page holds nothing close.
+ */
+export async function nearMissHints(page: Page, target: HintTarget): Promise<string[]> {
+  if (!target.query) return [];
+  const collected = await withBudget(
+    (async () => {
+      const [snapshot, dom] = await Promise.all([
+        page.ariaSnapshot().catch(() => ""),
+        page.evaluate(domFactsScript).catch(() => EMPTY_DOM_FACTS),
+      ]);
+      return { aria: parseAriaSnapshot(snapshot), dom };
+    })(),
+    { aria: [] as AriaCandidate[], dom: EMPTY_DOM_FACTS },
+  );
+
+  const suggestions = buildSuggestions(target, collected.aria, collected.dom);
+  if (!suggestions.length) return [];
+
+  // Verify before printing. A suggestion nobody can use is worse than none:
+  // it sends the author to try a locator we invented.
+  const lines = await withBudget(
+    Promise.all(
+      suggestions.map(async (s) => {
+        const matches = await resolve(page, s.locator)
+          .count()
+          .catch(() => 0);
+        return matches > 0 ? suggestionLine(s, matches) : undefined;
+      }),
+    ),
+    [],
+  );
+  return lines.filter((l): l is string => l !== undefined);
+}
+
+/** The block appended under a failure sentence, or `""` when there is
+ *  nothing to add. */
+export function formatHints(lines: string[]): string {
+  if (!lines.length) return "";
+  return `\nClose matches on the page:\n${lines.join("\n")}`;
+}