[feat]: expose timeout param in ts & protocol
Merged
SE
2mo ago+2292+2292+0123456789012345678901234567890123456789-410-410-012345678901234567890123456789
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 }), orcount({ 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.tschecks 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.tsuses 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.tsruns 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.tsexercises 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
0disabling 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
SetInputFilesnow takes a file-input slice, and Python rejects non-finite timeout values. - Timeout errors retain the
TimeoutErrorname and message.