@specific.dev/spectest 0.118.0 → 0.119.0

package/src/locator.ts

@@ -29,7 +29,7 @@ import type { Wrapped } from "./inspect.js";
 import { rewriteLocatorErrorWithHints } from "./locator-errors.js";
 import { formatHints, nearMissHints, type HintTarget } from "./locator-hints.js";
 import { resolveExistingProjectPath } from "./project-files.js";
-import { truncateUtf8 } from "./recorder.js";
+import { truncateUtf8, type RecordedBrowserLocatorPart } from "./recorder.js";
 
 /** Default deadline for a locator action/read's target to become actionable.
  *  Playwright's own default is 30s — far too slow-failing for tests. This was
@@ -158,6 +158,22 @@ function chainOf(loc: Locator): Chain {
   return (loc as InternalLocator)[CHAIN];
 }
 
+/** Keep locator structure (including regex flags and nested filters) in the
+ * event. The old selector field remains for classic/CLI compatibility. */
+function recordedChain(chain: Chain): RecordedBrowserLocatorPart[] {
+  const argument = (v: unknown): unknown => {
+    if (v instanceof RegExp) return { regex: v.source, flags: v.flags };
+    if (isLocator(v)) return recordedChain(chainOf(v));
+    if (Array.isArray(v)) return v.map(argument);
+    if (v && typeof v === "object") {
+      return Object.fromEntries(Object.entries(v).filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, argument(value)]));
+    }
+    return v;
+  };
+  return chain.steps.map(({ m, args }) => ({ method: m, args: args.map(argument) }));
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Lowering: chain → live playwright Locator
 // ────────────────────────────────────────────────────────────────────────
@@ -553,8 +569,8 @@ async function stampActionPoint(
   }
 }
 
