@specific.dev/spectest 0.54.1 → 0.56.0

package/dist/recorder.d.ts

@@ -599,6 +599,7 @@ export type StepBlock = {
         value?: string;
         error?: boolean;
     }[];
+    label?: string;
 } | {
     type: "table";
     columns: string[];
@@ -611,6 +612,10 @@ export type StepBlock = {
     type: "chat";
     messages: ChatBlockMessage[];
     label?: string;
+} | {
+    type: "details";
+    summary: string;
+    blocks: StepBlock[];
 };
 /** One message of a `chat` block. */
 export interface ChatBlockMessage {

package/package.json

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

package/src/daemon.ts

@@ -118,6 +118,10 @@ import {
 } from "./harness/methods.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 import { openTerminal } from "./terminal.js";
+// `ctx.mcp(url)`. One client per call, no registry: an authenticated
+// client is passed to descendants as a test's return value.
+import { openMcp } from "./mcp.js";
+import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
   pauseRecording,
@@ -4178,6 +4182,10 @@ function isTransportError(err: unknown): boolean {
  */
 function installFetchWrapper(): () => void {
   const original = globalThis.fetch;
+  // SDK internals (the MCP client, its OAuth flow) must not see the
+  // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
+  // body to the end, which never finishes for an SSE stream.
+  setRawFetch(original);
   const wrappedFn = async (
     input: Parameters<typeof fetch>[0],
     init?: Parameters<typeof fetch>[1],
@@ -4934,6 +4942,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     openTerminal: recordedOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    mcp: openMcp,
     testName: testCase.name,
     parent,
   };
@@ -5455,6 +5464,7 @@ async function evalCode(
     openTerminal: evalOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    mcp: openMcp,
     testName: "eval",
     parent: undefined,
   };

package/src/harness/raw-fetch.ts

@@ -0,0 +1,36 @@
+// The real `fetch`, for SDK internals that must not go through the test
+// recorder's wrapper.
+//
+// While a test (or an eval) runs, the daemon replaces `globalThis.fetch`
+// with an instrumented one: it records an `http` event, and it hands back
+// a WRAPPED response whose `ok` / `status` are provenance handles rather
+// than a boolean and a number. That is exactly right for a test's own
+// calls, and exactly wrong inside the SDK, in two ways:
+//
+//   1. `if (!res.ok)` is always false against a handle, because a handle
+//      is an object. An SDK client that checks it would read a `401` as a
+//      success. (`pauseRecording()` does not help: it stops the event, not
+//      the wrapper.)
+//   2. The wrapper clones the response and reads the clone to the end so
+//      it can record the body. For a streaming reply — Server-Sent Events
+//      — that does not finish until the stream closes, so the caller is
+//      handed its response only after the stream it was waiting to read
+//      has already ended. A long-lived stream deadlocks.
+//
+// So SDK-internal HTTP goes through `rawFetch`. The daemon publishes the
+// original here when it installs its wrapper.
+
+let original: typeof fetch | undefined;
+
+/** Called by the daemon with the real `fetch`, before it installs its
+ *  instrumented one. */
+export function setRawFetch(fn: typeof fetch): void {
+  original = fn;
+}
+
+/** `fetch`, never the instrumented wrapper. Falls back to the global for
+ *  a context where nothing was ever installed (unit tests, a plain
+ *  script). */
+export function rawFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  return (original ?? globalThis.fetch)(input as RequestInfo, init);
+}

package/src/ids.ts

@@ -44,7 +44,18 @@ export function generateId(prefix: string): string {
   return `${prefix}_0${base32Crockford(digest.subarray(0, 16)).slice(0, RANDOM_LEN)}`;
 }
 
-/** Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool). */
+/**
+ * Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool).
+ *
+ * Exported because every in-VM secret with a uniqueness requirement has
+ * the same problem as an id: Bun's pool is frozen into the snapshot, so
+ * sibling forks draw identical bytes. An OAuth PKCE verifier and `state`
+ * (`mcp-auth.ts`) must come from here, not from `crypto.getRandomValues`.
+ */
+export function secureRandomBytes(n: number): Uint8Array {
+  return urandom(n);
+}
+
 function urandom(n: number): Uint8Array {
   const buf = new Uint8Array(n);
   try {

package/src/index.ts

@@ -66,6 +66,34 @@ export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./br
 
 import type { Browser, BrowserOptions } from "./browser.js";
 
+// The MCP client (`ctx.mcp`). Drives a Model Context Protocol server the
+// way a real AI client would, with the OAuth flow a test runs through its
+// own browser. See `mcp.ts`.
+export {
+  McpHttpError,
+  McpRpcError,
+  McpAuthDeniedError,
+  type Mcp,
+  type McpOptions,
+  type McpAuthorization,
+  type McpChallenge,
+  type McpIdentity,
+  type McpToolResult,
+  type McpToolInfo,
+  type McpResourceInfo,
+  type McpResourceContents,
+  type McpPromptInfo,
+  type McpPromptResult,
+  type McpContent,
+  type McpNotification,
+  type McpSamplingRequest,
+  type McpSamplingResult,
+  type AuthorizeOptions,
+  type AuthorizationServerInfo,
+} from "./mcp.js";
+
+import type { Mcp, McpOptions } from "./mcp.js";
+
 // Playwright-native locators — the select-then-act surface shared by
 // `ctx.browser()` and `ctx.mobile()`. `Locator` mirrors playwright-core's
 // Locator (getBy*/filter/first/nth/click/fill/textContent/…, STRICT mode).
@@ -87,6 +115,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";
@@ -1497,6 +1526,47 @@ export interface TestContext<
    * natural way to assert on the exit code.
    */
   openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
+  /**
+   * Connect to a Model Context Protocol server over HTTP, as an AI client
+   * would. Every tool call, resource read and prompt renders as its own
+   * step in the timeline, with the arguments and the result.
+   *
+   * ```ts
+   * const mcp = await ctx.mcp("https://api.test/mcp");
+   * const res = await mcp.call("create_invoice", { customer: "Acme" });
+   * expect(res.json<{ id: string }>().id).toMatch(/^inv_/);
+   * ```
+   *
+   * **Each call returns a NEW client.** There is no per-name registry like
+   * `ctx.browser("alice")` has, and no default session. A client that has
+   * authenticated is handed to the tests that need it, as this test's
+   * return value — `ctx.parent` crosses the fork in daemon memory, live
+   * connections included:
+   *
+   * ```ts
+   * export const signedIn = env.test("sign in", async (ctx) => {
+   *   const mcp = await ctx.mcp(URL);
+   *   const auth = await mcp.authorize();
+   *   const page = await ctx.browser();
+   *   await page.goto(auth.url);
+   *   await page.getByRole("button", { name: "Allow" }).click();
+   *   await auth.complete();
+   *   return mcp;
+   * });
+   *
+   * env.test("call a tool", { dependsOn: signedIn }, async (ctx) => {
+   *   await ctx.parent.call("create_invoice", { amount: 250 });
+   * });
+   * ```
+   *
+   * Two identities are two calls to `ctx.mcp` — nothing to name.
+   *
+   * A server that needs authorization answers `401`, which is reported and
+   * not hidden: `ctx.mcp(url)` returns an unauthenticated client carrying
+   * the challenge, and a call on it fails with the server's own rejection.
+   * That is what makes "this tool is protected" a test.
+   */
+  mcp(url: string, opts?: McpOptions): Promise<Mcp>;
   /**
    * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
    *
@@ -2467,7 +2537,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 +2550,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 +2615,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>>,