@percy/sdk-utils 1.31.15-alpha.0 → 1.31.15-beta.0

package/dist/bundle.js

@@ -327,11 +327,21 @@
     }
 
     // Returns the readiness config for a snapshot.
-    // Priority: per-snapshot options > global percy.config > empty object (triggers balanced default).
+    // Shallow-merge of global .percy.yml config with per-snapshot overrides:
+    // per-snapshot keys win, unspecified keys are inherited from the global config.
     // SDKs obtain percy.config via the healthcheck endpoint in isPercyEnabled().
+    //
+    // Why shallow-merge instead of `||`:
+    //   - `options.readiness = {}` would otherwise wipe the global config entirely.
+    //   - A partial per-snapshot override like `{ stabilityWindowMs: 500 }` would
+    //     drop a global `preset: disabled` kill switch — silently re-enabling the
+    //     gate for a snapshot the user thought was opted out.
     function getReadinessConfig(snapshotOptions = {}) {
       var _percy$config;
-      return (snapshotOptions === null || snapshotOptions === void 0 ? void 0 : snapshotOptions.readiness) || ((_percy$config = info.config) === null || _percy$config === void 0 || (_percy$config = _percy$config.snapshot) === null || _percy$config === void 0 ? void 0 : _percy$config.readiness) || {};
+      return {
+        ...(((_percy$config = info.config) === null || _percy$config === void 0 || (_percy$config = _percy$config.snapshot) === null || _percy$config === void 0 ? void 0 : _percy$config.readiness) || {}),
+        ...((snapshotOptions === null || snapshotOptions === void 0 ? void 0 : snapshotOptions.readiness) || {})
+      };
     }
 
     // Returns true if readiness should be skipped for this snapshot.
@@ -390,6 +400,54 @@
     `;
     }
 
+    // Runs the readiness gate end-to-end so every JS SDK collapses to a single
+    // call. The SDK's only responsibility is to provide an `evalScript` callback
+    // that ships the script string to the browser via its driver's evaluator
+    // (page.evaluate, driver.executeAsyncScript, b.executeAsync, etc.).
+    //
+    // Centralised here:
+    //   - isReadinessDisabled kill-switch check
+    //   - getReadinessConfig shallow-merge of global + per-snapshot config
+    //   - waitForReadyScript script generation (callback or promise mode)
+    //   - try/catch with debug logging — serialize is never blocked
+    //
+    // Returns: the diagnostics object from PercyDOM.waitForReady, or null
+    // when readiness is disabled / unavailable / failed. The caller attaches
+    // the non-null result to domSnapshot.readiness_diagnostics.
+    //
+    // Usage:
+    //   // Puppeteer/Playwright (promise-mode):
+    //   const diag = await utils.runReadinessGate(
+    //     (script) => page.evaluate(script),
+    //     options,
+    //     { log }
+    //   );
+    //
+    //   // Selenium-js / WebdriverIO / Nightwatch (callback-mode):
+    //   const diag = await utils.runReadinessGate(
+    //     (script) => driver.executeAsyncScript(script),
+    //     options,
+    //     { callback: true, log }
+    //   );
+    async function runReadinessGate(evalScript, snapshotOptions = {}, {
+      callback = false,
+      log
+    } = {}) {
+      if (isReadinessDisabled(snapshotOptions)) return null;
+      const config = getReadinessConfig(snapshotOptions);
+      const script = waitForReadyScript(config, {
+        callback
+      });
+      try {
+        return await evalScript(script);
+      } catch (err) {
+        if (log && typeof log.debug === 'function') {
+          log.debug(`waitForReady failed, proceeding to serialize: ${(err === null || err === void 0 ? void 0 : err.message) || err}`);
+        }
+        return null;
+      }
+    }
+
     // Iframe depth constants shared with @percy/dom's serialize-frames. Kept
     // here so external Percy SDKs (Capybara, Cypress, Playwright, etc.) can
     // clamp their own pre-CLI configuration to the same bounds the CLI enforces.
@@ -426,6 +484,7 @@
       waitForReadyScript: waitForReadyScript,
       getReadinessConfig: getReadinessConfig,
       isReadinessDisabled: isReadinessDisabled,
+      runReadinessGate: runReadinessGate,
       'default': index
     });
 
@@ -446,6 +505,7 @@
     exports.postComparison = postComparison;
     exports.postSnapshot = postSnapshot;
     exports.request = request;
+    exports.runReadinessGate = runReadinessGate;
     exports.waitForPercyIdle = waitForPercyIdle;
     exports.waitForReadyScript = waitForReadyScript;
 

package/dist/index.js

@@ -84,6 +84,12 @@ Object.defineProperty(exports, "request", {
     return _request.default;
   }
 });
+Object.defineProperty(exports, "runReadinessGate", {
+  enumerable: true,
+  get: function () {
+    return _serializeDom.runReadinessGate;
+  }
+});
 Object.defineProperty(exports, "waitForPercyIdle", {
   enumerable: true,
   get: function () {

package/dist/serialize-dom.js

@@ -6,15 +6,26 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 exports.getReadinessConfig = getReadinessConfig;
 exports.isReadinessDisabled = isReadinessDisabled;
+exports.runReadinessGate = runReadinessGate;
 exports.waitForReadyScript = waitForReadyScript;
 var _percyInfo = _interopRequireDefault(require("./percy-info.js"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 // Returns the readiness config for a snapshot.
-// Priority: per-snapshot options > global percy.config > empty object (triggers balanced default).
+// Shallow-merge of global .percy.yml config with per-snapshot overrides:
+// per-snapshot keys win, unspecified keys are inherited from the global config.
 // SDKs obtain percy.config via the healthcheck endpoint in isPercyEnabled().
+//
+// Why shallow-merge instead of `||`:
+//   - `options.readiness = {}` would otherwise wipe the global config entirely.
+//   - A partial per-snapshot override like `{ stabilityWindowMs: 500 }` would
+//     drop a global `preset: disabled` kill switch — silently re-enabling the
+//     gate for a snapshot the user thought was opted out.
 function getReadinessConfig(snapshotOptions = {}) {
   var _percy$config;
-  return (snapshotOptions === null || snapshotOptions === void 0 ? void 0 : snapshotOptions.readiness) || ((_percy$config = _percyInfo.default.config) === null || _percy$config === void 0 || (_percy$config = _percy$config.snapshot) === null || _percy$config === void 0 ? void 0 : _percy$config.readiness) || {};
+  return {
+    ...(((_percy$config = _percyInfo.default.config) === null || _percy$config === void 0 || (_percy$config = _percy$config.snapshot) === null || _percy$config === void 0 ? void 0 : _percy$config.readiness) || {}),
+    ...((snapshotOptions === null || snapshotOptions === void 0 ? void 0 : snapshotOptions.readiness) || {})
+  };
 }
 
 // Returns true if readiness should be skipped for this snapshot.
@@ -72,4 +83,52 @@ function waitForReadyScript(readinessConfig = {}, {
     }
   `;
 }