-/** Stamp the rrweb node id of the element a settled `expect(locator)` step is
- *  about, so the dashboard can bring it into the replay's view.
+/** Stamp the rrweb node id of a locator operation's target, so the dashboard
+ *  can highlight it and bring it into the replay's view.
  *
  *  Playwright's idea of "visible" is a non-empty box that isn't hidden — it
  *  says nothing about the viewport, so an element below the fold passes
@@ -575,9 +591,11 @@ async function stampRevealTarget(
   rec: Partial<RecordableFields>,
 ): Promise<void> {
   try {
-    const id = await loc.evaluate(
-      (el) => {
-        if (window.top !== window) return 0;
+    const id = await loc.evaluateAll(
+      (elements) => {
+        // Never wait for a missing element or pick an arbitrary list match.
+        if (elements.length !== 1 || window.top !== window) return 0;
+        const el = elements[0]!;
         // The bootstrap stashes rrweb's `record` here; `mirror` is its
         // node ↔ id map, shared by every snapshot it takes (see browser.ts).
         const w = window as unknown as {
@@ -588,8 +606,6 @@ async function stampRevealTarget(
         const id = getId.call(w.__spectestRec!.mirror, el);
         return typeof id === "number" && id > 0 ? id : 0;
       },
-      undefined,
-      { timeout: POINT_PROBE_MS },
     );
     if (id) rec.targetNodeId = id;
   } catch {
@@ -753,6 +769,7 @@ export function makeLocator(
   chain: Chain,
 ): Locator {
   const label = chainLabel(chain);
+  const target = recordedChain(chain);
   const extend = (step: Step): Locator =>
     makeLocator(backend, strategy, { steps: [...chain.steps, step] });
 
@@ -779,15 +796,38 @@ export function makeLocator(
     }
   };
 
+  // Capture identity before mutations (e.g. a press that removes its target).
+  // If an action auto-waits for an element that is not present yet, capture it
+  // afterwards instead. Both probes are immediate and best-effort; annotation
+  // must not change action errors, return values or locator strictness.
+  const withTarget = async <T>(
+    page: Page,
+    action: string,
+    rec: Partial<RecordableFields>,
+    fn: (loc: PWLocator, page: Page) => Promise<T>,
+  ): Promise<T> => {
+    const lowered = lower(page, chain);
+    const singleTarget = !["count", "all", "allTextContents", "allInnerTexts"].includes(action)
+      && !(action === "waitFor" && (rec.state === "hidden" || rec.state === "detached"));
+    if (singleTarget) await stampRevealTarget(lowered, rec);
+    try {
+      return await fn(lowered, page);
+    } finally {
+      if (singleTarget && !rec.targetNodeId) await stampRevealTarget(lowered, rec);
+    }
+  };
+
   // One recorded event, result NOT wrapped (void/action).
   const act = <T>(
     action: string,
     fields: Partial<RecordableFields>,
     fn: (loc: PWLocator, page: Page) => Promise<T>,
-  ): Promise<T> =>
-    backend.pageOp(action, { selector: label, ...fields }, (page) =>
-      readable(page, () => fn(lower(page, chain), page)),
+  ): Promise<T> => {
+    const rec: Partial<RecordableFields> = { selector: label, target, ...fields };
+    return backend.pageOp(action, rec, (page) =>
+      readable(page, () => withTarget(page, action, rec, fn)),
     );
+  };
 
   // One recorded event whose fields the action itself finishes filling in:
   // `rec` is the very object the recorder spreads once `fn` resolves (the
@@ -797,7 +837,7 @@ export function makeLocator(
     action: string,
     fn: (loc: PWLocator, rec: Partial<RecordableFields>) => Promise<T>,
   ): Promise<T> => {
-    const rec: Partial<RecordableFields> = { selector: label };
+    const rec: Partial<RecordableFields> = { selector: label, target };
     return backend.pageOp(action, rec, (page) =>
       readable(page, () => fn(lower(page, chain), rec)),
     );
@@ -808,13 +848,15 @@ export function makeLocator(
     action: string,
     fn: (loc: PWLocator) => Promise<T>,
     fields: Partial<RecordableFields> = {},
-  ): Promise<Wrapped<T>> =>
-    backend.pageOp(
+  ): Promise<Wrapped<T>> => {
+    const rec: Partial<RecordableFields> = { selector: label, target, ...fields };
+    return backend.pageOp(
       action,
-      { selector: label, ...fields },
-      (page) => readable(page, () => fn(lower(page, chain))),
+      rec,
+      (page) => readable(page, () => withTarget(page, action, rec, fn)),
       { wrap: true },
     ) as Promise<Wrapped<T>>;
+  };
 
   // Silent, non-recorded reads for expect(locator) matchers to poll.
   const probe: LocatorProbe = {
@@ -830,7 +872,7 @@ export function makeLocator(
     isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
     isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
     settle: async (action, waitedMs, error, opts) => {
-      const fields: Partial<RecordableFields> = { selector: label };
+      const fields: Partial<RecordableFields> = { selector: label, target };
       if (opts && opts.reveal) {
         await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
       }
@@ -887,9 +929,9 @@ export function makeLocator(
     check: (opts) => act("check", {}, (l) => l.check({ timeout: opts?.timeout })),
     uncheck: (opts) => act("uncheck", {}, (l) => l.uncheck({ timeout: opts?.timeout })),
     setChecked: (checked, opts) =>
-      act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
+      act("setChecked", { checked }, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
     selectOption: (values, opts) =>
-      read("selectOption", (l) => l.selectOption(values as never, { timeout: opts?.timeout })),
+      read("selectOption", (l) => l.selectOption(values as never, { timeout: opts?.timeout }), { values }),
     setInputFiles: (files, opts) => {
       const { arg, names } = lowerInputFiles(files);
       return act("setInputFiles", { files: names }, (l) =>
@@ -902,7 +944,7 @@ export function makeLocator(
     scrollIntoViewIfNeeded: (opts) =>
       act("scrollIntoViewIfNeeded", {}, (l) => l.scrollIntoViewIfNeeded({ timeout: opts?.timeout })),
     dragTo: (target, opts) =>
-      act("dragTo", {}, (l, page) => l.dragTo(lower(page, chainOf(target)), { timeout: opts?.timeout })),
+      act("dragTo", { destinationTarget: recordedChain(chainOf(target)) }, (l, page) => l.dragTo(lower(page, chainOf(target)), { timeout: opts?.timeout })),
 
     // reads
     textContent: (opts) => read("textContent", (l) => l.textContent({ timeout: opts?.timeout })),
@@ -931,16 +973,15 @@ export function makeLocator(
       for (let i = 0; i < n; i++) out.push(extend({ m: "nth", args: [i] }));
       return out;
     },
-    evaluate: (description, fn, arg) =>
-      backend.pageOp(
-        "evaluate",
-        { selector: label, description },
-        (page) => readable(page, () => lower(page, chain).evaluate(fn as never, arg)),
-        { wrap: true },
-      ) as Promise<Wrapped<never>>,
+    evaluate: (description, fn, arg) => {
+      const script = truncateUtf8(fn.toString());
+      return read("evaluate", (l) => l.evaluate(fn as never, arg), {
+        description, script: script.value, scriptTruncated: script.truncated,
+      }) as Promise<Wrapped<never>>;
+    },
 
     waitFor: (opts) =>
-      act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
+      act("waitFor", { state: opts?.state ?? "visible" }, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
   };
   // Attach the silent-read probe under its symbol (kept off the typed literal
   // so declaration order stays simple).

package/src/recorder.ts

@@ -458,9 +458,18 @@ export interface EnvEvent extends BaseEvent {
 // "check", "hover", "textContent", "inputValue", "count", "screenshot".
 export type BrowserAction = string;
 
+/** JSON-safe locator syntax. Regexes use {regex, flags}, nested locators
+ * use another chain. Presentation is determined by the dashboard. */
+export interface RecordedBrowserLocatorPart {
+  method: string;
+  args: unknown[];
+}
+
 export interface BrowserEvent extends BaseEvent {
   kind: "browser";
   action: BrowserAction;
+  target?: RecordedBrowserLocatorPart[];
+  destinationTarget?: RecordedBrowserLocatorPart[];
   /** Target URL (navigate). */
   url?: string;
   /** CSS selector (click, scrollTo). */
@@ -480,6 +489,10 @@ export interface BrowserEvent extends BaseEvent {
   /** File names given to an `<input type="file">` (setInputFiles). Names
    *  only — a built file's bytes stay out of the timeline. */
   files?: string[];
+  /** Arguments used by the dashboard to describe the operation completely. */
+  checked?: boolean;
+  values?: string | string[] | { label?: string; value?: string; index?: number };
+  state?: string;
   /** Scroll/click coordinates. */
   dx?: number;
   dy?: number;