@percy/nightwatch 2.2.1-beta.0 → 2.2.1-beta.1

package/commands/percySnapshot.js

@@ -46,8 +46,10 @@ module.exports = class PercySnapshotCommand {
       // Readiness gate — runs before serialize when CLI supports it.
       const readinessDiagnostics = await waitForReady(this.api, options, utils, log);
 
-      // Serialize and capture the DOM
-      let { domSnapshot, url } = await captureDOM(this.api, options, utils, log, domScript);
+      // Thread domScript + log through ctx so concurrent percySnapshot calls
+      // (parallel workers in the same Node process) don't race on shared
+      // module-level state.
+      let { domSnapshot, url } = await captureDOM(this.api, options, utils, domScript, log);
 
       // Attach readiness diagnostics so the CLI can log timing and pass/fail
       if (readinessDiagnostics && domSnapshot && typeof domSnapshot === 'object' && !Array.isArray(domSnapshot)) {

package/lib/snapshot.js

@@ -1,6 +1,31 @@
+// Canonical iframe-capture helpers, single source of truth (percy/cli #2319).
+// Aliased to the local _FRAME_ names this module already uses.
+const {
+  DEFAULT_MAX_IFRAME_DEPTH: DEFAULT_MAX_FRAME_DEPTH,
+  isUnsupportedIframeSrc,
+  clampIframeDepth: clampFrameDepth,
+  normalizeIgnoreSelectors
+} = require('@percy/sdk-utils');
+
 const CS_MAX_SCREENSHOT_LIMIT = 25000;
 const SCROLL_DEFAULT_SLEEP_TIME = 0.45; // 450ms
 
+// Kept for backward compatibility with callers that previously pinned a
+// module-scope domScript + log. The new code threads both through ctx /
+// function arguments so two concurrent percySnapshot calls cannot race on
+// shared module state. This function is a no-op.
+function setSnapshotContext(/* script, logger */) {
+  // Intentionally empty — context now flows through ctx.
+}
+
+function getOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
 function ignoreCanvasSerializationErrors(options = {}, utils) {
   return options?.ignoreCanvasSerializationErrors ??
     utils?.percy?.config?.snapshot?.ignoreCanvasSerializationErrors ??
@@ -102,7 +127,262 @@ function getCookies(browser) {
   }).catch(() => []);
 }
 
-async function captureSerializedDOM(browser, options = {}, utils) {
+function resolveMaxFrameDepth(options = {}, utils) {
+  return clampFrameDepth(
+    options.maxIframeDepth ??
+    utils?.percy?.config?.snapshot?.maxIframeDepth ??
+    DEFAULT_MAX_FRAME_DEPTH
+  );
+}
+
+function resolveIgnoreSelectors(options = {}, utils) {
+  return normalizeIgnoreSelectors(
+    options.ignoreIframeSelectors ??
+    utils?.percy?.config?.snapshot?.ignoreIframeSelectors ??
+    []
+  );
+}
+
+// In-browser script that walks document.querySelectorAll('iframe') and
+// returns metadata for each. Defined as a function reference so the two
+// call sites (top-level enumeration in captureCorsIframes and per-frame
+// recursion in processFrameTree) share one body.
+function enumerateIframesScript(selectors) {
+  let iframes = document.querySelectorAll('iframe');
+  let result = [];
+  for (let i = 0; i < iframes.length; i++) {
+    let frame = iframes[i];
+    let matchesIgnore = false;
+    if (selectors && selectors.length) {
+      for (let j = 0; j < selectors.length; j++) {
+        try { if (frame.matches(selectors[j])) { matchesIgnore = true; break; } } catch (e) { /* invalid selector — ignore */ }
+      }
+    }
+    result.push({
+      src: frame.src || '',
+      srcdoc: frame.getAttribute('srcdoc'),
+      percyElementId: frame.getAttribute('data-percy-element-id'),
+      dataPercyIgnore: frame.hasAttribute('data-percy-ignore'),
+      matchesIgnoreSelector: matchesIgnore,
+      index: i
+    });
+  }
+  return result;
+}
+
+function shouldSkipIframe(iframe, currentOrigin, log) {
+  if (iframe.dataPercyIgnore) {
+    log?.debug?.(`Skipping iframe marked with data-percy-ignore: ${iframe.src || '(no src)'}`);
+    return true;
+  }
+  if (iframe.matchesIgnoreSelector) {
+    log?.debug?.(`Skipping iframe matching ignoreIframeSelectors: ${iframe.src || '(no src)'}`);
+    return true;
+  }
+  if (!iframe.src || isUnsupportedIframeSrc(iframe.src)) {
+    if (iframe.src) log?.debug?.(`Skipping unsupported iframe src: ${iframe.src}`);
+    return true;
+  }
+  if (iframe.srcdoc) {
+    log?.debug?.(`Skipping srcdoc iframe at index ${iframe.index}`);
+    return true;
+  }
+  let frameOrigin = getOrigin(iframe.src);
+  if (!frameOrigin) {
+    log?.debug?.(`Skipping iframe with invalid URL: ${iframe.src}`);
+    return true;
+  }
+  if (frameOrigin === currentOrigin) {
+    log?.debug?.(`Skipping same-origin iframe: ${iframe.src}`);
+    return true;
+  }
+  if (!iframe.percyElementId) {
+    log?.debug?.(`Skipping cross-origin iframe without data-percy-element-id: ${iframe.src}`);
+    return true;
+  }
+  return false;
+}
+
+// Switch into the given iframe element from the current frame context, capture
+// its DOM, then recurse into any cross-origin iframes nested inside it. Restores
+// the parent context on exit. Bounded by maxFrameDepth to prevent runaway
+// recursion when pages link to each other in cycles. `ancestorUrls` tracks the
+// chain of frame URLs above this one — if the current frame's URL appears in
+// the chain, we treat it as a cycle and stop descending (still capturing the
+// current frame once).
+async function processFrameTree(browser, iframe, depth, ancestorUrls, ctx) {
+  const { maxFrameDepth, ignoreSelectors, serializeOptions, domScript, log } = ctx;
+  if (depth > maxFrameDepth) {
+    log?.debug?.(`Reached max iframe nesting depth (${maxFrameDepth}); stopping at ${iframe.src}`);
+    return [];
+  }
+  if (ancestorUrls && ancestorUrls.has(iframe.src)) {
+    log?.debug?.(`Skipping cyclic iframe (${iframe.src} appears in ancestor chain)`);
+    return [];
+  }
+
+  const collected = [];
+  let switchedIn = false;
+  let capturedError = null;
+
+  try {
+    log?.debug?.(`Processing cross-origin iframe (depth ${depth}): ${iframe.src}`);
+
+    // Switch to the iframe by its data-percy-element-id attribute instead of numeric
+    // index, which avoids drift if the DOM changes between enumeration and switch.
+    // CSS.escape() neutralises any quote/backslash characters that could otherwise
+    // break out of the attribute selector — defence in depth, since the id is
+    // SDK-generated.
+    let iframeElement = await executeScript(browser, function(percyId) {
+      /* eslint-disable-next-line no-undef */
+      const cssApi = (typeof CSS !== 'undefined') ? CSS : null;
+      const safeId = (cssApi && cssApi.escape) ? cssApi.escape(percyId) : String(percyId).replace(/["\\]/g, '\\$&');
+      return document.querySelector('iframe[data-percy-element-id="' + safeId + '"]');
+    }, [iframe.percyElementId]);
+
+    if (!iframeElement) {
+      log?.warn?.(`Could not find iframe element with data-percy-element-id: ${iframe.percyElementId}`);
+      return [];
+    }
+
+    await promisifyBrowserCommand(browser, 'frame', iframeElement);
+    switchedIn = true;
+
+    // Inject PercyDOM into the frame
+    if (domScript) {
+      await executeScript(browser, domScript);
+      log?.debug?.(`Injected PercyDOM into frame: ${iframe.src}`);
+    }
+
+    // Serialize the frame's DOM; enableJavaScript is intentionally forced to true
+    // to prevent the standard iframe serialization logic from running, since we
+    // handle cross-origin iframe serialization manually here
+    let frameResult = await executeScript(browser, function(opts) {
+      return {
+        /* eslint-disable-next-line no-undef */
+        snapshot: PercyDOM.serialize(opts),
+        frameUrl: document.URL
+      };
+    }, [{ ...serializeOptions, enableJavaScript: true }]);
+
+    if (!frameResult || !frameResult.snapshot) {
+      log?.warn?.(`Serialization returned empty result for frame: ${iframe.src}`);
+      return [];
+    }
+
+    log?.debug?.(`Captured cross-origin iframe (depth ${depth}): ${frameResult.frameUrl}`);
+
+    collected.push({
+      frameUrl: frameResult.frameUrl,
+      iframeData: { percyElementId: iframe.percyElementId },
+      iframeSnapshot: frameResult.snapshot
+    });
+
+    // Look for cross-origin iframes nested inside this frame and recurse into them.
+    // Same-origin descendants are already inlined as srcdoc by PercyDOM.serialize above.
+    if (depth < maxFrameDepth) {
+      let currentOrigin = getOrigin(frameResult.frameUrl);
+      let childIframesRaw = await executeScript(browser, enumerateIframesScript, [ignoreSelectors]);
+      let childIframes = Array.isArray(childIframesRaw) ? childIframesRaw : [];
+      let nextAncestors = new Set(ancestorUrls || []);
+      nextAncestors.add(frameResult.frameUrl);
+      nextAncestors.add(iframe.src);
+      for (let child of childIframes) {
+        if (shouldSkipIframe(child, currentOrigin, log)) continue;
+        let nested = await processFrameTree(browser, child, depth + 1, nextAncestors, ctx);
+        if (nested.length) collected.push(...nested);
+      }
+    }
+
+    return collected;
+  } catch (error) {
+    if (error && error.percyContextLost) {
+      // Merge any partial capture from the inner level into ours before propagating
+      if (Array.isArray(error.partialCapture) && error.partialCapture.length) {
+        collected.push(...error.partialCapture);
+        error.partialCapture = collected;
+      } else {
+        error.partialCapture = collected;
+      }
+      throw error;
+    }
+    log?.warn?.(`Failed to process cross-origin iframe ${iframe.src}: ${error.message}`);
+    capturedError = error;
+    return collected;
+  } finally {
+    if (switchedIn) {
+      // Step up exactly one level so an outer recursion can continue from its
+      // own context. If parentFrame fails we have no reliable way to land in
+      // the correct parent — fall back to top and signal the caller to stop
+      // iterating siblings (whose enumeration was performed in a now-lost
+      // context). Without this signal, sibling lookups would silently match
+      // against the top document and produce wrong percyElementId resolutions.
+      try {
+        await promisifyBrowserCommand(browser, 'frameParent');
+      } catch (e) {
+        log?.warn?.(`Failed to switch back to parent frame: ${e.message}`);
+        try { await promisifyBrowserCommand(browser, 'frame', null); } catch (_) {}
+        // Always raise percyContextLost regardless of depth: even at depth 1
+        // the fallback `frame(null)` leaves us at the top document, so the
+        // caller's pending sibling enumeration was performed in a now-stale
+        // context and must be aborted. Carry partial capture so the outer
+        // caller can keep what was already serialized successfully.
+        const err = new Error(`Lost parent frame context: ${e.message}`);
+        err.percyContextLost = true;
+        err.partialCapture = collected;
+        // Preserve the original error so it isn't swallowed by this throw
+        if (capturedError) err.cause = capturedError;
+        // eslint-disable-next-line no-unsafe-finally
+        throw err;
+      }
+    }
+  }
+}
+
+async function captureCorsIframes(browser, pageUrl, ctx) {
+  const { ignoreSelectors, log } = ctx;
+  try {
+    let iframeInfoRaw = await executeScript(browser, enumerateIframesScript, [ignoreSelectors]);
+    let iframeInfo = Array.isArray(iframeInfoRaw) ? iframeInfoRaw : [];
+    if (!iframeInfo.length) return [];
+
+    log?.debug?.(`Found ${iframeInfo.length} top-level iframe(s)`);
+
+    let pageOrigin = getOrigin(pageUrl);
+    let corsIframes = [];
+    let skippedCount = 0;
+
+    for (let iframe of iframeInfo) {
+      if (shouldSkipIframe(iframe, pageOrigin, log)) {
+        skippedCount++;
+        continue;
+      }
+      let entries;
+      try {
+        entries = await processFrameTree(browser, iframe, 1, new Set([pageUrl]), ctx);
+      } catch (error) {
+        if (error && error.percyContextLost) {
+          log?.warn?.('Aborting further nested CORS capture due to lost frame context');
+          if (Array.isArray(error.partialCapture) && error.partialCapture.length) {
+            corsIframes.push(...error.partialCapture);
+          }
+          break;
+        }
+        throw error;
+      }
+      if (entries && entries.length) corsIframes.push(...entries);
+    }
+
+    log?.debug?.(`Captured ${corsIframes.length} cross-origin iframe(s) (top-level skipped: ${skippedCount})`);
+
+    return corsIframes;
+  } catch (error) {
+    log?.warn?.(`Error capturing CORS iframes: ${error.message}`);
+    return [];
+  }
+}
+
+async function captureSerializedDOM(browser, options = {}, utils, domScript = null, log = null) {
   const serializeOptions = {
     ...options,
     ignoreCanvasSerializationErrors: ignoreCanvasSerializationErrors(options, utils),
@@ -120,6 +400,20 @@ async function captureSerializedDOM(browser, options = {}, utils) {
   if (!domSnapshot) domSnapshot = {};
   domSnapshot.cookies = await getCookies(browser);
 
+  // Capture cross-origin iframes. ctx carries the per-call domScript + log so
+  // concurrent percySnapshot invocations don't race on shared module state.
+  const ctx = {
+    maxFrameDepth: resolveMaxFrameDepth(options, utils),
+    ignoreSelectors: resolveIgnoreSelectors(options, utils),
+    serializeOptions,
+    domScript,
+    log
+  };
+  let corsIframes = await captureCorsIframes(browser, url, ctx);
+  if (corsIframes.length > 0) {
+    domSnapshot.corsIframes = corsIframes;
+  }
+
   return { domSnapshot, url };
 }
 
@@ -272,7 +566,12 @@ async function changeWindowDimensionAndWait(browser, width, height, resizeCount,
 async function maybeReloadPage(browser, domScript) {
   if (!process.env.PERCY_RESPONSIVE_CAPTURE_RELOAD_PAGE) return false;
   await promisifyBrowserCommand(browser, 'refresh');
-  if (domScript) await executeScript(browser, domScript);
+  // Guard: if a consumer imported captureDOM directly (bypassing percySnapshot)
+  // domScript may be null. Skipping the re-injection is safe — the page reload
+  // will only matter when PercyDOM is also pinned.
+  if (domScript) {
+    await executeScript(browser, domScript);
+  }
   return true;
 }
 
@@ -296,7 +595,7 @@ async function getResponsiveHeight(browser, currentHeight, utils) {
   }, [minHeight]);
 }
 
-async function captureResponsiveDOM(browser, options, utils, log, domScript) {
+async function captureResponsiveDOM(browser, options, utils, domScript = null, log = null) {
   const widths = getWidthsForMultiDOM(options.widths || [], utils?.percy?.widths || {});
   const domSnapshots = [];
   const { width: originalWidth, height: originalHeight } = await getWindowRect(browser);
@@ -331,7 +630,7 @@ async function captureResponsiveDOM(browser, options, utils, log, domScript) {
     await maybeSleepForResponsiveCapture();
     await maybeScrollForLazyLoad(browser);
 
-    let { domSnapshot, url } = await captureSerializedDOM(browser, options, utils);
+    let { domSnapshot, url } = await captureSerializedDOM(browser, options, utils, domScript, log);
     domSnapshot.width = width;
     domSnapshots.push(domSnapshot);
     lastURL = url;
@@ -341,13 +640,36 @@ async function captureResponsiveDOM(browser, options, utils, log, domScript) {
   return { domSnapshot: domSnapshots, url: lastURL };
 }
 
-async function captureDOM(browser, options = {}, utils, log, domScript) {
+// Backward-compatibility shim for the two trailing positional arguments.
+//
+// captureDOM is exported and was published (v2.2.1-beta.0) with the signature
+//   captureDOM(browser, options, utils, log, domScript)
+// This branch reordered the trailing pair to (..., domScript, log) so the
+// per-call domScript + logger could be threaded through ctx. Silently swapping
+// two published positional args would break any external caller that imports
+// captureDOM directly and still passes them in the old order.
+//
+// domScript is always the PercyDOM source (a string); log is always a logger
+// object (or null/undefined). They are never the same type, so we can accept
+// either order and route each value to its correct slot. This keeps both the
+// old (log, domScript) and new (domScript, log) call shapes working.
+function normalizeScriptAndLog(a, b) {
+  const isScript = v => typeof v === 'string';
+  if (isScript(a) && !isScript(b)) return { domScript: a, log: b ?? null };
+  if (isScript(b) && !isScript(a)) return { domScript: b, log: a ?? null };
+  // Neither is a string (e.g. both null, or domScript passed as non-string):
+  // fall back to the new positional order without reinterpreting.
+  return { domScript: a ?? null, log: b ?? null };
+}
+
+async function captureDOM(browser, options = {}, utils, arg4 = null, arg5 = null) {
+  const { domScript, log } = normalizeScriptAndLog(arg4, arg5);
   const responsiveEnabled = isResponsiveOptionEnabled(options, utils);
   if (responsiveEnabled) {
-    return await captureResponsiveDOM(browser, options, utils, log, domScript);
+    return await captureResponsiveDOM(browser, options, utils, domScript, log);
   }
 
-  return await captureSerializedDOM(browser, options, utils);
+  return await captureSerializedDOM(browser, options, utils, domScript, log);
 }
 
 async function slowScrollToBottom(browser, scrollSleep = SCROLL_DEFAULT_SLEEP_TIME) {
@@ -400,8 +722,12 @@ async function slowScrollToBottom(browser, scrollSleep = SCROLL_DEFAULT_SLEEP_TI
 module.exports = {
   captureSerializedDOM,
   captureDOM,
+  setSnapshotContext,
   slowScrollToBottom,
   ignoreCanvasSerializationErrors,
   ignoreStyleSheetSerializationErrors,
+  isUnsupportedIframeSrc,
+  getOrigin,
+  captureCorsIframes,
   waitForReady
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@percy/nightwatch",
   "description": "Nightwatch client library for visual testing with Percy",
-  "version": "2.2.1-beta.0",
+  "version": "2.2.1-beta.1",
   "license": "MIT",
   "author": "Perceptual Inc.",
   "repository": "https://github.com/percy/percy-nightwatch",
@@ -29,14 +29,14 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/sdk-utils": "^1.31.15-beta.0",
+    "@percy/sdk-utils": "1.32.3-beta.1",
     "@percy/selenium-webdriver": "^2.2.3"
   },
   "peerDependencies": {
     "nightwatch": ">=1 || >=2 || >=3"
   },
   "devDependencies": {
-    "@percy/cli": "^1.31.4",
+    "@percy/cli": "1.31.14",
     "cross-env": "^10.1.0",
     "eslint": "^7.11.0",
     "eslint-config-standard": "^16.0.1",
@@ -49,5 +49,6 @@
     "nightwatch": "^3.12.3",
     "nyc": "^17.1.0",
     "tsd": "^0.33.0"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }