feat: PER-7348 add waitForReady() call before serialize()

Shivanshu-07 · claude · Shivanshu-07 · commit c36e4d3a197a · 2026-04-17T18:02:14.000+05:30
Adds the readiness gate from percy/cli#2184 to percySnapshot. The SDK now calls PercyDOM.waitForReady() with readiness config (from per-snapshot options or utils.percy.config.snapshot.readiness) before the existing PercyDOM.serialize() call. The serialize call itself is unchanged. Backward compat: typeof guard on PercyDOM.waitForReady means older CLI versions that lack the method skip the readiness step entirely. Graceful degradation: a rejected/thrown waitForReady is logged at debug level and serialize still runs. Disabled preset: { readiness: { preset: 'disabled' } } in snapshot options or config skips the readiness call. Tests cover happy path, backward compat (no waitForReady), disabled preset, and waitForReady rejection. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/cypress/e2e/index.cy.js b/cypress/e2e/index.cy.js
@@ -407,6 +407,74 @@ describe('percySnapshot', () => {
     });
   });
 
+  describe('readiness gate (PER-7348)', () => {
+    // Pre-populate window.PercyDOM so the SDK's `injectPercyDOM` early-returns
+    // and leaves our stub in place. This lets us observe how the SDK interacts
+    // with waitForReady / serialize.
+    const installPercyDOMStub = (stub) => {
+      cy.window().then((win) => {
+        win.PercyDOM = stub;
+      });
+    };
+
+    it('calls waitForReady before serialize when the CLI exposes it', () => {
+      const calls = [];
+      installPercyDOMStub({
+        waitForReady: (cfg) => { calls.push(['waitForReady', cfg]); return Promise.resolve(); },
+        serialize: (opts) => { calls.push(['serialize', opts]); return { html: { html: '<html></html>' } }; }
+      });
+
+      cy.percySnapshot('readiness-happy-path');
+
+      cy.then(() => {
+        const order = calls.map(([name]) => name);
+        expect(order.indexOf('waitForReady')).to.be.lessThan(order.indexOf('serialize'));
+      });
+    });
+
+    it('skips waitForReady when the CLI is old (function is absent)', () => {
+      const calls = [];
+      // No waitForReady — simulating an older CLI. serialize must still run.
+      installPercyDOMStub({
+        serialize: (opts) => { calls.push(['serialize', opts]); return { html: { html: '<html></html>' } }; }
+      });
+
+      cy.percySnapshot('readiness-backward-compat');
+
+      cy.then(() => {
+        expect(calls.map(([name]) => name)).to.deep.equal(['serialize']);
+      });
+    });
+
+    it('skips waitForReady when preset is disabled', () => {
+      const calls = [];
+      installPercyDOMStub({
+        waitForReady: (cfg) => { calls.push(['waitForReady', cfg]); return Promise.resolve(); },
+        serialize: (opts) => { calls.push(['serialize', opts]); return { html: { html: '<html></html>' } }; }
+      });
+
+      cy.percySnapshot('readiness-disabled', { readiness: { preset: 'disabled' } });
+
+      cy.then(() => {
+        expect(calls.map(([name]) => name)).to.deep.equal(['serialize']);
+      });
+    });
+
+    it('proceeds to serialize when waitForReady rejects', () => {
+      const calls = [];
+      installPercyDOMStub({
+        waitForReady: () => { calls.push(['waitForReady']); return Promise.reject(new Error('readiness failed')); },
+        serialize: (opts) => { calls.push(['serialize', opts]); return { html: { html: '<html></html>' } }; }
+      });
+
+      cy.percySnapshot('readiness-rejection');
+
+      cy.then(() => {
+        expect(calls.map(([name]) => name)).to.deep.equal(['waitForReady', 'serialize']);
+      });
+    });
+  });
+
   describe('createRegion function', () => {
     it('creates a region object with default values', () => {
       const region = createRegion();
diff --git a/index.js b/index.js
@@ -247,6 +247,17 @@ Cypress.Commands.add('percySnapshot', (name, options = {}) => {
 
         injectPercyDOM(_percyDOMScript);
 
+        // Readiness gate — runs before serialize when CLI supports it (PER-7348).
+        // Uses typeof guard for backward compat with older CLI that lacks waitForReady.
+        const readinessConfig = options.readiness || utils.percy?.config?.snapshot?.readiness || {};
+        if (readinessConfig.preset !== 'disabled' && typeof window.PercyDOM?.waitForReady === 'function') {
+          try {
+            await window.PercyDOM.waitForReady(readinessConfig);
+          } catch (e) {
+            log.debug(`waitForReady failed, proceeding to serialize: ${e?.message || e}`);
+          }
+        }
+
         const domSnapshot = window.PercyDOM.serialize({ ...options, dom: doc });
         if (width !== null) domSnapshot.width = width;
 
