[docs] ADR: Selenium waits for interaction readiness, not just element presence - #17886
Open
AutomatedTester wants to merge 1 commit into
Open
[docs] ADR: Selenium waits for interaction readiness, not just element presence#17886AutomatedTester wants to merge 1 commit into
AutomatedTester wants to merge 1 commit into
Conversation
AutomatedTester
force-pushed
the
adr-interaction-readiness-waits
branch
from
August 6, 2026 10:32
f81e054 to
181658f
Compare
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
force-pushed
the
adr-interaction-readiness-waits
branch
from
August 6, 2026 10:37
181658f to
d03f066
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📄 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
py-quiescence-bidi-preload— the oracle as a shared JavaScript atom registered as a BiDi preload script, exposed asdriver.wait_for_dom_settledanddriver.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.quiescencemodule; 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
waitUntilActionableis a composition of all three — deciding themseparately would mean a reader has to open three records to understand any one of them.
Deliberately out of scope.
click/send_keys. This is where Playwright sits and probably where weend up, but it changes the timing and failure modes of every existing test. Deferred, not rejected
— recorded as a follow-up decision.
ExpectedConditions.elementToBeClickableand equivalents. Listed as a follow-up.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:
the right call, or is a result record better for a wait that is best-effort by construction?
willing to own that maintenance burden, and is "best-effort, documented limits" a strong enough
framing to set user expectations?
waitForDomSettled/waitUntilActionableon the driver.Better names, or do these belong somewhere other than the driver?
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?
actually ask for?
Not yet discussed at a TLC meeting — requesting an agenda slot.
📌 Tracking
Tracking issue: (linked on acceptance)