@specific.dev/spectest 0.18.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/browser.ts

@@ -533,8 +533,12 @@ const RRWEB_BOOTSTRAP = `
       // faithfully offline (the dashboard reconstructs the DOM with no
       // access to the env's origin). \`inlineStylesheet\` (default, set
       // explicitly) bakes <style>/<link> CSS into the snapshot;
-      // \`inlineImages\` turns <img> and CSS background images into data
-      // URIs. \`collectFonts\` only captures fonts added via the JS
+      // \`inlineImages\` turns <img> elements into data URIs — but ONLY
+      // synchronously, for images already decoded at serialize time
+      // (its late-load path patches the emitted event in place, which
+      // loses the race against our per-op drains; the image inliner
+      // below covers that case with synthetic mutation events).
+      // \`collectFonts\` only captures fonts added via the JS
       // FontFace API — it does NOT inline static \`@font-face { src:url() }\`
       // CSS (what next/font emits), so it's a no-op for most apps; the
       // url()-based fonts are handled by the inliner below instead. All
@@ -685,6 +689,119 @@ const RRWEB_BOOTSTRAP = `
       }
     } catch (e) { log("init FAIL " + (e && e.message)); }
   })();
+  // ── Inline late-loading <img>s as synthetic src mutations ──────────
+  // rrweb's inlineImages only bakes a data: URI in synchronously when
+  // the image is already decoded at serialize time. An image that
+  // finishes loading AFTER its node was serialized is patched by rrweb
+  // IN PLACE on the already-emitted event object — lost whenever a
+  // drain (op boundary) ships the buffer first. Classic case: a tap
+  // reveals a screen full of first-seen images; the step's drain fires
+  // right after the tap, the images decode a beat later, and the replay
+  // is left with raw in-VM URLs it can't fetch (hermetic env).
+  //
+  // Fix: listen for image loads ourselves (capture phase on document —
+  // runs BEFORE rrweb's target-phase listener) and, once the element
+  // has an id in rrweb's mirror, push a synthetic incremental mutation
+  // rewriting the img's src to a data: URI. A mutation event rides
+  // whatever drain comes next, so it survives the race even when the
+  // add event is long gone. Bytes come from a same-origin fetch of the
+  // ORIGINAL file (compact and lossless — rrweb's canvas path
+  // re-encodes JPEGs as much larger PNGs). It must be a plain \`src\`
+  // rewrite: the replayer honors \`rr_dataURL\` only when BUILDING a
+  // node; in the attribute-mutation path it just sets the literal
+  // attribute (only canvas is special-cased there).
+  (function () {
+    if (window.__spectestImgInliner) return;
+    window.__spectestImgInliner = true;
+    function log(m) { try { console.log("[spectest-img] " + m); } catch (e) {} }
+    var cache = {};
+    function fetchDataUri(url) {
+      if (cache[url]) return cache[url];
+      cache[url] = fetch(url).then(function (r) {
+        if (!r.ok) throw new Error("HTTP " + r.status);
+        return r.blob();
+      }).then(function (blob) {
+        return new Promise(function (resolve, reject) {
+          var fr = new FileReader();
+          fr.onload = function () { resolve(fr.result); };
+          fr.onerror = reject;
+          fr.readAsDataURL(blob);
+        });
+      });
+      return cache[url];
+    }
+    // The serialized-node meta when rrweb already inlined THIS src on
+    // it (rr_dataURL present and the recorded src matches — a stale
+    // bake from a previous src must not count).
+    function bakedMeta(mirror, img, src) {
+      try {
+        var meta = mirror.getMeta(img);
+        if (meta && meta.attributes && meta.attributes.rr_dataURL &&
+            meta.attributes.src === src) return meta;
+      } catch (e) {}
+      return null;
+    }
+    function onImgLoad(img, src) {
+      var mirror = rec && rec.mirror;
+      if (!mirror || typeof mirror.getId !== "function" ||
+          typeof mirror.getMeta !== "function") return;
+      // A patch visible NOW — before rrweb's own load listener has run
+      // (we're capture phase, it's target phase) — can only be the
+      // synchronous serialize-time bake, which shipped inside the event
+      // itself. Nothing to do.
+      var preId = mirror.getId(img);
+      if (preId > 0 && bakedMeta(mirror, img, src)) return;
+      var tries = 0;
+      function finish() {
+        var id = mirror.getId(img);
+        if (!(id > 0)) {
+          // Not serialized yet (mutation batch pending, or the initial
+          // full snapshot hasn't run — rrweb defers it to window load).
+          tries++;
+          if (tries < 40) setTimeout(finish, 50);
+          else log("drop (never serialized) " + src);
+          return;
+        }
+        var meta = bakedMeta(mirror, img, src);
+        if (meta && preId < 1) return; // serialized after load → sync bake
+        if (meta) {
+          // rrweb's async in-place patch landed after our capture-phase
+          // check. If the add is still in the buffer it now carries a
+          // PNG re-encode; strip it and ship ours instead (original
+          // bytes, and immune to a drain having already taken the add).
+          try { delete meta.attributes.rr_dataURL; } catch (e) {}
+        }
+        fetchDataUri(src).then(function (dataUri) {
+          var attrs = { src: dataUri };
+          // A srcset would out-rank the patched src in the replay
+          // iframe and point back at the unreachable original.
+          if (img.getAttribute && img.getAttribute("srcset")) attrs.srcset = "";
+          window.__spectestRrwebEvents.push({
+            type: 3,
+            data: { source: 0, texts: [], attributes: [{ id: id, attributes: attrs }], removes: [], adds: [] },
+            timestamp: Date.now(),
+          });
+          log("inlined id=" + id + " bytes=" + dataUri.length + " " + src);
+        }).catch(function (e) {
+          log("fetch FAIL " + src + " : " + (e && e.message));
+        });
+      }
+      // Next task, so rrweb's own load listener has run and its patch
+      // (if any) is observable above.
+      setTimeout(finish, 0);
+    }
+    try {
+      document.addEventListener("load", function (ev) {
+        var el = ev.target;
+        if (!el || !el.tagName || String(el.tagName).toLowerCase() !== "img") return;
+        var src = el.currentSrc || el.src || "";
+        if (!src || src.lastIndexOf("http", 0) !== 0) return; // data:/blob: already replayable
+        if (el.__spectestImgSrc === src) return; // this src already handled
+        el.__spectestImgSrc = src;
+        onImgLoad(el, src);
+      }, true);
+    } catch (e) { log("init FAIL " + (e && e.message)); }
+  })();
 })();
 `;
 

package/src/mobile.ts

@@ -68,11 +68,17 @@ interface LocatorDesc {
   regex?: { source: string; flags: string };
   name?: string;
   nameExact?: boolean;
+  /** Narrowing applied after resolution (`.first()`/`.last()`/`.nth(i)`) —
+   *  the explicit escape hatch from strict mode. */
+  nth?: number | "first" | "last";
 }
 
 /** A lazy reference to a single element, resolved (with auto-wait) at the
  *  moment an action runs. Mirrors the select-then-act idiom shared by
- *  Playwright, Detox, and RN Testing Library. */
+ *  Playwright, Detox, and RN Testing Library — including Playwright's
+ *  STRICT mode: a locator matching multiple elements throws an
+ *  element-listing error rather than acting on one of them. Narrow with
+ *  `exact: true`, a testID, or {@link first}/{@link nth}. */
 export interface MobileLocator {
   /** Wait for the element to be visible (default 5s, `timeoutMs` overrides),
    *  then touch-tap its center. `durationMs` overrides the touch dwell. */
@@ -94,13 +100,23 @@ export interface MobileLocator {
   /** The element's text content, wrapped. Waits (default 5s) for the
    *  element to become visible; throws if it never does. */
   textContent(): Promise<Wrapped<string | null>>;
+  /** Narrow to the first resolved element — the explicit opt-out from
+   *  strict mode when multiple matches are intentional. */
+  first(): MobileLocator;
+  /** Narrow to the last resolved element. */
+  last(): MobileLocator;
+  /** Narrow to the i-th resolved element (0-based). */
+  nth(index: number): MobileLocator;
 }
 
-/** Map a locator descriptor onto a playwright Locator. The trailing
- *  `.filter({ visible: true }).first()` preserves the pre-Playwright
- *  selection rule: the first VISIBLE match wins, and a hidden duplicate
- *  (e.g. an offscreen menu item with the same label) neither gets picked
- *  nor trips playwright's strict-mode multi-match error. */
+/** Map a locator descriptor onto a playwright Locator — STRICT, exactly
+ *  like stock Playwright: a locator that resolves to multiple elements
+ *  throws an element-listing "strict mode violation" at action time
+ *  instead of silently picking one. (An earlier `.filter({visible})
+ *  .first()` auto-pick deterministically tapped the WRONG element when
+ *  case-insensitive substring matching made two leaves qualify —
+ *  `getByText("Men")` also matches "Wo**men**". Loud beats lucky.)
+ *  Disambiguate with `exact: true`, a testID, or `.first()`/`.nth(i)`. */
 function pwLocator(page: Page, desc: LocatorDesc): Locator {
   let base: Locator;
   switch (desc.kind) {
@@ -126,18 +142,25 @@ function pwLocator(page: Page, desc: LocatorDesc): Locator {
       );
       break;
   }
-  return base.filter({ visible: true }).first();
+  if (desc.nth === "first") return base.first();
+  if (desc.nth === "last") return base.last();
+  if (typeof desc.nth === "number") return base.nth(desc.nth);
+  return base;
 }
 
 /** Short human label for a descriptor, used in event descriptions. */
 function descLabel(desc: LocatorDesc): string {
+  let base: string;
   if (desc.kind === "text") {
-    return desc.regex ? `text /${desc.regex.source}/` : `text ${JSON.stringify(desc.value)}`;
+    base = desc.regex ? `text /${desc.regex.source}/` : `text ${JSON.stringify(desc.value)}`;
+  } else if (desc.kind === "role") {
+    base = desc.name ? `role ${desc.value} ${JSON.stringify(desc.name)}` : `role ${desc.value}`;
+  } else {
+    base = `${desc.kind} ${JSON.stringify(desc.value)}`;
   }
-  if (desc.kind === "role") {
-    return desc.name ? `role ${desc.value} ${JSON.stringify(desc.name)}` : `role ${desc.value}`;
-  }
-  return `${desc.kind} ${JSON.stringify(desc.value)}`;
+  if (desc.nth === "first" || desc.nth === "last") return `${base} .${desc.nth}()`;
+  if (typeof desc.nth === "number") return `${base} .nth(${desc.nth})`;
+  return base;
 }
 
 /** Default wait for a locator action's target to become visible. Override
@@ -223,6 +246,15 @@ function makeLocator(backend: MobileBackend, desc: LocatorDesc): MobileLocator {
         pwLocator(page, desc).textContent({ timeout: DEFAULT_ACTION_TIMEOUT_MS }),
       ) as Promise<Wrapped<string | null>>;
     },
+    first() {
+      return makeLocator(backend, { ...desc, nth: "first" });
+    },
+    last() {
+      return makeLocator(backend, { ...desc, nth: "last" });
+    },
+    nth(index: number) {
+      return makeLocator(backend, { ...desc, nth: index });
+    },
   };
 }