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

[Shivanshu-07]

Summary

Adds readiness-gated snapshot capture to this SDK (PER-7348). Before serializing the DOM, the SDK now calls PercyDOM.waitForReady(config) to ensure the page is stable — no skeleton screens, fonts loaded, network idle, JavaScript settled.

Architecture: Two-Call Pattern

Step 1: PercyDOM.waitForReady(config)  — async, waits for page stability
Step 2: PercyDOM.serialize(options)    — sync, captures the stable DOM (unchanged)

• serialize() stays synchronous — zero breakage
• Readiness is a separate async call that runs before serialize
• Diagnostics from waitForReady() are captured and attached to domSnapshot.readiness_diagnostics so the CLI can log timing and pass/fail

Backward compatibility

Scenario	Behavior
This SDK + old CLI	typeof PercyDOM.waitForReady === 'function' is false — skips readiness. serialize() works as today.
This SDK + new CLI	waitForReady() runs, page stabilizes, diagnostics attached, serialize() captures stable DOM.
waitForReady throws	Caught, logged at debug level, serialize() still runs.
waitForReady times out	Resolves with { timed_out: true }, serialize() still runs.

Readiness config

Readiness config flows from .percy.yml through the CLI healthcheck to the SDK:

# .percy.yml
snapshot:
  readiness:
    preset: balanced  # balanced | strict | fast | disabled
    stabilityWindowMs: 300
    networkIdleWindowMs: 200
    timeoutMs: 10000

Per-snapshot overrides: percySnapshot('name', { readiness: { preset: 'strict' } })

Disable globally: readiness: { preset: disabled }

Test plan

• Readiness runs before serialize when enabled
• Readiness config from snapshot options is passed through
• Readiness skipped when preset: disabled
• Serialize still runs when waitForReady throws
• Backward compat: works when PercyDOM.waitForReady is unavailable (old CLI)

Depends on

• feat: Readiness gate in PercyDOM.serialize() — works for URL + SDK paths (PER-7348) cli#2184 (readiness implementation in @percy/dom)

[rishigupta1599]

Nice backward-compatible design — the in-browser typeof PercyDOM.waitForReady guard plus graceful exception handling is the right shape for a staged CLI rollout. A few substantive concerns worth addressing before merge:

1. readiness leaks into PercyDOM.serialize() and into the snapshot POST body. get_serialized_dom never pops readiness out of kwargs, so it gets JSON-serialized into the PercyDOM.serialize(kwargs) argument and also spread into the /percy/snapshot POST body as a top-level field. @percy/dom.serialize ignores unknown keys today, but it's a silent coupling, and the CLI snapshot endpoint receiving a top-level readiness alongside snapshot options is likely not what the CLI expects (readiness config is supposed to flow via healthcheck per the PR description). Pop readiness from kwargs once consumed.

2. Readiness runs N times for responsive capture. capture_responsive_dom calls get_serialized_dom once per width, so with 3 widths and a 10s timeout you can add up to 30s of sequential readiness waits per snapshot name. Consider running readiness once before the width loop and short-circuiting inside get_serialized_dom when responsive is active.

3. No explicit script timeout. execute_async_script relies on the driver's global script timeout (Selenium default ~30s, but BrowserStack hubs and some remotes use lower). If a user sets readiness.timeoutMs higher than the driver's script timeout, WebDriver fires ScriptTimeoutException before the in-page Promise resolves — so the user-facing timeout is silently capped. Either driver.set_script_timeout(readiness.timeoutMs + buffer) around the call (and restore the previous value) or document the interaction.

4. Minor: the is_percy_enabled() call inside _wait_for_ready is redundant — percy_snapshot has already called it and has the data dict in scope. Plumb data['config'] through instead of re-reading the lru_cache.

Tests look solid for the happy paths. Consider adding one for the responsive + readiness interaction once (2) is resolved.

[rishigupta1599]

Redundant call. percy_snapshot (the only production caller path) has already called is_percy_enabled() and has data['config'] in scope. Plumb the config through explicitly rather than relying on the lru_cache re-lookup — it makes the data flow clearer and avoids a surprise dependency on the cache for anyone who calls get_serialized_dom directly (module-level, no leading underscore).

[rishigupta1599]

If config.snapshot is ever returned from the CLI as a non-dict (e.g. null deserialized to None), .get('readiness', {}) raises AttributeError and blows up the snapshot call. Consider ((data.get('config') or {}).get('snapshot') or {}).get('readiness') or {} for symmetry with the other guards.

[rishigupta1599]

Two concerns on this execute_async_script call:

1. No script timeout is set on the driver. execute_async_script uses the session's global script timeout (Selenium default ~30s, but BrowserStack hubs and some remotes run lower). If a user configures readiness.timeoutMs higher than the driver's script timeout, WebDriver fires ScriptTimeoutException before the in-page Promise resolves — so the user-facing timeout config is silently capped. Either driver.set_script_timeout(readiness.timeoutMs / 1000 + buffer) around this call (and restore the previous value) or document the interaction prominently.

2. Readiness runs once per width for responsive snapshots. capture_responsive_dom calls get_serialized_dom inside its per-width loop, so every responsive snapshot pays the readiness cost N times. With a 10s timeoutMs across 3 widths that's up to 30s of sequential waits per snapshot. Consider running readiness once before the loop and short-circuiting inside get_serialized_dom for responsive calls (e.g. a skip_readiness=True kwarg).

[rishigupta1599]

readiness stays in kwargs after this call and then gets:

1. JSON-serialized into the PercyDOM.serialize(kwargs) argument on the next line — harmless today because @percy/dom ignores unknown keys, but it's an implicit coupling.
2. Spread into the requests.post(..., json={**kwargs, ...}) body in percy_snapshot at the end of the function, so the CLI receives a top-level readiness alongside snapshot options. That likely isn't what the CLI expects (readiness config is supposed to flow via healthcheck per the PR description), and it's easy for a future CLI-side validator to reject unknown top-level fields.

Safer: kwargs.pop('readiness', None) inside _wait_for_ready once you've consumed it (or pop at this call site) so neither serialize() nor the snapshot POST sees it.

[rishigupta1599]

Minor: the readiness_diagnostics truthiness check drops falsy-but-present results. The PR description specifically calls out { timed_out: true } as a signal the CLI needs for logging — that one's fine because it's truthy — but if waitForReady ever resolves with an empty dict {} (e.g. disabled preset short-circuit inside the JS), the diagnostics are silently dropped. Prefer if readiness_diagnostics is not None and isinstance(dom_snapshot, dict):.

[rishigupta1599]

This test validates the POST happens when execute_async_script raises, but it doesn't assert that serialize() actually ran — which is the whole point of the graceful-degradation path. Consider also spying on execute_script and asserting PercyDOM.serialize was called after the readiness exception. Otherwise this passes trivially even if the serialize call were accidentally short-circuited alongside readiness.