@specific.dev/spectest 0.54.1 → 0.55.0

package/dist/index.js

@@ -34,6 +34,7 @@ export { SQL } from "./sql.js";
 export { RedisClient } from "./redis.js";
 export { S3Client } from "./s3.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
+import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
@@ -549,7 +550,8 @@ function buildLocatorMatchers(loc, negated, message) {
     // value for the timeline.
     const run = async (matcher, timeout, check, describe, expected) => {
         const started = Date.now();
-        const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+        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
@@ -560,20 +562,59 @@ function buildLocatorMatchers(loc, negated, message) {
         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.
+        const elementFailure = async (err) => {
+            if (err !== undefined)
+                return locatorFailureMessage(probe.label, err);
+            if (expectsGone || matcher === "toHaveCount")
+                return undefined;
+            try {
+                if ((await probe.count()) === 0) {
+                    return `No element matches ${probe.label} (waited ${formatWaited(budget)})`;
+                }
+            }
+            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 5000ms 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;
-                actual = `<error: ${err?.message ?? String(err)}>`;
+                // 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) {
@@ -590,7 +631,11 @@ function buildLocatorMatchers(loc, negated, message) {
                 return;
             }
             if (Date.now() >= deadline) {
-                const msg = describe(actual);
+                // The deadline, not the stopwatch: every one of these polled until it
+                // ran out, and "(waited 5s)" is both what the author set and the same
+                // number twice in a row — a measured 4_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,

package/dist/locator-errors.d.ts

@@ -0,0 +1,21 @@
+/** A wait's duration, in the units a reader thinks in: "800ms", "5s", "1.5s". */
+export declare function formatWaited(ms: number): string;
+/**
+ * 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).
+ *
+ * `label` is the locator's human chain label, the same string the timeline
+ * step shows.
+ */
+export declare function locatorFailureMessage(label: string, err: unknown): string | undefined;
+/**
+ * Replace a locator timeout'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
+ * author's own call, which a fresh Error would lose. The stack string embeds
+ * the old message (it is built at construction), so that copy is rewritten
+ * too — otherwise the CLI's failure block would print the friendly message and
+ * then the timeout wall right under it.
+ */
+export declare function rewriteLocatorError(err: unknown, label: string): unknown;

package/dist/locator-errors.js

@@ -0,0 +1,142 @@
+// Readable failures for locator steps.
+//
+// Playwright reports every unmet actionability wait the same way: a
+// `TimeoutError` whose message is "Timeout 5000ms exceeded." with the real
+// story — did the element exist at all? was it disabled? did something cover
+// it? — buried in a call log below it. A test that clicks a button that is not
+// on the page therefore fails with a sentence about OUR deadline, which reads
+// 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.
+//
+// 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
+// a serialize/deserialize round trip.
+/** A wait's duration, in the units a reader thinks in: "800ms", "5s", "1.5s". */
+export function formatWaited(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return "0ms";
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    // Rounded off the millisecond count, not through toFixed — 1450ms is
+    // "1.5s", and binary floating point renders 1.45 as 1.4.
+    return `${Math.round(ms / 100) / 10}s`;
+}
+/** Recognise playwright's actionability timeout and pull it apart. Returns
+ *  `undefined` for every other error. */
+function parseTimeout(err) {
+    const e = err;
+    if (!e || e.name !== "TimeoutError" || typeof e.message !== "string")
+        return undefined;
+    const m = /Timeout (\d+)ms exceeded/.exec(e.message);
+    if (!m)
+        return undefined;
+    const raw = Array.isArray(e.log)
+        ? e.log.filter((l) => typeof l === "string")
+        : logFromMessage(e.message);
+    return { timeoutMs: Number(m[1]), log: raw.map(cleanLogLine).filter(Boolean) };
+}
+function logFromMessage(message) {
+    const at = message.indexOf("Call log:");
+    if (at === -1)
+        return [];
+    return message.slice(at + "Call log:".length).split("\n");
+}
+/** Strip a line's leading bullet and repeat count ("2 × waiting for …"). */
+function cleanLogLine(line) {
+    return line.trim().replace(/^-\s*/, "").replace(/^\d+\s*×\s*/, "");
+}
+/** Did the locator ever match anything? Playwright logs "locator resolved to
+ *  <html>" the moment it does, and nothing of the sort when it never did. */
+function resolved(log) {
+    return log.some((l) => l.startsWith("locator resolved to"));
+}
+/** The state a `waitFor`-style wait was after, from its opening log line. */
+function waitedForState(log) {
+    for (const line of log) {
+        const m = /^waiting for .* to be (attached|detached|visible|hidden)$/.exec(line);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/** Why an element that DID match still could not be acted on. Read from the
+ *  last attempt, since that is the state the deadline caught it in. */
+function actionabilityReason(log) {
+    for (let i = log.length - 1; i >= 0; i--) {
+        const line = log[i];
+        // "element is not visible" / "not enabled" / "not stable" / "not editable"
+        const missing = /^element is not (.+)$/.exec(line);
+        if (missing)
+            return `is not ${missing[1]}`;
+        // "<div id="overlay"></div> intercepts pointer events"
+        const covered = /^(<.+>) intercepts pointer events$/.exec(line);
+        if (covered)
+            return `is covered by ${covered[1]}`;
+    }
+    return undefined;
+}
+/**
+ * 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).
+ *
+ * `label` is the locator's human chain label, the same string the timeline
+ * step shows.
+ */
+export function locatorFailureMessage(label, err) {
+    const detail = parseTimeout(err);
+    if (!detail)
+        return undefined;
+    const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
+    if (!resolved(detail.log))
+        return `No element matches ${label} ${waited}`;
+    // It matched, so the failure is about the element's state.
+    switch (waitedForState(detail.log)) {
+        case "hidden":
+            return `Element ${label} is still visible ${waited}`;
+        case "detached":
+            return `Element ${label} is still attached to the page ${waited}`;
+        case "visible":
+            return `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}`;
+}
+/**
+ * Replace a locator timeout'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
+ * author's own call, which a fresh Error would lose. The stack string embeds
+ * the old message (it is built at construction), so that copy is rewritten
+ * too — otherwise the CLI's failure block would print the friendly message and
+ * then the timeout wall right under it.
+ */
+export function rewriteLocatorError(err, label) {
+    const message = locatorFailureMessage(label, err);
+    if (message === undefined)
+        return err;
+    const e = err;
+    const old = e.message;
+    if (typeof e.stack === "string") {
+        for (const [header, replacement] of [
+            [`${e.name}: ${old}`, `${e.name}: ${message}`],
+            [old, message],
+        ]) {
+            if (e.stack.startsWith(header)) {
+                e.stack = replacement + e.stack.slice(header.length);
+                break;
+            }
+        }
+    }
+    e.message = message;
+    return e;
+}

package/dist/locator.js

@@ -22,6 +22,7 @@
 // author-facing call is exactly one recorded browser event (with its rrweb
 // drain), whatever playwright work it composes underneath.
 import { Buffer } from "node:buffer";
+import { rewriteLocatorError } from "./locator-errors.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 /** Default deadline for a locator action/read's target to become actionable.
@@ -350,20 +351,31 @@ function lowerInputFiles(files) {
 export function makeLocator(backend, strategy, chain) {
     const label = chainLabel(chain);
     const extend = (step) => makeLocator(backend, strategy, { steps: [...chain.steps, step] });
+    // Every terminal op runs through this: playwright's actionability timeouts
+    // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
+    // log, so they are rewritten into a sentence naming the element and its
+    // state (see locator-errors.ts). Applied INSIDE `pageOp`, so the recorded
+    // step carries the readable message too — not just the thrown error.
+    const readable = async (fn) => {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            throw rewriteLocatorError(err, label);
+        }
+    };
     // One recorded event, result NOT wrapped (void/action).
-    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain), page));
+    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(() => fn(lower(page, chain), page)));
     // One recorded event whose fields the action itself finishes filling in:
     // `rec` is the very object the recorder spreads once `fn` resolves (the
     // same mutate-in-flight seam `screenshot`'s artifact id rides), so the
     // click family can stamp the point it acted on. See stampActionPoint.
     const actAt = (action, fn) => {
         const rec = { selector: label };
-        return backend.pageOp(action, rec, (page) => fn(lower(page, chain), rec));
+        return backend.pageOp(action, rec, (page) => readable(() => fn(lower(page, chain), rec)));
     };
     // One recorded event, result provenance-wrapped for expect().
-    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain)), {
-        wrap: true,
-    });
+    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(() => fn(lower(page, chain))), { wrap: true });
     // Silent, non-recorded reads for expect(locator) matchers to poll.
     const probe = {
         label,
@@ -459,7 +471,7 @@ export function makeLocator(backend, strategy, chain) {
                 out.push(extend({ m: "nth", args: [i] }));
             return out;
         },
-        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => lower(page, chain).evaluate(fn, arg), { wrap: true }),
+        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => readable(() => lower(page, chain).evaluate(fn, arg)), { wrap: true }),
         waitFor: (opts) => act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
     };
     // Attach the silent-read probe under its symbol (kept off the typed literal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -87,6 +87,7 @@ import {
   getBrowserProbe,
   DEFAULT_ACTION_TIMEOUT_MS,
 } from "./locator.js";
