@percy/core 1.31.14-beta.2 → 1.31.14-beta.4

package/dist/closed-shadow.js

@@ -0,0 +1,194 @@
+// Closed-shadow capture helper. CLI-side only.
+//
+// External Percy SDK plugins (puppeteer-percy, playwright-percy,
+// cypress-percy, selenium-chrome-percy) will get their own copy when
+// SDK-side closed-shadow capture is added — that work is intentionally
+// scoped to a separate change so this PR stays focused on the CLI path.
+//
+// Discovers closed shadow roots in the live page and exposes them to
+// PercyDOM.serialize() via per-document `__percyClosedShadowRoots`
+// WeakMaps that clone-dom.js reads through shadow-utils.getRuntime().
+//
+// Closed shadow roots are inaccessible from JavaScript
+// (`element.shadowRoot === null`), but Chrome DevTools Protocol's DOM domain
+// can pierce them. We get the full DOM tree with `pierce: true` (which also
+// traverses iframe boundaries — closed shadow hosts inside iframes are
+// captured by the same walk), collect every closed-shadow host/root pair,
+// resolve both to JS object references via `DOM.resolveNode`, then call
+// `Runtime.callFunctionOn` to write the mapping. The function body installs
+// the WeakMap on the host's *own* `ownerDocument.defaultView` — so a host
+// inside an iframe writes into the iframe's realm, where shadow-utils will
+// later read it.
+//
+// Works for any caller that has a CDP session-like object exposing
+// `send(method, params) => Promise`:
+//   - Puppeteer:    `await page.target().createCDPSession()`
+//   - Playwright:   `await context.newCDPSession(page)`
+//   - Selenium:     `await driver.getDevTools()` (Chromium only)
+//   - Percy CLI:    Percy's own session.send wrapper
+//
+// Side effect: temporarily enables and then disables the CDP `DOM` domain
+// on the supplied session. Don't run concurrently with another `DOM`-domain
+// consumer on the same session — the helper installs an in-flight guard
+// against itself, but can't see other consumers.
+//
+// Limitation: captures the closed shadow roots present at the time of the
+// call. Custom elements that lazy-attach a closed shadow root after this
+// returns (e.g. inside `requestIdleCallback` or `IntersectionObserver`)
+// won't be captured. The caller is responsible for waiting until the page
+// is settled before invoking.
+//
+// Returns the number of closed shadow roots successfully exposed (0 if none,
+// -1 on top-level error). Per-pair errors are swallowed and surfaced via the
+// optional `log` callback — closed-shadow capture is best-effort and must
+// never break a snapshot run.
+
+const DEFAULT_LOG = () => {};
+
+// Mirrors HARD_MAX_IFRAME_DEPTH from serialize-frames so every recursive
+// walk in the capture pipeline shares the same ceiling. Counted only across
+// shadow / iframe boundary crossings — not plain children — otherwise a
+// normal deep DOM (html → body → div → … → custom-element) would burn
+// through the budget before reaching any shadow host.
+const MAX_SHADOW_DEPTH = 10;
+
+// Bound concurrent CDP messages so we don't flood a session with hundreds
+// of in-flight resolveNode/callFunctionOn calls when a page has many
+// closed shadow hosts. Phase 1 (resolve) issues 2 calls per pair, so peak
+// in-flight there is 2 * CDP_BATCH_SIZE; phase 2 (stamp) is 1 per pair so
+// peak is exactly CDP_BATCH_SIZE. 8 chosen as a conservative default that
+// keeps both phases well under typical CDP message-queue depths.
+const CDP_BATCH_SIZE = 8;
+
+// The function body that installs the WeakMap and writes the host→shadow
+// pair. Runs inside Runtime.callFunctionOn with the host as `this`, so
+// `this.ownerDocument.defaultView` is the host's *own* realm — the iframe's
+// window when the host is inside an iframe.
+//
+// IMPORTANT: this is a string (required by Runtime.callFunctionOn) AND it
+// is intentionally ES5 — it executes in the page's realm, which may be any
+// browser/JS target the page itself targets. Don't "modernize" with arrow
+// functions, let/const, or optional chaining.
+const STAMP_FUNCTION = 'function(shadowRoot) {' + '  var w = this.ownerDocument && this.ownerDocument.defaultView;' + '  if (!w) return;' + '  if (!w.__percyClosedShadowRoots) w.__percyClosedShadowRoots = new WeakMap();' + '  w.__percyClosedShadowRoots.set(this, shadowRoot);' + '}';
+
+// Marker for the in-flight guard — prevents concurrent invocations on the
+// same session from racing each other's DOM.enable / DOM.disable lifecycle.
+// Module-local Symbol (not Symbol.for) so it can't collide with any other
+// global registry entry.
+const IN_FLIGHT = Symbol('percy.closedShadow.inFlight');
+export async function exposeClosedShadowRoots(cdp, log = DEFAULT_LOG) {
+  if (!cdp || typeof cdp.send !== 'function') return -1;
+  if (cdp[IN_FLIGHT]) {
+    log('Skipping concurrent closed-shadow CDP discovery on the same session');
+    return -1;
+  }
+  cdp[IN_FLIGHT] = true;
+  let domEnabled = false;
+  try {
+    await cdp.send('DOM.enable');
+    domEnabled = true;
+    const {
+      root
+    } = await cdp.send('DOM.getDocument', {
+      depth: -1,
+      pierce: true
+    });
+    const closedPairs = [];
+    walkCDPNodes(root, closedPairs);
+    if (closedPairs.length === 0) {
+      return 0;
+    }
+    log(`Found ${closedPairs.length} closed shadow root(s), exposing via CDP`);
+
+    // Phase 1: resolve every backendNodeId → objectId in parallel batches.
+    const resolved = [];
+    for (let i = 0; i < closedPairs.length; i += CDP_BATCH_SIZE) {
+      const slice = closedPairs.slice(i, i + CDP_BATCH_SIZE);
+      const out = await Promise.all(slice.map(async pair => {
+        try {
+          const [hostRes, shadowRes] = await Promise.all([cdp.send('DOM.resolveNode', {
+            backendNodeId: pair.hostBackendNodeId
+          }), cdp.send('DOM.resolveNode', {
+            backendNodeId: pair.shadowBackendNodeId
+          })]);
+          return {
+            hostObj: hostRes.object,
+            shadowObj: shadowRes.object,
+            pair
+          };
+        } catch (err) {
+          const msg = err && err.message ? err.message : err;
+          log(`Skipping a closed shadow pair: ${msg} (host=${pair.hostBackendNodeId}, shadow=${pair.shadowBackendNodeId})`);
+          return null;
+        }
+      }));
+      for (const entry of out) if (entry) resolved.push(entry);
+    }
+
+    // Phase 2: stamp the WeakMap (per-realm), also batched. Track real
+    // successes — earlier shapes returned closedPairs.length and overstated
+    // success when stamps failed.
+    let stamped = 0;
+    for (let i = 0; i < resolved.length; i += CDP_BATCH_SIZE) {
+      const slice = resolved.slice(i, i + CDP_BATCH_SIZE);
+      const results = await Promise.all(slice.map(({
+        hostObj,
+        shadowObj,
+        pair
+      }) => cdp.send('Runtime.callFunctionOn', {
+        functionDeclaration: STAMP_FUNCTION,
+        objectId: hostObj.objectId,
+        arguments: [{
+          objectId: shadowObj.objectId
+        }]
+      }).then(() => true).catch(err => {
+        const msg = err && err.message ? err.message : err;
+        log(`Skipping a closed shadow pair: ${msg} (host=${pair.hostBackendNodeId}, shadow=${pair.shadowBackendNodeId})`);
+        return false;
+      })));
+      for (const ok of results) if (ok) stamped++;
+    }
+    return stamped;
+  } catch (err) {
+    log(`Could not expose closed shadow roots via CDP: ${err && err.message ? err.message : err}`);
+    return -1;
+  } finally {
+    if (domEnabled) {
+      await cdp.send('DOM.disable').catch(disableErr => {
+        log(`DOM.disable failed during closed-shadow cleanup: ${disableErr && disableErr.message ? disableErr.message : disableErr}`);
+      });
+    }
+    delete cdp[IN_FLIGHT];
+  }
+}
+
+// Walk a DOM.getDocument tree (with pierce: true) collecting every
+// closed-shadow host/root pair we encounter. `pierce: true` traverses both
+// shadow boundaries and iframe `contentDocument` boundaries, so a single
+// walk reaches closed shadow hosts inside nested iframes. Recursion is
+// bounded at MAX_SHADOW_DEPTH levels — counted only across shadow/iframe
+// boundary crossings, not plain children — so a deep ordinary DOM doesn't
+// exhaust the budget before reaching its shadow hosts. Exported for tests.
+export function walkCDPNodes(node, pairs, depth = 0) {
+  if (!node || depth >= MAX_SHADOW_DEPTH) return;
+  if (node.shadowRoots) {
+    for (const sr of node.shadowRoots) {
+      if (sr.shadowRootType === 'closed') {
+        pairs.push({
+          hostBackendNodeId: node.backendNodeId,
+          shadowBackendNodeId: sr.backendNodeId
+        });
+      }
+      // crossing a shadow boundary — increment depth
+      walkCDPNodes(sr, pairs, depth + 1);
+    }
+  }
+  if (node.children) {
+    // plain children — same realm, same depth
+    for (const child of node.children) walkCDPNodes(child, pairs, depth);
+  }
+  // pierce: true surfaces iframe content documents on the iframe node;
+  // crossing into the iframe's realm — increment depth.
+  if (node.contentDocument) walkCDPNodes(node.contentDocument, pairs, depth + 1);
+}
+export default exposeClosedShadowRoots;

