feat: Readiness gate in PercyDOM.serialize() — works for URL + SDK paths (PER-7348)

packages/core/src/config.js

@@ -132,6 +132,23 @@ 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 },
+          imageReady: { type: 'boolean' },
+          fontReady: { type: 'boolean' },
+          jsIdle: { type: 'boolean' },
+          readySelectors: { type: 'array', items: { type: 'string' } },
+          notPresentSelectors: { type: 'array', items: { type: 'string' } },
+          maxTimeoutMs: { type: 'integer', minimum: 1000, maximum: 60000 }
+        }
+      },
       responsiveSnapshotCapture: {
         type: 'boolean',
         default: false
@@ -489,6 +506,7 @@ export const snapshotSchema = {
         domTransformation: { $ref: '/config/snapshot#/properties/domTransformation' },
         enableLayout: { $ref: '/config/snapshot#/properties/enableLayout' },
         sync: { $ref: '/config/snapshot#/properties/sync' },
+        readiness: { $ref: '/config/snapshot#/properties/readiness' },
         responsiveSnapshotCapture: { $ref: '/config/snapshot#/properties/responsiveSnapshotCapture' },
         testCase: { $ref: '/config/snapshot#/properties/testCase' },
         labels: { $ref: '/config/snapshot#/properties/labels' },
@@ -682,6 +700,10 @@ export const snapshotSchema = {
                 type: 'array',
                 items: { type: 'string' }
               },
+              readiness_diagnostics: {
+                type: 'object',
+                description: 'Diagnostics from readiness checks run before serialization'
+              },
               corsIframes: {
                 type: 'array',
                 items: {

packages/core/src/page.js

@@ -213,15 +213,31 @@ 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?.percy?.config?.snapshot?.readiness;
+
+    if (readiness && readiness.preset !== 'disabled') {
+      this.log.debug('Waiting for readiness', this.meta);
+      /* istanbul ignore next: no instrumenting injected code */
+      let diagnostics = await this.eval(async (_, config) => {
+        // eslint-disable-next-line no-undef
+        if (typeof PercyDOM?.waitForReady === 'function') return PercyDOM.waitForReady(config);
+      }, readiness).catch(e => {
+        this.log.debug(`Readiness check failed: ${e}`, this.meta);
+      });
+
+      if (diagnostics?.timed_out) {
+        this.log.debug('Readiness timed out, capturing anyway', this.meta);
+      }
+    }
 
+    // Serialize the DOM — always sync
+    this.log.debug('Serialize DOM', this.meta);
     /* istanbul ignore next: no instrumenting injected code */
-    let capture = await this.eval((_, options) => ({
+    let capture = await this.eval((_, options) => {
       /* eslint-disable-next-line no-undef */
-      domSnapshot: PercyDOM.serialize(options),
-      url: document.URL
-    }), { enableJavaScript, disableShadowDOM, forceShadowAsLightDOM, domTransformation, reshuffleInvalidTags, ignoreCanvasSerializationErrors, ignoreStyleSheetSerializationErrors, pseudoClassEnabledElements });
+      return { domSnapshot: PercyDOM.serialize(options), url: document.URL };
+    }, { enableJavaScript, disableShadowDOM, forceShadowAsLightDOM, domTransformation, reshuffleInvalidTags, ignoreCanvasSerializationErrors, ignoreStyleSheetSerializationErrors, pseudoClassEnabledElements });
 
     return { ...snapshot, ...capture };
   }

packages/core/src/snapshot.js

@@ -220,6 +220,17 @@ export function validateSnapshotOptions(options) {
     log.warn('Encountered snapshot serialization warnings:');
     for (let w of domWarnings) log.warn(`- ${w}`);
   }
+
+  // log readiness diagnostics when present (SDK-submitted snapshots with readiness enabled)
+  let readinessDiag = migrated.domSnapshot?.readiness_diagnostics;
+  if (readinessDiag) {
+    if (readinessDiag.timed_out) {
+      log.warn(`Readiness timed out after ${readinessDiag.total_duration_ms}ms (preset: ${readinessDiag.preset || 'custom'})`);
+    } else {
+      log.debug(`Readiness passed in ${readinessDiag.total_duration_ms}ms (preset: ${readinessDiag.preset || 'custom'})`);
+    }
+  }
+
   // warn on validation errors
   let errors = PercyConfig.validate(migrated, schema);
   if (errors?.length > 0) {

packages/core/test/percy.test.js

@@ -110,6 +110,7 @@ describe('Percy', () => {
     });
 
     // expect required arguments are passed to PercyDOM.serialize
+    // readiness is now a separate waitForReady call, not part of serialize options
     expect(evalSpy.calls.allArgs()[3]).toEqual(jasmine.arrayContaining([jasmine.anything(), { enableJavaScript: undefined, disableShadowDOM: true, domTransformation: undefined, reshuffleInvalidTags: undefined, ignoreCanvasSerializationErrors: undefined, ignoreStyleSheetSerializationErrors: undefined, forceShadowAsLightDOM: undefined, pseudoClassEnabledElements: undefined }]));
 
     expect(snapshot.url).toEqual('http://localhost:8000/');
@@ -120,6 +121,95 @@ describe('Percy', () => {
     }));
   });
 
+  it('runs readiness check before serializing when readiness option is set', async () => {
+    server.reply('/', () => [200, 'text/html', '<p>Hello Percy!</p>']);
+
+    await percy.browser.launch();
+    let page = await percy.browser.page();
+    await page.goto('http://localhost:8000');
+
+    percy.loglevel('debug');
+
+    let snapshot = await page.snapshot({
+      readiness: { preset: 'fast', timeoutMs: 1000 }
+    });
+
+    expect(logger.stderr).toEqual(jasmine.arrayContaining([
+      jasmine.stringMatching(/Waiting for readiness/)
+    ]));
+    expect(snapshot.url).toEqual('http://localhost:8000/');
+  });
+
+  it('skips readiness check when readiness preset is disabled', async () => {
+    server.reply('/', () => [200, 'text/html', '<p>Hello Percy!</p>']);
+
+    await percy.browser.launch();
+    let page = await percy.browser.page();
+    await page.goto('http://localhost:8000');
+
+    percy.loglevel('debug');
+
+    let snapshot = await page.snapshot({
+      readiness: { preset: 'disabled' }
+    });
+
+    expect(logger.stderr).not.toEqual(jasmine.arrayContaining([
+      jasmine.stringMatching(/Waiting for readiness/)
+    ]));
+    expect(snapshot.url).toEqual('http://localhost:8000/');
+  });
+
+  it('logs when readiness times out and continues to capture', async () => {
+    server.reply('/', () => [200, 'text/html', '<p>Hello Percy!</p>']);
+
+    await percy.browser.launch();
+    let page = await percy.browser.page();
+    await page.goto('http://localhost:8000');
+
+    percy.loglevel('debug');
+
+    // Force the readiness eval to resolve with a timed_out diagnostics
+    // payload while letting all other eval calls (PercyDOM injection,
+    // serialize, etc.) pass through untouched. The readiness eval is the
+    // only call whose first arg is a config object containing `preset`.
+    let originalEval = page.eval.bind(page);
+    spyOn(page, 'eval').and.callFake((fn, ...args) => {
+      if (args[0] && typeof args[0] === 'object' && 'preset' in args[0]) {
+        return Promise.resolve({ timed_out: true, total_duration_ms: 1234 });
+      }
+      return originalEval(fn, ...args);
+    });
+
+    let snapshot = await page.snapshot({
+      readiness: { preset: 'balanced' }
+    });
+
+    expect(logger.stderr).toEqual(jasmine.arrayContaining([
+      jasmine.stringMatching(/Waiting for readiness/),
+      jasmine.stringMatching(/Readiness timed out, capturing anyway/)
+    ]));
+    expect(snapshot.url).toEqual('http://localhost:8000/');
+  });
+
+  it('falls back to the percy config readiness when none is set per snapshot', async () => {
+    server.reply('/', () => [200, 'text/html', '<p>Hello Percy!</p>']);
+
+    percy.config.snapshot.readiness = { preset: 'fast', timeoutMs: 1000 };
+
+    await percy.browser.launch();
+    let page = await percy.browser.page();
+    await page.goto('http://localhost:8000');
+
+    percy.loglevel('debug');
+
+    let snapshot = await page.snapshot({});
+
+    expect(logger.stderr).toEqual(jasmine.arrayContaining([
+      jasmine.stringMatching(/Waiting for readiness/)
+    ]));
+    expect(snapshot.url).toEqual('http://localhost:8000/');
+  });
+
   describe('.start()', () => {
     // rather than stub prototypes, extend and mock
     class TestPercy extends Percy {

packages/core/test/snapshot.test.js

@@ -1036,6 +1036,68 @@ describe('Snapshot', () => {
     expect(uploads[2]).toEqual(Buffer.from(textResource.content).toString('base64'));
   });
 
+  it('warns when readiness diagnostics indicate a timeout', async () => {
+    // domSnapshot is sent as a JSON string by SDKs, which preserves snake_case
+    // keys like readiness_diagnostics through option normalization.
+    await percy.snapshot({
+      name: 'Readiness Timed Out',
+      url: 'http://localhost:8000/',
+      domSnapshot: JSON.stringify({
+        html: testDOM,
+        readiness_diagnostics: {
+          timed_out: true,
+          total_duration_ms: 12345,
+          preset: 'balanced'
+        }
+      })
+    });
+
+    expect(logger.stderr).toEqual(jasmine.arrayContaining([
+      '[percy] Readiness timed out after 12345ms (preset: balanced)'
+    ]));
+    expect(logger.stdout).toEqual(jasmine.arrayContaining([
+      '[percy] Snapshot taken: Readiness Timed Out'
+    ]));
+  });
+
+  it('falls back to "custom" preset label when readiness timeout omits the preset', async () => {
+    await percy.snapshot({
+      name: 'Readiness Timed Out Custom',
+      url: 'http://localhost:8000/',
+      domSnapshot: JSON.stringify({
+        html: testDOM,
+        readiness_diagnostics: {
+          timed_out: true,
+          total_duration_ms: 9999
+        }
+      })
+    });
+
+    expect(logger.stderr).toEqual(jasmine.arrayContaining([
+      '[percy] Readiness timed out after 9999ms (preset: custom)'
+    ]));
+  });
+
+  it('debug logs readiness diagnostics when readiness passes', async () => {
+    percy.loglevel('debug');
+
+    await percy.snapshot({
+      name: 'Readiness Passed',
+      url: 'http://localhost:8000/',
+      domSnapshot: JSON.stringify({
+        html: testDOM,
+        readiness_diagnostics: {
+          timed_out: false,
+          total_duration_ms: 250
+        }
+      })
+    });
+
+    expect(logger.stderr).toEqual(jasmine.arrayContaining([
+      '[percy:core:snapshot] Readiness passed in 250ms (preset: custom)'
+    ]));
+  });
+
   it('handles duplicate snapshots when testCase is not passed', async () => {
     await percy.snapshot([{
       url: 'http://localhost:8000/foobar',

packages/dom/src/index.js

@@ -7,3 +7,5 @@ export {
 } from './serialize-dom';
 
 export { loadAllSrcsetLinks } from './serialize-image-srcset';
+
+export { waitForReady } from './readiness';