[feat]: expose timeout param in ts & protocol

Merged
SE
2mo ago
+2292-410

why

this PR adds the timeout param to the protocol, & exposes it publicly in ts. the default timeout is 20 seconds

what changed

  • added optional timeout settings to all 17 terminal locator methods, including reads. typescript callers can use click({ timeout: 5000 }), fill("hello", { timeout: 5000 }), or count({ timeout: 0 }).
  • started one deadline before frame resolution & passed it through the whole call. frame readiness, element lookup, typing delays, highlight duration, & extension-side upload preparation all share that budget.
  • aligned typescript response waits with the execution timeout plus delivery grace. zero disables that response deadline too. long timeouts avoid the JS timer limit, & timeout errors retain their name & message.
  • made the compatibility facade pass its remaining budget to native locator calls, including zero, instead of dropping timeout options

test plan

  • locator-timeouts.test.ts checks every registered locator method accepts zero & positive timeouts, rejects invalid values, preserves omission, & keeps existing options working. timeout settings stay separate from locator identity.
  • runtime-locator-timeouts.test.ts uses controlled time to verify every entry point starts its deadline before resolution, applies the default or override, rejects stalled work, & leaves zero unlimited.
  • wrapper, rpc, & package tests cover option forwarding, the public options type, response deadlines & delivery grace, long timers, & timeout error details. facade tests check remaining-budget forwarding for ordinary & frame locators.
  • iframeLocatorReadiness.test.ts runs against real chrome with same-process frames & frames in a separate process. it verifies nested frame readiness & typing share one budget, explicit timeouts can exceed the old readiness cap, zero waits successfully, & loading a frame after expiry does not cause a late click.
  • locatorActions.test.ts exercises highlight & upload cleanup through the runtime: stalled cleanup preserves an earlier action error & does not delay timeout rejection.

Summary by cubic

Adds a timeout option to all terminal locator methods across the protocol and the TypeScript, Python, and Go SDKs, and updates the v4 docs. The default is 20 seconds, and { timeout: 0 } disables the deadline.

What changed

  • One deadline starts before frame resolution and covers frame readiness, element lookup, typing delays, highlight duration, and upload preparation; SDK file reading and request delivery happen before that budget starts.
  • Each SDK sets its RPC response deadline to the execution timeout plus a delivery grace, with 0 disabling it; long timeouts work around per-language timer limits.
  • The Playwright compatibility facade forwards its remaining budget to native locator calls, including zero.
  • Go's SetInputFiles now takes a file-input slice, and Python rejects non-finite timeout values.
  • Timeout errors retain the TimeoutError name and message.