[feat]: expose `timeout` param in `page.snapshot()`

Merged
SE
2mo ago
+914-227

why

page.snapshot() had no timeout param, nor did some of its internal helpers. the helpers that it calls are also called by other functions in the codebase that require timeout handling. this PR wires the progress object through the shared downstream helpers, and also exposes a user facing timeout param in page.snapshot()

what changed

  • added a snapshot timeout in milliseconds to typescript, python, & go. omission or 0 keeps snapshots unlimited.
  • made one deadline cover frame readiness, element lookup, document & accessibility tree reads, & frame traversal
  • allowed internal snapshot calls to reuse a caller's remaining time & timeout error instead of starting a new budget.
  • stopped retries, fallback reads, & further frame traversal after expiry. temporary element references are released, including those returned after timeout. already-issued browser commands can still finish.
  • updated sdk response waits to allow the requested timeout plus delivery grace, with no response deadline for unlimited snapshots

test plan

  • capture.test.ts checks public & inherited deadlines, unlimited snapshots, expiry preventing further reads or fallback, & cleanup of ignored elements.
  • domTree.test.ts & a11yTree.test.ts check that expired reads cannot retry or fall back, including when the deadline timer has not fired yet.
  • focusSelectors.test.ts checks that both selector lookup paths release element references returned after timeout. focused accessibility tests also check reference cleanup after successful reads.
  • protocol & sdk tests cover omitted, zero, positive, & invalid timeouts, option forwarding in all three sdks, & response waits. the typescript package test checks that the published snapshot options include the new field.

Summary by cubic

Adds an optional timeout param to page.snapshot() so callers can bound the entire snapshot operation. Omitted timeouts now default to 20 seconds instead of running unlimited.

  • Exposes timeout in the TypeScript, Python, and Go SDKs; passing 0 keeps snapshots unlimited.
  • Uses one deadline for frame readiness, element lookup, DOM/accessibility tree reads, and frame traversal, and lets snapshots reuse the caller's remaining time instead of starting a new budget.
  • Stops retries, fallback reads (including focus-scope and ignore-locator fallback), and further frame traversal after expiry, releasing temporary element references even when they return after the timeout.
  • SDK response waits now add delivery grace to the requested timeout and skip the deadline entirely for unlimited snapshots.