@specific.dev/spectest 0.50.0 → 0.51.0

package/dist/browser.d.ts

@@ -360,4 +360,5 @@ export interface RecordableFields {
     artifactId: string;
     attribute: string;
     files: string[];
+    targetNodeId: number;
 }

package/dist/index.js

@@ -524,6 +524,15 @@ function buildLocatorMatchers(loc, negated, message) {
         const started = Date.now();
         const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
         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
+        // `LocatorProbe.settle`). Only the visibility matchers flip with `negated`
+        // — `not.toHaveText(...)` is still an element the reader should be looking
+        // at — and `toHaveCount(0)` is the third way of saying "expect nothing".
+        const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
+        const expectsGone = (visibility && (matcher === "toBeHidden") !== negated) ||
+            (matcher === "toHaveCount" && expected === 0);
+        const settleOpts = { reveal: !expectsGone };
         for (;;) {
             let satisfied;
             try {
@@ -541,7 +550,7 @@ function buildLocatorMatchers(loc, negated, message) {
             }
             const passed = satisfied !== negated;
             if (passed) {
-                const sourceSeq = await probe.settle(matcher, Date.now() - started);
+                const sourceSeq = await probe.settle(matcher, Date.now() - started, undefined, settleOpts);
                 recordAssertion({
                     matcher,
                     negated,
@@ -555,7 +564,7 @@ function buildLocatorMatchers(loc, negated, message) {
             }
             if (Date.now() >= deadline) {
                 const msg = describe(actual);
-                const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
+                const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);
                 recordAssertion({
                     matcher,
                     negated,

package/dist/locator.d.ts

@@ -151,8 +151,16 @@ export interface LocatorProbe {
      *  locator's `expect(...)` matcher assertion nests under, and return its seq
      *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
      *  poll time, `error` marks the step failed on a timed-out matcher. Returns
-     *  `undefined` when nothing is recording. */
-    settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+     *  `undefined` when nothing is recording.
+     *
+     *  `opts.reveal` additionally stamps the element's rrweb node id for the
+     *  replay viewer (see {@link stampRevealTarget}). The caller decides,
+     *  because only it knows whether the matcher expects the element on screen:
+     *  probing for one a passing `toBeHidden()` says is gone would do nothing
+     *  but wait out the probe's own timeout. */
+    settle(action: string, waitedMs: number, error?: string, opts?: {
+        reveal?: boolean;
+    }): Promise<number | undefined>;
 }
 /** Silent (non-recorded) reads an `expect(browser)` matcher polls — the
  *  session twin of {@link LocatorProbe}. Lives here, next to it, so `index.ts`

package/dist/locator.js

@@ -244,9 +244,22 @@ async function stampActionPoint(loc, rec, position) {
         const pt = await loc.evaluate((el, pos) => {
             if (window.top !== window)
                 return null;
+            // rrweb's id for this element, in the same one round trip. It is what
+            // the replay actually needs: a coordinate is measured against the VM's
+            // layout a moment BEFORE playwright's own actionability wait, so an
+            // element still animating in (or one the dashboard's fonts lay out a
+            // little differently) leaves the recorded point beside the element
+            // rather than on it — measured 27px low on a modal with an entrance
+            // animation. The id lets the viewer place the cursor from the replay's
+            // own layout instead. Stamped even when the point below is not, since
+            // the viewer can scroll an off-screen element into view.
+            const w = window;
+            const getId = w.__spectestRec?.mirror?.getId;
+            const rawId = typeof getId === "function" ? getId.call(w.__spectestRec.mirror, el) : 0;
+            const nodeId = typeof rawId === "number" && rawId > 0 ? rawId : 0;
             const r = el.getBoundingClientRect();
             if (!r.width || !r.height)
-                return null;
+                return nodeId ? { nodeId } : null;
             // Playwright clicks the element's centre unless the caller named a
             // point — which it takes relative to the PADDING box, so an element
             // with a border (a plain `<button>` has 2px of it) sits that far off
@@ -255,17 +268,57 @@ async function stampActionPoint(loc, rec, position) {
             const x = cs ? r.left + parseFloat(cs.borderLeftWidth) + pos.x : r.left + r.width / 2;
             const y = cs ? r.top + parseFloat(cs.borderTopWidth) + pos.y : r.top + r.height / 2;
             const onScreen = x >= 0 && y >= 0 && x <= window.innerWidth && y <= window.innerHeight;
-            return onScreen ? { x, y } : null;
+            return onScreen ? { x, y, nodeId } : { nodeId };
         }, position, { timeout: POINT_PROBE_MS });
-        if (pt) {
+        if (pt && pt.x !== undefined) {
             rec.x = Math.round(pt.x);
             rec.y = Math.round(pt.y);
         }
+        if (pt && pt.nodeId)
+            rec.targetNodeId = pt.nodeId;
     }
     catch {
         /* Element not ready / gone / strict violation — the action reports it. */
     }
 }
+/** 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.
+ *
+ *  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
+ *  `toBeVisible()`. The replay then shows the recorded viewport, which is a
+ *  frame the asserted element isn't in: the reader sees a page that looks
+ *  unrelated to the step. The id is the element's identity in the recording
+ *  (rrweb's own mirror, the same id space its mutation events carry), so the
+ *  viewer can find the node in the replayed DOM and scroll it into view —
+ *  measured against the replay's real layout rather than a rect we recorded
+ *  here, and correct for an element inside a scrollable container too.
+ *
+ *  Best-effort like {@link stampActionPoint}, and only for the top-level
+ *  document: a frame's recorder has its own mirror, whose ids mean nothing in
+ *  the main frame's stream. An unserialized node (`getId` → -1) or no recorder
+ *  leaves the step unstamped, which just means the viewer doesn't scroll. */
+async function stampRevealTarget(loc, rec) {
+    try {
+        const id = await loc.evaluate((el) => {
+            if (window.top !== window)
+                return 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;
+            const getId = w.__spectestRec?.mirror?.getId;
+            if (typeof getId !== "function")
+                return 0;
+            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 {
+        /* Element gone / not attached / strict violation — no reveal target. */
+    }
+}
 /** Fold a {@link InputFiles} argument into the one playwright takes: repo
  *  paths resolved to their in-VM location (see project-files.ts), built files
  *  given a default mime type and a real `Buffer`. The names come back too —
@@ -320,7 +373,13 @@ export function makeLocator(backend, strategy, chain) {
         count: () => backend.silentRead((page) => lower(page, chain).count()),
         isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
         isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
-        settle: (action, waitedMs, error) => backend.recordSettled(action, { selector: label }, waitedMs, error),
+        settle: async (action, waitedMs, error, opts) => {
+            const fields = { selector: label };
+            if (opts && opts.reveal) {
+                await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+            }
+            return backend.recordSettled(action, fields, waitedMs, error);
+        },
     };
     const loc = {
         [LOCATOR_BRAND]: true,

package/dist/recorder.d.ts

@@ -418,6 +418,15 @@ export interface BrowserEvent extends BaseEvent {
     dy?: number;
     x?: number;
     y?: number;
+    /**
+     * rrweb node id of the element a settled `expect(locator)` step asserted on
+     * — the element's identity in this session's recording. Playwright calls an
+     * element below the fold visible, so the frame the step seeks to need not
+     * contain it; with this the viewer finds the node in the replayed DOM and
+     * scrolls it into view. Absent when the SDK couldn't measure it (an element
+     * in a frame, one rrweb hasn't serialized, a matcher whose subject is gone).
+     */
+    targetNodeId?: number;
     /** Screenshot image format. */
     format?: string;
     /** For `waitFor`: how many times the predicate was polled. */

package/package.json

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

package/src/browser.ts

@@ -2093,4 +2093,5 @@ export interface RecordableFields {
   artifactId: string;
   attribute: string;
   files: string[];
+  targetNodeId: number;
 }

package/src/index.ts

@@ -2328,6 +2328,16 @@ function buildLocatorMatchers(
     const started = Date.now();
     const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
     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
+    // `LocatorProbe.settle`). Only the visibility matchers flip with `negated`
+    // — `not.toHaveText(...)` is still an element the reader should be looking
+    // at — and `toHaveCount(0)` is the third way of saying "expect nothing".
+    const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
+    const expectsGone =
+      (visibility && (matcher === "toBeHidden") !== negated) ||
+      (matcher === "toHaveCount" && expected === 0);
+    const settleOpts = { reveal: !expectsGone };
     for (;;) {
       let satisfied: boolean;
       try {
@@ -2344,7 +2354,7 @@ function buildLocatorMatchers(
       }
       const passed = satisfied !== negated;
       if (passed) {
-        const sourceSeq = await probe.settle(matcher, Date.now() - started);
+        const sourceSeq = await probe.settle(matcher, Date.now() - started, undefined, settleOpts);
         recordAssertion({
           matcher,
           negated,
@@ -2358,7 +2368,7 @@ function buildLocatorMatchers(
       }
       if (Date.now() >= deadline) {
         const msg = describe(actual);
-        const sourceSeq = await probe.settle(matcher, Date.now() - started, msg);
+        const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);
         recordAssertion({
           matcher,
           negated,

package/src/locator.ts

@@ -322,8 +322,19 @@ export interface LocatorProbe {
    *  locator's `expect(...)` matcher assertion nests under, and return its seq
    *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
    *  poll time, `error` marks the step failed on a timed-out matcher. Returns
-   *  `undefined` when nothing is recording. */
-  settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+   *  `undefined` when nothing is recording.
+   *
+   *  `opts.reveal` additionally stamps the element's rrweb node id for the
+   *  replay viewer (see {@link stampRevealTarget}). The caller decides,
+   *  because only it knows whether the matcher expects the element on screen:
+   *  probing for one a passing `toBeHidden()` says is gone would do nothing
+   *  but wait out the probe's own timeout. */
+  settle(
+    action: string,
+    waitedMs: number,
+    error?: string,
+    opts?: { reveal?: boolean },
+  ): Promise<number | undefined>;
 }
 
 /** Silent (non-recorded) reads an `expect(browser)` matcher polls — the
@@ -446,8 +457,23 @@ async function stampActionPoint(
     const pt = await loc.evaluate(
       (el, pos) => {
         if (window.top !== window) return null;
+        // rrweb's id for this element, in the same one round trip. It is what
+        // the replay actually needs: a coordinate is measured against the VM's
+        // layout a moment BEFORE playwright's own actionability wait, so an
+        // element still animating in (or one the dashboard's fonts lay out a
+        // little differently) leaves the recorded point beside the element
+        // rather than on it — measured 27px low on a modal with an entrance
+        // animation. The id lets the viewer place the cursor from the replay's
+        // own layout instead. Stamped even when the point below is not, since
+        // the viewer can scroll an off-screen element into view.
+        const w = window as unknown as {
+          __spectestRec?: { mirror?: { getId?: (n: Node) => number } };
+        };
+        const getId = w.__spectestRec?.mirror?.getId;
+        const rawId = typeof getId === "function" ? getId.call(w.__spectestRec!.mirror, el) : 0;
+        const nodeId = typeof rawId === "number" && rawId > 0 ? rawId : 0;
         const r = el.getBoundingClientRect();
-        if (!r.width || !r.height) return null;
+        if (!r.width || !r.height) return nodeId ? { nodeId } : null;
         // Playwright clicks the element's centre unless the caller named a
         // point — which it takes relative to the PADDING box, so an element
         // with a border (a plain `<button>` has 2px of it) sits that far off
@@ -457,20 +483,65 @@ async function stampActionPoint(
         const y = cs ? r.top + parseFloat(cs.borderTopWidth) + pos!.y : r.top + r.height / 2;
         const onScreen =
           x >= 0 && y >= 0 && x <= window.innerWidth && y <= window.innerHeight;
-        return onScreen ? { x, y } : null;
+        return onScreen ? { x, y, nodeId } : { nodeId };
       },
       position,
       { timeout: POINT_PROBE_MS },
     );
-    if (pt) {
+    if (pt && pt.x !== undefined) {
       rec.x = Math.round(pt.x);
-      rec.y = Math.round(pt.y);
+      rec.y = Math.round(pt.y!);
     }
+    if (pt && pt.nodeId) rec.targetNodeId = pt.nodeId;
   } catch {
     /* Element not ready / gone / strict violation — the action reports it. */
   }
 }
 
+/** 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.
+ *
+ *  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
+ *  `toBeVisible()`. The replay then shows the recorded viewport, which is a
+ *  frame the asserted element isn't in: the reader sees a page that looks
+ *  unrelated to the step. The id is the element's identity in the recording
+ *  (rrweb's own mirror, the same id space its mutation events carry), so the
+ *  viewer can find the node in the replayed DOM and scroll it into view —
+ *  measured against the replay's real layout rather than a rect we recorded
+ *  here, and correct for an element inside a scrollable container too.
+ *
+ *  Best-effort like {@link stampActionPoint}, and only for the top-level
+ *  document: a frame's recorder has its own mirror, whose ids mean nothing in
+ *  the main frame's stream. An unserialized node (`getId` → -1) or no recorder
+ *  leaves the step unstamped, which just means the viewer doesn't scroll. */
+async function stampRevealTarget(
+  loc: PWLocator,
+  rec: Partial<RecordableFields>,
+): Promise<void> {
+  try {
+    const id = await loc.evaluate(
+      (el) => {
+        if (window.top !== window) return 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 {
+          __spectestRec?: { mirror?: { getId?: (n: Node) => number } };
+        };
+        const getId = w.__spectestRec?.mirror?.getId;
+        if (typeof getId !== "function") return 0;
+        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 {
+    /* Element gone / not attached / strict violation — no reveal target. */
+  }
+}
+
 /** Fold a {@link InputFiles} argument into the one playwright takes: repo
  *  paths resolved to their in-VM location (see project-files.ts), built files
  *  given a default mime type and a real `Buffer`. The names come back too —
@@ -671,8 +742,13 @@ export function makeLocator(
     count: () => backend.silentRead((page) => lower(page, chain).count()),
     isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
     isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
-    settle: (action, waitedMs, error) =>
-      backend.recordSettled(action, { selector: label }, waitedMs, error),
+    settle: async (action, waitedMs, error, opts) => {
+      const fields: Partial<RecordableFields> = { selector: label };
+      if (opts && opts.reveal) {
+        await backend.silentRead((page) => stampRevealTarget(lower(page, chain), fields));
+      }
+      return backend.recordSettled(action, fields, waitedMs, error);
+    },
   };
 
   const loc: InternalLocator = {

package/src/recorder.ts

@@ -473,6 +473,15 @@ export interface BrowserEvent extends BaseEvent {
   dy?: number;
   x?: number;
   y?: number;
+  /**
+   * rrweb node id of the element a settled `expect(locator)` step asserted on
+   * — the element's identity in this session's recording. Playwright calls an
+   * element below the fold visible, so the frame the step seeks to need not
+   * contain it; with this the viewer finds the node in the replayed DOM and
+   * scrolls it into view. Absent when the SDK couldn't measure it (an element
+   * in a frame, one rrweb hasn't serialized, a matcher whose subject is gone).
+   */
+  targetNodeId?: number;
   /** Screenshot image format. */
   format?: string;
   /** For `waitFor`: how many times the predicate was polled. */