+import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
 
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
@@ -2467,7 +2468,8 @@ function buildLocatorMatchers(
     expected?: unknown,
   ): Promise<void> => {
     const started = Date.now();
-    const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+    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
@@ -2479,19 +2481,55 @@ function buildLocatorMatchers(
       (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.
+    const elementFailure = async (err: unknown): Promise<string | undefined> => {
+      if (err !== undefined) return locatorFailureMessage(probe.label, err);
+      if (expectsGone || matcher === "toHaveCount") return undefined;
+      try {
+        if ((await probe.count()) === 0) {
+          return `No element matches ${probe.label} (waited ${formatWaited(budget)})`;
+        }
+      } 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 5000ms 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;
-        actual = `<error: ${(err as Error)?.message ?? String(err)}>`;
+        // 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) {
@@ -2508,7 +2546,11 @@ function buildLocatorMatchers(
         return;
       }
       if (Date.now() >= deadline) {
-        const msg = describe(actual);
+        // The deadline, not the stopwatch: every one of these polled until it
+        // ran out, and "(waited 5s)" is both what the author set and the same
+        // number twice in a row — a measured 4_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,

package/src/locator-errors.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+
+import { formatWaited, locatorFailureMessage, rewriteLocatorError } 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
+ *  log as an array, and a stack whose first lines ARE the message. Captured
+ *  from a real run against headless Chromium. */
+function timeoutError(message: string, log: string[]): Error {
+  const full = `${message}\nCall log:\n${log.join("\n")}\n`;
+  const err = new Error(full) as Error & { log: string[] };
+  err.name = "TimeoutError";
+  err.log = log;
+  err.stack = `${full}\n    at /project/spectest/tests/todo.ts:12:34`;
+  return err;
+}
+
+describe("locatorFailureMessage", () => {
+  test("names the element that was never found", () => {
+    const err = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for getByTestId('add')",
+    ]);
+    expect(locatorFailureMessage('testid "add"', err)).toBe(
+      'No element matches testid "add" (waited 5s)',
+    );
+  });
+
+  test("reports the state of an element that was found", () => {
+    const err = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for locator('#dis')",
+      "    - locator resolved to <button id=\"dis\" disabled>Nope</button>",
+      "  - attempting click action",
+      "    2 × waiting for element to be visible, enabled and stable",
+      "      - element is not enabled",
+      "    - retrying click action",
+      "      - waiting 100ms",
+    ]);
+    expect(locatorFailureMessage('css "#dis"', err)).toBe(
+      'Element css "#dis" is not enabled (waited 5s)',
+    );
+  });
+
+  test("names what covered the element", () => {
+    const err = timeoutError("click: Timeout 1000ms exceeded.", [
+      "  - waiting for locator('#ok')",
+      "    - locator resolved to <button id=\"ok\">OK</button>",
+      "  - attempting click action",
+      "      - <div id=\"cover\"></div> intercepts pointer events",
+    ]);
+    expect(locatorFailureMessage('css "#ok"', err)).toBe(
+      'Element css "#ok" is covered by <div id="cover"></div> (waited 1s)',
+    );
+  });
+
+  test("a wait for the element to go away says it is still there", () => {
+    const err = timeoutError("waitFor: Timeout 2500ms exceeded.", [
+      "  - waiting for locator('#ok') to be hidden",
+      "    11 × locator resolved to visible <button id=\"ok\">OK</button>",
+    ]);
+    expect(locatorFailureMessage('css "#ok"', err)).toBe(
+      'Element css "#ok" is still visible (waited 2.5s)',
+    );
+  });
+
+  test("falls back when the element matched for a reason we cannot read", () => {
+    const err = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for locator('#ok')",
+      "    - locator resolved to <button id=\"ok\">OK</button>",
+      "  - something new playwright started logging",
+    ]);
+    expect(locatorFailureMessage('css "#ok"', err)).toBe(
+      'Element css "#ok" never became ready for this action (waited 5s)',
+    );
+  });
+
+  test("reads the call log out of the message when the log array is gone", () => {
+    const err = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for getByTestId('add')",
+    ]);
+    delete (err as { log?: unknown }).log;
+    expect(locatorFailureMessage('testid "add"', err)).toBe(
+      'No element matches testid "add" (waited 5s)',
+    );
+  });
+
+  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();
+    expect(locatorFailureMessage('css "p"', new Error("page closed"))).toBeUndefined();
+    expect(locatorFailureMessage('css "p"', "not an error at all")).toBeUndefined();
+  });
+});
+
+describe("rewriteLocatorError", () => {
+  test("rewrites the message AND the copy embedded in the stack", () => {
+    const err = timeoutError("click: Timeout 5000ms exceeded.", [
+      "  - waiting for getByTestId('add')",
+    ]);
+    const out = rewriteLocatorError(err, 'testid "add"') 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)');
+    expect(out.stack).toStartWith('No element matches testid "add" (waited 5s)');
+    expect(out.stack).not.toContain("Timeout 5000ms exceeded");
+    expect(out.stack).toContain("todo.ts:12:34");
+  });
+
+  test("hands back anything it does not understand untouched", () => {
+    const err = new Error("page closed");
+    expect(rewriteLocatorError(err, 'css "p"')).toBe(err);
+    expect(err.message).toBe("page closed");
+  });
+});
+
+describe("formatWaited", () => {
+  test("reads in the units a reader thinks in", () => {
+    expect(formatWaited(250)).toBe("250ms");
+    expect(formatWaited(5000)).toBe("5s");
+    expect(formatWaited(5040)).toBe("5s");
+    expect(formatWaited(1450)).toBe("1.5s");
+    expect(formatWaited(30_000)).toBe("30s");
+  });
+});

