"""The retry loop, and the actions that run inside it. ⛔ THIS IS THE PIECE THAT FAILS SILENTLY, and the reason is the shape of the loop: if a condition is checked ONCE and then acted on, the page can change between the check and the action. It doesn't break: it breaks ONE TIME IN TWENTY, when loading is slower than usual. THE RIGHT SHAPE, and every line of this file exists to keep it: until it expires: RESOLVE THE SELECTOR FROM SCRATCH <- don't reuse the old handle ask whether it is actionable get the point act if something says "it's not there anymore": START OVER ⛔ **The selector is resolved on EVERY turn.** Reusing the previous turn's handle is the mistake that makes the loop pointless: if the DOM has changed, that handle points to a detached node, and the action goes nowhere without saying anything. ⛔ **And a timeout must say WHY.** A bare `TimeoutError` on a retry loop is the least useful thing you can print: the reason for the last turn - "missing visible", "the selector finds nothing", "no quad" - is the only information that tells you what to look at. """ from __future__ import annotations import time from typing import Optional from . import _pacing from .injected import EvaluationError from .keyboard import BUTTON_MASK, Keyboard, UnknownKey #: The states a pointer action requires, in the order Playwright asks for #: them. `stable` is the most expensive (waits two frames) and comes first #: because it is also the one that most often isn't true yet. ACTION_STATES = ["visible", "stable", "enabled"] class ElementNotActionable(TimeoutError): """The loop timed out. The message carries the reason for the LAST turn.""" class ActionMissed(RuntimeError): """The event went out and landed on something other than the element. ⛔ NOT RETRYABLE, AND THAT IS THE WHOLE DIFFERENCE FROM `WrongHitTarget`. That one is raised BEFORE anything happened, so starting over is free. This one is raised after: a press has been delivered to whatever was under the pointer, and a loop that repeated the action would be pressing twice. It exists because the alternative was silence. Measured 2026-09-19 with a target that moves (`tests/gates/hover_non_mente.py` in the workbench): `hover()` returned normally 2 times out of 8 with the page having seen no event at all, and `click()` 8 times out of 8 - the hit-target check before the press passed, then the element left between `mousedown` and `mouseup`, the two landed on different nodes and no `click` was ever born. Nothing after the commit looked, for a reason that is right (see `_act_on_target`), so the caller was told "done". [B217] """ class WrongHitTarget(RuntimeError): """The event would have landed on ANOTHER element. RETRYABLE condition. ⛔ It's the window that the rest of the loop doesn't close, and it was MEASURED, not feared. Between the actionability check and the event a couple of commands go by; if the layout moves in that gap - a banner appearing, a font finishing loading, a `setTimeout` shifting the page - the point calculated earlier no longer belongs to the intended element. The case from 2026-08-27: a page that at 1200 ms reveals a block higher up. `dblclick` succeeded, the page saw NO `dblclick` event at all, and on the same page without that timer the same code worked. No error anywhere: the click had landed nineteen pixels higher. """ def _normalize_options(options) -> list: """A string becomes `{"valueOrLabel": ...}`, and that's NOT a detail. ⛔ THE INJECTED SCRIPT'S FILTER STARTS FROM `matches = true` AND NARROWS it down ONLY if the criterion carries one of `valueOrLabel`, `value`, `label` or `index`. A bare string has none of those, so every option matches and **the first one** gets picked. Measured on 2026-08-27 on a `` with `display:none`. Asking that input for a quad answered "it isn't visible" on every turn until the timeout, so an upload to the commonest upload widget there is could not happen through either door, `set_input_files` or a file chooser's `set_files`. Such an action gets the element and no point: no scroll, no hit test, nothing a hidden element cannot satisfy. ⛔ AND IT IS A PROPERTY OF THE ACTION, NOT OF FILE INPUTS: every action whose `states` are empty declared that it needs no visibility, and the quad put the requirement back. `focus`, `blur` and `dispatch_event` on a `display:none` element timed out the same way, 4 s out of 4, where Playwright performs all three; they pass `needs_point=False` too. ⛔ `position` travels HERE and not through each action, because the point is recomputed on every turn of this loop: an offset applied by the caller once would be stale the moment the page moved, which is precisely the case this loop exists to absorb. ⛔ `element_id` IS THE ElementHandle CASE, and it changes exactly two things. The node is not looked up again - a handle names one node, and re-querying the selector would be a different element with the same description, which is not what `handle.click()` means - and the node is NOT disposed at the end, because it belongs to the caller and disposing it would destroy the handle they still hold. Everything else is deliberately shared: states, the point, the scroll, the hit-target check, the retry on detachment. A second loop for handles would be a second definition of "actionable" and a second click path, and two click paths are two fingerprints. """ f = frame_id or self.lifecycle.main_frame if f is None: raise RuntimeError("no main frame: the page isn't ready") states = ACTION_STATES if states is None else states deadline = time.monotonic() + timeout reason = "haven't tried yet" turns = 0 while True: turns += 1 element = None ours = False try: if element_id is not None: # The caller's node, fixed. Not re-queried and not ours. element = element_id else: # ⛔ FROM SCRATCH on every turn. A handle from the previous # turn could point to a node the DOM has since replaced. # ⛔ `strict` REACHES HERE OR IT MEANS NOTHING. The # injected script has always known how to raise on it and # the chain accepts it, but no caller ever passed it: the # default stayed false, so a selector matching MORE THAN # ONE element acted on the FIRST instead of refusing. That # is not only correctness - the automation was touching an # element nobody had chosen. element = self.inj.query_selector(f, selector, strict=strict) ours = True if not element: reason = "the selector finds nothing" elif states and not force: result = self.inj.element_states(f, element, states) if not result.get("ok"): reason = "missing %s" % result.get("missing", "a state") element_ok = False else: element_ok = True else: element_ok = True if element and element_ok and not needs_point: if trial: return None return run(f, element, None) if element and element_ok: # ⛔ SCROLL FIRST, and only when the point is not usable. # Actionability says "visible", which is true of an element # three thousand pixels down; the POINT is what has to be # inside the viewport, and `getContentQuads` answers in # main-frame coordinates. Scrolling unconditionally would # move the page under every ordinary click for nothing, so # the quad is measured first and the scroll happens only if # it lands outside - then the loop recomputes, because the # geometry has just changed underneath. point = self._center_point(f, element, position) if point is not None and not self._in_viewport(point): if self.inj.scroll_into_view(f, element): reason = ("the element was outside the viewport; " "scrolled it in and starting over") continue point = self._center_point(f, element, position) if point is None: reason = "the element has no quad (it isn't visible)" elif trial: # ⛔ TRIAL STOPS HERE, AND HERE IS THE ONLY PLACE IT CAN. # # It used to stop nowhere. The public API accepts it on # 31 signatures and `_juggler/` never mentioned it, so # `click(trial=True)` performed a real click. The only # reader was the cursor wrapper, which took it as a # reason to skip the approach and then ran the action # anyway: the worst of the three possible behaviours, # because the click went out in the most recognisable # form there is, with no pointer movement before it. # # This loop is where it belongs. `trial` is a statement # ABOUT ACTIONABILITY - run the checks, skip the act - # and this loop is the only thing that knows what # actionable means. Honouring it inside each action # would be the same sentence written six times, and the # seventh action would be written without it. # # The hit target is checked too: a trial that answers # yes, followed by a click that lands elsewhere, has # told the caller nothing. It costs one pure read. # # ⛔ Unless `force`, which skips that check on the real # path: a trial has to answer the question the caller # would actually ask, and `trial=True, force=True` asks # whether a FORCED action would go through. if not force: verdict = self.hit_target(f, element, point) if verdict != "done": raise WrongHitTarget(verdict) return None else: return run(f, element, point) except EvaluationError as e: # ⛔ "notconnected" means the node disappeared BETWEEN the # resolution and the use: it's the case the loop exists to # absorb, not a failure. Everything else propagates. if "notconnected" not in str(e): raise reason = "the node detached while I was using it" except WrongHitTarget as e: # ⛔ This too is a condition of the WORLD, not a failure: the # point stopped belonging to the element before we committed, # so nothing was done and starting over is free. The point gets # recalculated on the new geometry. # # ⛔ AND THAT SENTENCE IS THE INVARIANT THIS LOOP RESTS ON: # STARTING OVER IS SOUND ONLY WHILE NOTHING HAS HAPPENED. It # was broken for four versions. `_act_on_target` used to read # the DOM again AFTER the event and raise this same exception # on what it found, so "the click missed" and "the click worked # and the control moved out from under the pointer" arrived # here as the same word - and this line repeated the action. # Measured on 0.22.0: thirty-nine clicks delivered for one # call, and a toggle flipped twice and reported success. # # Nothing may raise this after committing. An action that needs # to report something about what it did afterwards must say so # in its RESULT: a retry loop cannot un-press a button, so it # must never be handed a reason to press one twice. reason = "the event would have landed elsewhere (%s)" % e finally: # Only what this loop resolved. Disposing the caller's handle # here would make `handle.click()` destroy the handle, and the # NEXT call on it would fail with the node not existing - an # error naming neither the cause nor the previous call. if element and ours: self.inj.dispose(f, element) if time.monotonic() > deadline: raise ElementNotActionable( "%r not actionable in %.0fs after %d attempts. Last " "reason: %s" % (selector, timeout, turns, reason)) time.sleep(0.05) # ── the hit target ────────────────────────────────────────────────────── def hit_target(self, f, element, point) -> str: """Does a MAIN-FRAME point land on `element`? `"done"`, or what is there. ⛔ ONE QUESTION, ONE ANSWER, THREE ASKERS: the trial, the check before a commit, and the humanised cursor choosing an off-centre landing (`ElementHandle.checkHitTarget`). The cursor used to answer it on its own with `document.elementFromPoint` at main-frame coordinates, which is wrong twice: inside a nested frame the number means another place, and inside a shadow root the hit is the host, never the control. Both made every landing fail its check and fall back to the exact geometric centre - one number for every click. Asking here means the cursor accepts exactly the points the action itself would accept. """ return self.inj.check_hit_target(f, element, self._hit_point(f, point)) def _hit_point(self, f, point): """The caller's point, expressed in `f`'s own coordinate space. ⛔ A POINT IS ALWAYS IN THE MAIN FRAME'S SPACE when it gets here: `Page.getContentQuads` answers there and `dispatchMouseEvent` wants it there. Handing that number to a hit test running INSIDE a nested frame asks the child about a coordinate that means something else, and it answers `` - which is how a covered element used to be reported for something sitting right under the pointer. The shift is the difference between the two content origins, read from the engine rather than recomputed here. """ if f == self.lifecycle.main_frame: return point main = self.inj.content_origin(self.lifecycle.main_frame) here = self.inj.content_origin(f) return (point[0] + main["x"] - here["x"], point[1] + main["y"] - here["y"]) def _act_on_target(self, f, element, point, *, approach, commit, force: bool = False, lands: tuple = ("mousedown", "mouseup")): """Approach, check that the point still belongs to the element, and only then do the thing that cannot be taken back. ⛔ `force` SKIPS THE CHECK, AND THAT IS NOT AN EXEMPTION - IT IS WHAT THE OPTION MEANS. "Receives events" is one of the actionability checks `force` is documented to bypass, and an overlay intercepting the pointer is the ordinary reason somebody passes it. Honouring `force` on the state checks alone would leave it half wired, which is the defect this was: an option accepted on every public signature that changed nothing a caller could observe. ⛔ IT USED TO BE AN INTERCEPTOR, and that history is why the shape here matters. An interceptor watched each event WHILE it arrived and BLOCKED the ones whose point had stopped belonging to the element. It needed capture listeners for the duration of every action, and the block itself was a tell: a real `mousedown` that vanishes under `preventDefault` is not something any input stack produces. It was replaced by two pure DOM reads, one before the action and one after, and the one AFTER is what this corrects. ⛔ A CHECK AFTER THE EVENT CANNOT ANSWER THE QUESTION IT IS ASKED, AND IT DROVE A RETRY. Once the event has gone out, these two are the SAME observation: the point stopped belonging to the element BEFORE the event, so the click landed on something else; the point stopped belonging to the element BECAUSE of the event, so the click landed exactly where it was aimed and the control did what it exists to do. The second is not an edge case, it is most controls. Measured on the published 0.22.0, one `browser_click` per call: a button that hides itself on click received THIRTY-NINE clicks and the call then reported failure; a panel toggle was opened and closed by a single call, which reported success; a button that only moves, and one that does nothing, were correct thirty times out of thirty. The discriminant is not movement - it is the target ceasing to be hittable BY ITS OWN EFFECT. A check whose negative result carries no information cannot gate anything, so it is gone rather than narrowed. What it leaves behind is the invariant `_retry` depends on: starting over is sound only while nothing has happened, and every raise here is now before `commit`. ⛔ AND THE READ MOVED AFTER `approach`, WHICH IS WHERE THE RACE IS. It used to run before the pointer moved, so a page that rearranges itself on hover - a menu opening under the cursor is the ordinary case - was judged in the layout that existed before the thing that changed it. What is left is one round trip between this read and the press. Closing that one belongs to the engine, the only place that can verify and dispatch without a gap; it is not closed by reading the DOM again afterwards, which is what this function just stopped doing. Measured by `tests/gates/injected_page_surface.js`: the bundle touches the page's window zero times, in every phase. ⛔ AND WHAT CLOSES THE GAP IS NOT A THIRD READ OF THE GEOMETRY. It is the engine telling us where each event LANDED, recorded at dispatch by a privileged listener the page cannot see (`Page.pointerLanded`). That answer distinguishes what a read after the fact cannot: an event that hit the element and then saw it move away by its own effect landed ON the element, and says so. `lands` names the events the commit emits - the press and the release for a click, the one move for a hover - and every one of them must have landed on the element or inside it, which is also the condition under which the DOM composes a `click`. A miss raises `ActionMissed`, which `_retry` does not catch: something has happened, and the invariant this loop rests on is that it starts over only while nothing has. `force` skips this as it skips the check before: the caller has said the event is to go wherever the pointer is, and an overlay receiving it is then not a miss but the request. [B217] """ approach() if not force: verdict = self.hit_target(f, element, point) if verdict != "done": raise WrongHitTarget(verdict) if force or not lands: return commit() # ⛔ WHERE EACH EVENT LANDED COMES BACK WITH ITS DISPATCH. While the # commit runs, every mouse event it sends names this element # (`landsOn`): the engine holds the element before the event is sent # and judges the landing when the page handled the event, in the same # turn. A question asked afterwards (`Page.pointerLanded`, until # firefox-39) met whatever the page had become by then - a submit that # navigated had already taken the element away. [B230] self._landing_target, self._landings = (f, element), {} try: result = commit() finally: self._landing_target = None landings = self._landings # ⛔ A DIALOG THE ACTION OPENED ENDS THE ENGINE'S WAIT with no verdict: # the page's process is inside the dialog, and the dialog is the proof # that the action landed. if any(landings.get(kind, False) is None for kind in lands): return result missed = ["%s was never sent" % kind if kind not in landings else "%s landed on %s" % (kind, landings[kind]["on"]) for kind in lands if kind not in landings or not landings[kind]["landed"]] if missed: raise ActionMissed( "the action went out but did not reach the element: " + "; ".join(missed)) return result # ── waiting ───────────────────────────────────────────────────────────── def wait_for_selector(self, selector: str, *, state: str = "visible", timeout: float = 30.0, frame_id: Optional[str] = None, strict: bool = False): """Waits for a selector to reach a state, and returns its handle. ⛔ THE HANDLE IS NOT DISPOSED HERE, and that is deliberate: the caller is about to use it. `_retry` disposes what it resolves on every turn precisely because it re-resolves, so this cannot go through it - it would hand back an objectId it has just released, and a released handle does not raise, it answers wrong. ⛔ AND `state="attached"` AND `"detached"` ARE NOT ELEMENT STATES. The injected script knows visible / hidden / enabled / disabled / editable / checked; presence in the DOM is answered by the selector resolving at all, so those two are handled here rather than asked of a function that would reject them. """ frame = frame_id or self.lifecycle.main_frame if frame is None: raise RuntimeError("no main frame: the page is not ready") deadline = time.monotonic() + timeout reason = "not tried yet" while True: element = self.inj.query_selector(frame, selector, strict=strict) if state == "detached": if not element: return None self.inj.dispose(frame, element) reason = "the element is still attached" elif element: if state == "attached": return element try: if self.inj.element_state(frame, element, state): return element reason = "the element is not %s" % state except EvaluationError as failure: reason = str(failure) self.inj.dispose(frame, element) else: reason = "the selector matches nothing" if time.monotonic() > deadline: raise ElementNotActionable( "%r did not become %s in %.0fs. Last reason: %s" % (selector, state, timeout, reason)) time.sleep(0.05) # ── the actions ───────────────────────────────────────────────────────── def hover(self, selector: str, *, timeout: float = 30.0, frame_id: Optional[str] = None, position=None, element_id: Optional[str] = None, **opts): def run(f, element, point): # The move IS the action here, so there is nothing to approach # first: the check sits immediately before the only event. return self._act_on_target( f, element, point, approach=lambda: self._approach(point, stop_short=True), commit=lambda: self._mouse_event("mousemove", point) or point, force=bool(opts.get("force")), # The one event a hover emits. Without this the check after # the commit would ask about a press that never went out. lands=("mousemove",)) return self._retry(selector, run, timeout=timeout, element_id=element_id, frame_id=frame_id, position=position, **opts) def click(self, selector: str, *, timeout: float = 30.0, frame_id: Optional[str] = None, button: int = 0, delay_ms: Optional[float] = None, clicks: int = 1, position=None, modifiers: int = 0, element_id: Optional[str] = None, **opts): def run(f, element, point): def act(): self._click_at_point(point, button=button, clicks=clicks, modifiers=modifiers, delay_ms=delay_ms) return point # The order is that of a user: approach, press, release. Skipping # the mousemove leaves the page without the hover, and there are # sites that open the menu right there - which is also why the # target is checked BETWEEN the two rather than before both. # ⛔ The move carries the modifiers too. A page that reads # `event.shiftKey` on `mouseover` - menus do - would otherwise # see an unmodified approach followed by a modified click, # which no real input device produces. return self._act_on_target( f, element, point, approach=lambda: self._approach(point, modifiers=modifiers), commit=act, force=bool(opts.get("force"))) return self._retry(selector, run, timeout=timeout, frame_id=frame_id, position=position, element_id=element_id, **opts) def dblclick(self, selector: str, *, timeout: float = 30.0, frame_id: Optional[str] = None, delay_ms: Optional[float] = None, button: int = 0, position=None, modifiers: int = 0, **opts): """⛔ These are NOT two `click`s in a row: the second one must carry `clickCount: 2`, and it's that field - not the interval between the two - that gives birth to the `dblclick` event. Two clicks with `clickCount: 1` produce two `click` events and no `dblclick`, which is a silent failure: the action succeeds and the site's handler never fires. ⛔ AND IT FORWARDS `frame_id`, which it used to accept and drop. A double click on an element inside an iframe resolved the selector in the MAIN frame instead, so it either found nothing or found a same-named element in the wrong document. The signature said the argument was honoured; nothing else did.""" return self.click(selector, timeout=timeout, button=button, clicks=2, frame_id=frame_id, position=position, modifiers=modifiers, delay_ms=delay_ms, **opts) def check(self, selector: str, *, timeout: float = 30.0, frame_id: Optional[str] = None, position=None, element_id: Optional[str] = None, **opts): return self._set_checked(selector, True, timeout=timeout, element_id=element_id, frame_id=frame_id, position=position, **opts) def uncheck(self, selector: str, *, timeout: float = 30.0, frame_id: Optional[str] = None, position=None, element_id: Optional[str] = None, **opts): return self._set_checked(selector, False, timeout=timeout, element_id=element_id, frame_id=frame_id, position=position, **opts) def _set_checked(self, selector: str, wanted: bool, *, timeout: float, frame_id: Optional[str] = None, position=None, element_id: Optional[str] = None, **opts): """`check` / `uncheck`. ⛔ It CHECKS FIRST, and rechecks after. Clicking without looking flips a box that was already right - that's the obvious defect - but the second check is the one that matters: a `