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

package/commands/percySnapshot.js

@@ -1,7 +1,7 @@
 // Collect client and environment information
 const sdkPkg = require('../package.json');
 const nightwatchPkg = require('nightwatch/package.json');
-const { captureDOM } = require('../lib/snapshot');
+const { captureDOM, waitForReady } = require('../lib/snapshot');
 const { createRegion } = require('../lib/regions');
 const CLIENT_INFO = `${sdkPkg.name}/${sdkPkg.version}`;
 const ENV_INFO = `${nightwatchPkg.name}/${nightwatchPkg.version}`;
@@ -43,9 +43,17 @@ module.exports = class PercySnapshotCommand {
       // Inject the DOM serialization script
       await injectPercyDOM(this.api, domScript);
 
+      // 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);
 
+      // Attach readiness diagnostics so the CLI can log timing and pass/fail
+      if (readinessDiagnostics && domSnapshot && typeof domSnapshot === 'object' && !Array.isArray(domSnapshot)) {
+        domSnapshot.readiness_diagnostics = readinessDiagnostics;
+      }
+
       // Filter out DOM-only serialization options that shouldn't be posted to Percy
       const {
         ignoreCanvasSerializationErrors,

package/lib/snapshot.js

@@ -41,6 +41,51 @@ function executeScript(browser, fn, args = []) {
   });
 }
 
+function executeAsyncScript(browser, fn, args = []) {
+  return new Promise((resolve, reject) => {
+    try {
+      const cb = result => {
+        let value = unwrapResult(result);
+        if (result && result.status && result.status !== 0 && result.error) {
+          return reject(result.error);
+        }
+        resolve(value);
+      };
+
+      if (typeof browser.executeAsync === 'function') {
+        browser.executeAsync(fn, args, cb);
+      } else if (typeof browser.executeAsyncScript === 'function') {
+        browser.executeAsyncScript(fn, args, cb);
+      } else {
+        resolve(undefined);
+      }
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+// Readiness gate. Runs *before* serialize when CLI exposes
+// PercyDOM.waitForReady. Falls back silently on older CLI builds and never
+// blocks snapshot capture. Uses sdk-utils.waitForReadyScript({ callback: true })
+// as the shared in-browser invoker — uses `arguments[arguments.length - 1]`
+// for the executeAsync done callback.
+async function waitForReady(browser, options = {}, utils, log) {
+  // All readiness orchestration (disabled check + shallow-merge config +
+  // callback-mode script generation + try/catch) lives in @percy/sdk-utils
+  // 1.31.15+ as runReadinessGate. Degrade to no-op when the helper is
+  // absent — same behaviour as an old CLI without PercyDOM.waitForReady.
+  if (typeof utils?.runReadinessGate !== 'function') return undefined;
+  const result = await utils.runReadinessGate(
+    (script) => executeAsyncScript(browser, script),
+    options,
+    { callback: true, log }
+  );
+  // sdk-utils returns null on no-op / failure; nightwatch's contract is
+  // `undefined`, so normalise.
+  return result == null ? undefined : result;
+}
+
 function getCookies(browser) {
   if (typeof browser.getCookies !== 'function') return Promise.resolve([]);
   return new Promise((resolve, reject) => {
@@ -357,5 +402,6 @@ module.exports = {
   captureDOM,
   slowScrollToBottom,
   ignoreCanvasSerializationErrors,
-  ignoreStyleSheetSerializationErrors
+  ignoreStyleSheetSerializationErrors,
+  waitForReady
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@percy/nightwatch",
   "description": "Nightwatch client library for visual testing with Percy",
-  "version": "2.2.0-beta.0",
+  "version": "2.2.1-beta.0",
   "license": "MIT",
   "author": "Perceptual Inc.",
   "repository": "https://github.com/percy/percy-nightwatch",
@@ -29,7 +29,7 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/sdk-utils": "^1.31.4",
+    "@percy/sdk-utils": "^1.31.15-beta.0",
     "@percy/selenium-webdriver": "^2.2.3"
   },
   "peerDependencies": {