package/src/locator-errors.ts

@@ -0,0 +1,153 @@
+// Readable failures for locator steps.
+//
+// Playwright reports every unmet actionability wait the same way: a
+// `TimeoutError` whose message is "Timeout 5000ms exceeded." with the real
+// story — did the element exist at all? was it disabled? did something cover
+// it? — buried in a call log below it. A test that clicks a button that is not
+// on the page therefore fails with a sentence about OUR deadline, which reads
+// 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.
+//
+// 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
+// a serialize/deserialize round trip.
+
+/** A wait's duration, in the units a reader thinks in: "800ms", "5s", "1.5s". */
+export function formatWaited(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "0ms";
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  // Rounded off the millisecond count, not through toFixed — 1450ms is
+  // "1.5s", and binary floating point renders 1.45 as 1.4.
+  return `${Math.round(ms / 100) / 10}s`;
+}
+
+/** The states `waitFor` (and the mobile tap's own pre-wait) can ask for. Read
+ *  off the call log rather than threaded through the callers, so a wait nested
+ *  inside some other action is described just as well. */
+type WaitState = "attached" | "detached" | "visible" | "hidden";
+
+interface TimeoutDetail {
+  /** The deadline playwright reported — the exact number the author set. */
+  timeoutMs: number;
+  /** Call-log lines, leading "- " and "N × " repeat counts stripped. */
+  log: string[];
+}
+
+/** Recognise playwright's actionability timeout and pull it apart. Returns
+ *  `undefined` for every other error. */
+function parseTimeout(err: unknown): TimeoutDetail | undefined {
+  const e = err as { name?: string; message?: unknown; log?: unknown } | null;
+  if (!e || e.name !== "TimeoutError" || typeof e.message !== "string") return undefined;
+  const m = /Timeout (\d+)ms exceeded/.exec(e.message);
+  if (!m) return undefined;
+  const raw = Array.isArray(e.log)
+    ? (e.log as unknown[]).filter((l): l is string => typeof l === "string")
+    : logFromMessage(e.message);
+  return { timeoutMs: Number(m[1]), log: raw.map(cleanLogLine).filter(Boolean) };
+}
+
+function logFromMessage(message: string): string[] {
+  const at = message.indexOf("Call log:");
+  if (at === -1) return [];
+  return message.slice(at + "Call log:".length).split("\n");
+}
+
+/** Strip a line's leading bullet and repeat count ("2 × waiting for …"). */
+function cleanLogLine(line: string): string {
+  return line.trim().replace(/^-\s*/, "").replace(/^\d+\s*×\s*/, "");
+}
+
+/** Did the locator ever match anything? Playwright logs "locator resolved to
+ *  <html>" the moment it does, and nothing of the sort when it never did. */
+function resolved(log: string[]): boolean {
+  return log.some((l) => l.startsWith("locator resolved to"));
+}
+
+/** The state a `waitFor`-style wait was after, from its opening log line. */
+function waitedForState(log: string[]): WaitState | undefined {
+  for (const line of log) {
+    const m = /^waiting for .* to be (attached|detached|visible|hidden)$/.exec(line);
+    if (m) return m[1] as WaitState;
+  }
+  return undefined;
+}
+
+/** Why an element that DID match still could not be acted on. Read from the
+ *  last attempt, since that is the state the deadline caught it in. */
+function actionabilityReason(log: string[]): string | undefined {
+  for (let i = log.length - 1; i >= 0; i--) {
+    const line = log[i]!;
+    // "element is not visible" / "not enabled" / "not stable" / "not editable"
+    const missing = /^element is not (.+)$/.exec(line);
+    if (missing) return `is not ${missing[1]}`;
+    // "<div id="overlay"></div> intercepts pointer events"
+    const covered = /^(<.+>) intercepts pointer events$/.exec(line);
+    if (covered) return `is covered by ${covered[1]}`;
+  }
+  return undefined;
+}
+
+/**
+ * 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).
+ *
+ * `label` is the locator's human chain label, the same string the timeline
+ * step shows.
+ */
+export function locatorFailureMessage(label: string, err: unknown): string | undefined {
+  const detail = parseTimeout(err);
+  if (!detail) return undefined;
+  const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
+  if (!resolved(detail.log)) return `No element matches ${label} ${waited}`;
+
+  // It matched, so the failure is about the element's state.
+  switch (waitedForState(detail.log)) {
+    case "hidden":
+      return `Element ${label} is still visible ${waited}`;
+    case "detached":
+      return `Element ${label} is still attached to the page ${waited}`;
+    case "visible":
+      return `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}`;
+}
+
+/**
+ * Replace a locator timeout'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
+ * author's own call, which a fresh Error would lose. The stack string embeds
+ * the old message (it is built at construction), so that copy is rewritten
+ * 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;
+  const old = e.message;
+  if (typeof e.stack === "string") {
+    for (const [header, replacement] of [
+      [`${e.name}: ${old}`, `${e.name}: ${message}`],
+      [old, message],
+    ] as const) {
+      if (e.stack.startsWith(header)) {
+        e.stack = replacement + e.stack.slice(header.length);
+        break;
+      }
+    }
+  }
+  e.message = message;
+  return e;
+}

package/src/locator.ts

@@ -26,6 +26,7 @@ import { Buffer } from "node:buffer";
 import type { Page, Locator as PWLocator } from "playwright-core";
 import type { RecordableFields } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
+import { rewriteLocatorError } from "./locator-errors.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 
@@ -701,6 +702,19 @@ export function makeLocator(
   const extend = (step: Step): Locator =>
     makeLocator(backend, strategy, { steps: [...chain.steps, step] });
 
+  // Every terminal op runs through this: playwright's actionability timeouts
+  // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
+  // log, so they are rewritten into a sentence naming the element and its
+  // state (see locator-errors.ts). Applied INSIDE `pageOp`, so the recorded
+  // step carries the readable message too — not just the thrown error.
+  const readable = async <T>(fn: () => Promise<T>): Promise<T> => {
+    try {
+      return await fn();
+    } catch (err) {
+      throw rewriteLocatorError(err, label);
+    }
+  };
+
   // One recorded event, result NOT wrapped (void/action).
   const act = <T>(
     action: string,
@@ -708,7 +722,7 @@ export function makeLocator(
     fn: (loc: PWLocator, page: Page) => Promise<T>,
   ): Promise<T> =>
     backend.pageOp(action, { selector: label, ...fields }, (page) =>
-      fn(lower(page, chain), page),
+      readable(() => fn(lower(page, chain), page)),
     );
 
   // One recorded event whose fields the action itself finishes filling in:
@@ -720,7 +734,9 @@ export function makeLocator(
     fn: (loc: PWLocator, rec: Partial<RecordableFields>) => Promise<T>,
   ): Promise<T> => {
     const rec: Partial<RecordableFields> = { selector: label };
-    return backend.pageOp(action, rec, (page) => fn(lower(page, chain), rec));
+    return backend.pageOp(action, rec, (page) =>
+      readable(() => fn(lower(page, chain), rec)),
+    );
   };
 
   // One recorded event, result provenance-wrapped for expect().
@@ -729,9 +745,12 @@ export function makeLocator(
     fn: (loc: PWLocator) => Promise<T>,
     fields: Partial<RecordableFields> = {},
   ): Promise<Wrapped<T>> =>
-    backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain)), {
-      wrap: true,
-    }) as Promise<Wrapped<T>>;
+    backend.pageOp(
+      action,
+      { selector: label, ...fields },
+      (page) => readable(() => fn(lower(page, chain))),
+      { wrap: true },
+    ) as Promise<Wrapped<T>>;
 
   // Silent, non-recorded reads for expect(locator) matchers to poll.
   const probe: LocatorProbe = {
@@ -848,7 +867,7 @@ export function makeLocator(
       backend.pageOp(
         "evaluate",
         { selector: label, description },
-        (page) => lower(page, chain).evaluate(fn as never, arg),
+        (page) => readable(() => lower(page, chain).evaluate(fn as never, arg)),
         { wrap: true },
       ) as Promise<Wrapped<never>>,