+
+// Runs the readiness gate end-to-end so every JS SDK collapses to a single
+// call. The SDK's only responsibility is to provide an `evalScript` callback
+// that ships the script string to the browser via its driver's evaluator
+// (page.evaluate, driver.executeAsyncScript, b.executeAsync, etc.).
+//
+// Centralised here:
+//   - isReadinessDisabled kill-switch check
+//   - getReadinessConfig shallow-merge of global + per-snapshot config
+//   - waitForReadyScript script generation (callback or promise mode)
+//   - try/catch with debug logging — serialize is never blocked
+//
+// Returns: the diagnostics object from PercyDOM.waitForReady, or null
+// when readiness is disabled / unavailable / failed. The caller attaches
+// the non-null result to domSnapshot.readiness_diagnostics.
+//
+// Usage:
+//   // Puppeteer/Playwright (promise-mode):
+//   const diag = await utils.runReadinessGate(
+//     (script) => page.evaluate(script),
+//     options,
+//     { log }
+//   );
+//
+//   // Selenium-js / WebdriverIO / Nightwatch (callback-mode):
+//   const diag = await utils.runReadinessGate(
+//     (script) => driver.executeAsyncScript(script),
+//     options,
+//     { callback: true, log }
+//   );
+async function runReadinessGate(evalScript, snapshotOptions = {}, {
+  callback = false,
+  log
+} = {}) {
+  if (isReadinessDisabled(snapshotOptions)) return null;
+  const config = getReadinessConfig(snapshotOptions);
+  const script = waitForReadyScript(config, {
+    callback
+  });
+  try {
+    return await evalScript(script);
+  } catch (err) {
+    if (log && typeof log.debug === 'function') {
+      log.debug(`waitForReady failed, proceeding to serialize: ${(err === null || err === void 0 ? void 0 : err.message) || err}`);
+    }
+    return null;
+  }
+}
 var _default = exports.default = waitForReadyScript;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/sdk-utils",
-  "version": "1.31.15-alpha.0",
+  "version": "1.31.15-beta.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,7 +9,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "alpha"
+    "tag": "beta"
   },
   "engines": {
     "node": ">=14"
@@ -54,5 +54,5 @@
   "dependencies": {
     "pac-proxy-agent": "^7.0.2"
   },
-  "gitHead": "726ab78fcd37479a0904996a88400a0b6626daac"
+  "gitHead": "b2012ce5dae37e5009dd3f4190454bb9d9d118e3"
 }