Skip to content

[docs] ADR: Selenium waits for interaction readiness, not just element presence - #17886

Open
AutomatedTester wants to merge 1 commit into
trunkfrom
adr-interaction-readiness-waits
Open

[docs] ADR: Selenium waits for interaction readiness, not just element presence#17886
AutomatedTester wants to merge 1 commit into
trunkfrom
adr-interaction-readiness-waits

Conversation

@AutomatedTester

Copy link
Copy Markdown
Member

📄 The decision, its rationale, considered options, and consequences are in the record file
this PR adds; read it there. The sections below are proposal notes and review logistics.

🔗 Related

  • Builds on 17670 — BiDi implementation boundaries: the readiness waits are high-level, protocol-neutral API, with BiDi as an implementation mechanism that must not leak into their signatures.
  • Reference implementation (Python): py-quiescence-bidi-preload — the oracle as a shared JavaScript atom registered as a BiDi preload script, exposed as driver.wait_for_dom_settled and driver.wait_until_actionable, with ~1,500 lines of behavioral tests. Evidence that the semantics are implementable and testable; not proposed as the final API shape.
  • Intended to become a proposed WebDriver BiDi quiescence module; no working-group issue filed yet.

📝 Proposal notes

Why one record. The three layers (pending work, DOM settledness, actionability) share a single
context and rationale, and waitUntilActionable is a composition of all three — deciding them
separately would mean a reader has to open three records to understand any one of them.

Deliberately out of scope.

  • Implicit waiting inside click/send_keys. This is where Playwright sits and probably where we
    end up, but it changes the timing and failure modes of every existing test. Deferred, not rejected
    — recorded as a follow-up decision.
  • Deprecating ExpectedConditions.elementToBeClickable and equivalents. Listed as a follow-up.
  • The BiDi module proposal itself. Pursued in parallel; the record commits to taking it to the
    working group, not to its shape.

One place the record departs from the reference implementation. The prototype returns a result
record on timeout; the record decides a timeout should raise the binding's existing timeout error
carrying the diagnosis (Considered options 11–12). Called out in the Appendix so the difference
isn't mistaken for an oversight.

Cross-binding impact. Every binding gains two driver methods and the packaging wiring to ship a
JavaScript resource; bindings that already ship atoms have most of this. Only the Python side has
been built.

🗣 Discussion

Questions I would most like input on:

  1. Timeout behavior — is raising the binding's timeout error with the diagnosis in the message
    the right call, or is a result record better for a wait that is best-effort by construction?
  2. Scope of the guarantee — the waits are heuristics and will be wrong sometimes. Is the project
    willing to own that maintenance burden, and is "best-effort, documented limits" a strong enough
    framing to set user expectations?
  3. Entry-point names and placementwaitForDomSettled / waitUntilActionable on the driver.
    Better names, or do these belong somewhere other than the driver?
  4. Degradation — pending-work tracking needs a BiDi session and a preload script; the other two
    layers don't. Is explicit "could not observe pending work" in the result the right behavior, or
    should the wait refuse to run without BiDi?
  5. Should the implicit-wait question be decided now rather than deferred, given it is what users
    actually ask for?

Not yet discussed at a TLC meeting — requesting an agenda slot.

📌 Tracking

Tracking issue: (linked on acceptance)

@AutomatedTester
AutomatedTester force-pushed the adr-interaction-readiness-waits branch from f81e054 to 181658f Compare August 6, 2026 10:32
Proposes that Selenium ship supported, protocol-neutral readiness waits
built from three composable layers — a pending-work ledger, DOM
settledness, and element actionability — with the semantics defined once
in a shared JavaScript atom injected as a BiDi preload script, and
framed as a prototype of a proposed BiDi quiescence module.

Status: Proposed.
@AutomatedTester
AutomatedTester force-pushed the adr-interaction-readiness-waits branch from 181658f to d03f066 Compare August 6, 2026 10:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant