@percy/core 1.31.14-beta.3 → 1.31.14-beta.5

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
@@ -612,6 +697,9 @@ export const snapshotSchema = {
         sync: {
           $ref: '/config/snapshot#/properties/sync'
         },
+        readiness: {
+          $ref: '/config/snapshot#/properties/readiness'
+        },
         responsiveSnapshotCapture: {
           $ref: '/config/snapshot#/properties/responsiveSnapshotCapture'
         },
@@ -945,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

@@ -232,6 +232,7 @@ export class Page {
     execute,
     ...snapshot
   }) {
+    var _this$browser;
     let {
       name,
       width,
@@ -291,8 +292,24 @@ export class Page {
     }
     await this.insertPercyDom();
 
-    // serialize and capture a DOM snapshot
-    this.log.debug('Serialize DOM', this.meta);
+    // 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,
@@ -304,6 +321,13 @@ export class Page {
       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

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.3",
+  "version": "1.31.14-beta.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -44,12 +44,12 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.31.14-beta.3",
-    "@percy/config": "1.31.14-beta.3",
-    "@percy/dom": "1.31.14-beta.3",
-    "@percy/logger": "1.31.14-beta.3",
-    "@percy/monitoring": "1.31.14-beta.3",
-    "@percy/webdriver-utils": "1.31.14-beta.3",
+    "@percy/client": "1.31.14-beta.5",
+    "@percy/config": "1.31.14-beta.5",
+    "@percy/dom": "1.31.14-beta.5",
+    "@percy/logger": "1.31.14-beta.5",
+    "@percy/monitoring": "1.31.14-beta.5",
+    "@percy/webdriver-utils": "1.31.14-beta.5",
     "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.3"
+    "@percy/cli-doctor": "1.31.14-beta.5"
   },
-  "gitHead": "a17d4a1453c6bef282fd3da38082b670e125a5be"
+  "gitHead": "5a92d9e34d219d2c9a46d74a020de81814973370"
 }