package/dist/config.js

@@ -151,6 +151,91 @@ export const configSchema = {
       sync: {
         type: 'boolean'
       },
+      readiness: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          preset: {
+            type: 'string',
+            enum: ['balanced', 'strict', 'fast', 'disabled']
+          },
+          stabilityWindowMs: {
+            type: 'integer',
+            minimum: 50,
+            maximum: 30000
+          },
+          jsIdleWindowMs: {
+            type: 'integer',
+            minimum: 50,
+            maximum: 30000
+          },
+          networkIdleWindowMs: {
+            type: 'integer',
+            minimum: 50,
+            maximum: 10000
+          },
+          timeoutMs: {
+            type: 'integer',
+            minimum: 1000,
+            maximum: 60000
+          },
+          domStability: {
+            type: 'boolean'
+          },
+          imageReady: {
+            type: 'boolean'
+          },
+          fontReady: {
+            type: 'boolean'
+          },
+          jsIdle: {
+            type: 'boolean'
+          },
+          readySelectors: {
+            type: 'array',
+            items: {
+              oneOf: [{
+                type: 'string'
+              }, {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  css: {
+                    type: 'string'
+                  },
+                  xpath: {
+                    type: 'string'
+                  }
+                }
+              }]
+            }
+          },
+          notPresentSelectors: {
+            type: 'array',
+            items: {
+              oneOf: [{
+                type: 'string'
+              }, {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  css: {
+                    type: 'string'
+                  },
+                  xpath: {
+                    type: 'string'
+                  }
+                }
+              }]
+            }
+          },
+          maxTimeoutMs: {
+            type: 'integer',
+            minimum: 1000,
+            maximum: 60000
+          }
+        }
+      },
       responsiveSnapshotCapture: {
         type: 'boolean',
         default: false
@@ -332,6 +417,14 @@ export const configSchema = {
         type: 'boolean',
         default: false
       },
+      ignoreIframeSelectors: {
+        type: 'array',
+        default: [],
+        items: {
+          type: 'string',
+          minLength: 1
+        }
+      },
       pseudoClassEnabledElements: {
         type: 'object',
         additionalProperties: false,
@@ -604,6 +697,9 @@ export const snapshotSchema = {
         sync: {
           $ref: '/config/snapshot#/properties/sync'
         },
+        readiness: {
+          $ref: '/config/snapshot#/properties/readiness'
+        },
         responsiveSnapshotCapture: {
           $ref: '/config/snapshot#/properties/responsiveSnapshotCapture'
         },
@@ -640,6 +736,9 @@ export const snapshotSchema = {
         ignoreStyleSheetSerializationErrors: {
           $ref: '/config/snapshot#/properties/ignoreStyleSheetSerializationErrors'
         },
+        ignoreIframeSelectors: {
+          $ref: '/config/snapshot#/properties/ignoreIframeSelectors'
+        },
         pseudoClassEnabledElements: {
           $ref: '/config/snapshot#/properties/pseudoClassEnabledElements'
         },
@@ -934,6 +1033,11 @@ export const snapshotSchema = {
                   type: 'string'
                 }
               },
+              readiness_diagnostics: {
+                type: 'object',
+                normalize: false,
+                description: 'Diagnostics from readiness checks run before serialization. ' + 'normalize: false preserves the snake_case wire format the SDKs send (timed_out, ' + 'total_duration_ms, etc.) instead of camelCasing inner keys at validate time.'
+              },
               corsIframes: {
                 type: 'array',
                 items: {

package/dist/page.js

@@ -1,8 +1,55 @@
 import fs from 'fs';
 import logger from '@percy/logger';
 import Network from './network.js';
+import { exposeClosedShadowRoots } from './closed-shadow.js';
 import { PERCY_DOM } from './api.js';
 import { hostname, waitFor, waitForTimeout as sleep, serializeFunction } from './utils.js';
+
+// Internal ceiling on the customElements wait. Set tight (500ms) so a
+// page with a never-registering custom element — third-party widget whose
+// loader is blocked, typo'd tag name, etc. — doesn't add a full 1500ms to
+// every snapshot. Real cascades of legitimate lazy-defined elements
+// complete well within this budget; the loop also exits early as soon as
+// `:not(:defined)` clears.
+export const DEFAULT_WAIT_FOR_CUSTOM_ELEMENTS_TIMEOUT = 500;
+
+// Body of the customElements wait. Runs in the browser via
+// Runtime.callFunctionOn. Re-polls each tick so lazy-defined element
+// cascades are awaited up to the deadline.
+//
+// IMPORTANT: this body is intentionally ES5 — it is evaluated in the
+// page's realm and must work in any browser the page targets. Don't
+// "modernize" with arrow functions, let/const, or optional chaining.
+export const WAIT_FOR_CUSTOM_ELEMENTS_BODY = `
+  var deadline = Date.now() + (arguments[0] || 500);
+  return new Promise(function(resolve) {
+    function tick() {
+      var undef = document.querySelectorAll(":not(:defined)");
+      if (!undef.length) return resolve();
+      if (Date.now() >= deadline) return resolve();
+      var names = {};
+      for (var i = 0; i < undef.length; i++) names[undef[i].localName] = true;
+      var promises = Object.keys(names).map(function(n) {
+        return window.customElements.whenDefined(n).catch(function(){});
+      });
+      Promise.race([
+        Promise.all(promises),
+        new Promise(function(r) { setTimeout(r, 100); })
+      ]).then(tick);
+    }
+    tick();
+  });
+`;
+
+/* istanbul ignore next: runs in the page realm via Runtime.callFunctionOn,
+   not in the test process — there is no way to instrument it from here */
+function serializeDomCapture(_, options) {
+  /* eslint-disable-next-line no-undef */
+  return {
+    domSnapshot: PercyDOM.serialize(options),
+    url: document.URL
+  };
+}
 export class Page {
   static TIMEOUT = undefined;
   log = logger('core:page');
@@ -185,6 +232,7 @@ export class Page {
     execute,
     ...snapshot
   }) {
+    var _this$browser;
     let {
       name,
       width,
@@ -195,6 +243,7 @@ export class Page {
       reshuffleInvalidTags,
       ignoreCanvasSerializationErrors,
       ignoreStyleSheetSerializationErrors,
+      ignoreIframeSelectors,
       pseudoClassEnabledElements
     } = snapshot;
     this.log.debug(`Taking snapshot: ${name}${width ? ` @${width}px` : ''}`, this.meta);
@@ -219,17 +268,49 @@ export class Page {
 
     // wait for any final network activity before capturing the dom snapshot
     await this.network.idle();
-    await this.insertPercyDom();
 
-    // serialize and capture a DOM snapshot
-    this.log.debug('Serialize DOM', this.meta);
+    // Pre-snapshot best-effort steps: waiting for lazy custom elements and
+    // discovering closed shadow roots via CDP. Both target a fully-loaded
+    // page; if the session has already terminated, skip them so the proper
+    // crash/close error surfaces from the downstream insertPercyDom +
+    // serialize evals (which gate on the same session).
+    //
+    // Ordering is load-bearing: closed-shadow capture must run AFTER the
+    // customElements wait so we catch shadows attached inside upgrade /
+    // connectedCallback hooks. Don't reorder or parallelise these.
+    if (!this.session.closedReason) {
+      // Best-effort: a flaky page should not break the snapshot.
+      try {
+        await this.eval(WAIT_FOR_CUSTOM_ELEMENTS_BODY, DEFAULT_WAIT_FOR_CUSTOM_ELEMENTS_TIMEOUT);
+      } catch (err) {
+        /* istanbul ignore next: best-effort log; defensive against non-Error throws */
+        this.log.debug(`Custom elements wait failed: ${err.message ?? err}`, this.meta);
+      }
+      if (!disableShadowDOM) {
+        await exposeClosedShadowRoots(this.session, this._logShadowDebug.bind(this));
+      }
+    }
+    await this.insertPercyDom();
 
-    /* istanbul ignore next: no instrumenting injected code */
-    let capture = await this.eval((_, options) => ({
-      /* eslint-disable-next-line no-undef */
-      domSnapshot: PercyDOM.serialize(options),
-      url: document.URL
-    }), {
+    // Run readiness checks before serializing — wait for page stability
+    let readiness = snapshot.readiness || ((_this$browser = this.browser) === null || _this$browser === void 0 || (_this$browser = _this$browser.percy) === null || _this$browser === void 0 || (_this$browser = _this$browser.config) === null || _this$browser === void 0 || (_this$browser = _this$browser.snapshot) === null || _this$browser === void 0 ? void 0 : _this$browser.readiness);
+    let readinessDiagnostics;
+    if (readiness && readiness.preset !== 'disabled') {
+      var _readinessDiagnostics;
+      this.log.debug('Waiting for readiness', this.meta);
+      readinessDiagnostics = await this.eval(/* istanbul ignore next: no instrumenting injected code */
+      async (_, config) => {
+        var _PercyDOM;
+        // eslint-disable-next-line no-undef
+        if (typeof ((_PercyDOM = PercyDOM) === null || _PercyDOM === void 0 ? void 0 : _PercyDOM.waitForReady) === 'function') return PercyDOM.waitForReady(config);
+      }, readiness).catch(e => {
+        this.log.debug(`Readiness check failed: ${e}`, this.meta);
+      });
+      if ((_readinessDiagnostics = readinessDiagnostics) !== null && _readinessDiagnostics !== void 0 && _readinessDiagnostics.timed_out) {
+        this.log.debug('Readiness timed out, capturing anyway', this.meta);
+      }
+    }
+    let capture = await this.eval(serializeDomCapture, {
       enableJavaScript,
       disableShadowDOM,
       forceShadowAsLightDOM,
@@ -237,14 +318,31 @@ export class Page {
       reshuffleInvalidTags,
       ignoreCanvasSerializationErrors,
       ignoreStyleSheetSerializationErrors,
+      ignoreIframeSelectors,
       pseudoClassEnabledElements
     });
+
+    // Attach readiness diagnostics onto the captured DOM snapshot so the backend/UI can surface
+    // readiness metrics. Only valid when domSnapshot is the structured object form — the legacy
+    // string form (HTML only) has no place to embed diagnostics.
+    if (readinessDiagnostics && capture !== null && capture !== void 0 && capture.domSnapshot && typeof capture.domSnapshot === 'object') {
+      capture.domSnapshot.readiness_diagnostics = readinessDiagnostics;
+    }
     return {
       ...snapshot,
       ...capture
     };
   }
 
+  // Logger for the closed-shadow CDP helper. Defined on the prototype (not
+  // a class-field arrow) so it's reachable from a unit test that constructs
+  // a Page via Object.create without invoking the constructor — gives us a
+  // direct way to cover the callback without simulating a closed shadow
+  // discovery flow at the integration level.
+  _logShadowDebug(msg) {
+    this.log.debug(msg, this.meta);
+  }
+
   // Initialize newly attached pages and iframes with page options
   _handleAttachedToTarget = event => {
     let session = !event ? this.session : this.session.children.get(event.sessionId);

package/dist/snapshot.js

@@ -231,6 +231,27 @@ export function validateSnapshotOptions(options) {
     log.warn('Encountered snapshot serialization warnings:');
     for (let w of domWarnings) log.warn(`- ${w}`);
   }
+
+  // log readiness diagnostics when present.
+  // domSnapshot is a union of `string` (legacy SDK payload — HTML only) and `object`
+  // ({ html, warnings, readiness_diagnostics, ... }). Diagnostics only exist on the object form;
+  // gate explicitly on typeof so the intent is obvious to readers.
+  // The schema marks readiness_diagnostics with normalize: false to preserve the snake_case wire
+  // format. The dual-read fallback below is defensive — it keeps the log working even if a future
+  // SDK sends camelCase keys, or if a path in PercyConfig.migrate skips the normalize: false hint.
+  let domSnapshotObj = migrated.domSnapshot && typeof migrated.domSnapshot === 'object' ? migrated.domSnapshot : null;
+  let readinessDiag = (domSnapshotObj === null || domSnapshotObj === void 0 ? void 0 : domSnapshotObj.readiness_diagnostics) ?? (domSnapshotObj === null || domSnapshotObj === void 0 ? void 0 : domSnapshotObj.readinessDiagnostics);
+  if (readinessDiag) {
+    let timedOut = readinessDiag.timed_out ?? readinessDiag.timedOut;
+    let durationMs = readinessDiag.total_duration_ms ?? readinessDiag.totalDurationMs;
+    let presetName = readinessDiag.preset || 'custom';
+    if (timedOut) {
+      log.warn(`Readiness timed out after ${durationMs}ms (preset: ${presetName})`);
+    } else {
+      log.debug(`Readiness passed in ${durationMs}ms (preset: ${presetName})`);
+    }
+  }
+
   // warn on validation errors
   let errors = PercyConfig.validate(migrated, schema);
   if ((errors === null || errors === void 0 ? void 0 : errors.length) > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/core",
-  "version": "1.31.14-beta.2",
+  "version": "1.31.14-beta.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -44,12 +44,12 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.31.14-beta.2",
-    "@percy/config": "1.31.14-beta.2",
-    "@percy/dom": "1.31.14-beta.2",
-    "@percy/logger": "1.31.14-beta.2",
-    "@percy/monitoring": "1.31.14-beta.2",
-    "@percy/webdriver-utils": "1.31.14-beta.2",
+    "@percy/client": "1.31.14-beta.4",
+    "@percy/config": "1.31.14-beta.4",
+    "@percy/dom": "1.31.14-beta.4",
+    "@percy/logger": "1.31.14-beta.4",
+    "@percy/monitoring": "1.31.14-beta.4",
+    "@percy/webdriver-utils": "1.31.14-beta.4",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
@@ -63,7 +63,7 @@
     "yaml": "^2.4.1"
   },
   "optionalDependencies": {
-    "@percy/cli-doctor": "1.31.14-beta.2"
+    "@percy/cli-doctor": "1.31.14-beta.4"
   },
-  "gitHead": "e4fce73023453b77cdef50aac1a9bd5eb70cd01a"
+  "gitHead": "b52f1d2fb6272c0b3694e1e9ff584c5622a118c7"
 }