Skip to content

Automate browser based workflows with AI

Type into a field a decorative wrapper covers, or say so at once (#8264)

pedrohsdba72743eb5576
diff --git a/skyvern/forge/taskv3/tools.py b/skyvern/forge/taskv3/tools.py
index 020b43741..5962af670 100644
--- a/skyvern/forge/taskv3/tools.py
+++ b/skyvern/forge/taskv3/tools.py
@@ -386,6 +386,154 @@ _ROOT_QUERY_JS = (
)
+# Every other probe here asks whether a control is VISIBLE. This one asks whether it is REACHABLE,
+# which is a different question and the only one that separates these two cases: Playwright reports a
+# covered input as "visible, enabled, stable" and then fails the separate hit-target check, retrying
+# until the timeout.
+_TYPE_TARGET_PROBE_JS = (
+ r"""(arg) => {
+ const _q = """
+ + _ROOT_QUERY_JS
+ + r""";
+ // A host-anchored selector's two halves straddle a shadow boundary, so no single root can match it
+ // and a per-root lookup finds nothing -- which would read as "no field here" and skip the check on
+ // exactly the controls that addressing made reachable. The executor resolves it; take its element.
+ const el = _q.find(arg.sel) || (arg.el && arg.el.isConnected ? arg.el : null);
+ if (!el) return { exists: false };
+ const out = { exists: true, disabled: !!el.disabled, readOnly: !!el.readOnly };
+ let r = el.getBoundingClientRect();
+ if (r.width === 0 || r.height === 0) return out;
+ // elementFromPoint answers about the VIEWPORT, so a field below the fold returns null and would
+ // read as unoccluded -- which is most fields on a real form. Playwright scrolls before it clicks,
+ // so scrolling here asks about the same layout the click is about to meet.
+ const inView = r.top >= 0 && r.left >= 0 && r.bottom <= innerHeight && r.right <= innerWidth;
+ if (!inView) {
+ // 'instant' matters: scrollIntoView inherits CSS scroll-behavior, and a page with smooth
+ // scrolling animates over hundreds of ms while the rect below is read synchronously -- the
+ // element is still off-screen, elementFromPoint returns null, and the probe reports nothing.
+ try { el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' }); } catch (e) { /* keep the rect */ }
+ r = el.getBoundingClientRect();
+ }
+ let top = null;
+ try { top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2); } catch (e) { return out; }
+ // elementFromPoint sees the top-level document only, so a control inside a component resolves to
+ // its host. Treat that as reachable: the host IS what a real click lands on, and the browser
+ // retargets the event inward. The walk must hop ShadowRoot -> host, because Node.contains stays in
+ // the light tree and would read every component control as covered by its own host.
+ const related = (a, b) => {
+ for (let n = b; n; n = n.parentNode || n.host || null) if (n === a) return true;
+ return false;
+ };
+ if (!top || top === el || related(el, top)) return out;
+ out.occluded = true;
+ // Whether to force is a question about the OCCLUDER, not about the field. Structure alone is not
+ // enough: when the field sits directly under <body>, or shares a container with a portal target,
+ // EVERY overlay on the page is "inside its parent". So the occluder must also be the size of a
+ // skin. A decoration drawn over one field stays within that field's box give or take its own
+ // border; a dialog, cookie banner or backdrop is dramatically larger, and forcing past one would
+ // type into something the user cannot see.
+ // One property decides this: is the occluder part of the field's own control, or a surface layered
+ // over the region the field sits in? There are three ways to be a layer, and every condition below
+ // is one of them -- so a fourth would have to be a fourth way, not another special case.
+ // - it sits outside the field's own subtree (structure);
+ // - it is pinned to the viewport, where a control's decoration scrolls with its field;
+ // - it is the size of the viewport, where a decoration is the size of a control.
+ // Ancestors are NOT exempt. "A dialog is never an ancestor of what it covers" was wrong: a wrapper
+ // that disables its own contents while busy is exactly that, and so is a full-screen container
+ // that wraps the form it blocks.
+ const tr = top.getBoundingClientRect();
+ const area = (b) => Math.max(1, b.width * b.height);
+ const viewport = Math.max(1, innerWidth * innerHeight);
+ // Pinning is inherited from whichever ancestor establishes it, so reading the hit element alone
+ // misses the ordinary modal shape: a fixed backdrop wrapping a statically-positioned panel. And
+ // sticky pins to the viewport too once it sticks -- a sticky header covering a field is not a
+ // decoration of that field.
+ let pinned = false;
+ for (let n = top; n && n.nodeType === 1; n = n.parentNode || n.host || null) {
+ let pos = '';
+ try { pos = getComputedStyle(n).position; } catch (e) { break; }
+ if (pos === 'fixed' || pos === 'sticky') { pinned = true; break; }
+ }
+ // Measured against the VIEWPORT, not the field: 10x a small input is a small box, but 10x a large
+ // textarea is bigger than the screen, so a field-relative cap stops meaning anything exactly when
+ // the field is big. A decoration covers a control; a dialog or backdrop covers the view.
+ const coversTheView = area(tr) > 0.6 * viewport;
+ // "The field's own control" is its containing block, not its immediate parent: an overlay skin is
+ // positioned against that block, and design systems routinely put an inner wrapper between the
+ // input and it. Walking to the nearest positioned ancestor finds the same element the skin itself
+ // was laid out against, so a skin one wrapper deeper still reads as part of the control.
+ // Walk up from the OCCLUDER to the block it was positioned against, and ask whether the field is
+ // inside that block. Asking from the field's side instead stops at the field's own wrapper, and a
+ // design system that puts an inner wrapper around the input then hides its own skin from us.
+ let block = null;
+ for (let n = top.parentElement; n; n = n.parentElement) {
+ let pos = '';
+ try { pos = getComputedStyle(n).position; } catch (e) { break; }
+ if (pos !== 'static') { block = n; break; }
+ }
+ // With no positioned ancestor the occluder is laid out against the page itself, so fall back to
+ // the field's own parent rather than letting it inherit the document as its unit.
+ const unit = block || el.parentElement;
+ // Small is not the same as THIS field's. A table row, a card or a list item is small and holds
+ // several independent controls, so a sibling's dropdown or a row-level "saving" overlay would
+ // otherwise read as this field's decoration. A control the field shares with no other control is
+ // the field's own; one that holds others is a layout region.
+ let unitOwnsOnlyThisField = false;
+ if (unit && area(unit.getBoundingClientRect()) <= 0.6 * viewport) {
+ try {
+ unitOwnsOnlyThisField = !Array.from(
+ unit.querySelectorAll('input,select,textarea,button,a[href],[contenteditable],[role="button"]')
+ ).some((c) => c !== el && !related(el, c));
+ } catch (e) { unitOwnsOnlyThisField = false; }
+ }
+ // A thing that announces itself as an overlay is one. This is the least ambiguous signal here --
+ // a decoration has no role, while a tooltip, dialog or toast says so in its markup.
+ const LAYER_ROLE = /^(tooltip|dialog|alertdialog|alert|status|menu|listbox|log|marquee)$/i;
+ let declaresItselfALayer = false;
+ for (let n = top; n && n.nodeType === 1 && n !== unit; n = n.parentNode || n.host || null) {
+ const role = n.getAttribute && n.getAttribute('role');
+ if ((role && LAYER_ROLE.test(role.trim())) || n.hasAttribute('aria-modal') || n.tagName === 'DIALOG') {
+ declaresItselfALayer = true;
+ break;
+ }
+ }
+ const inFieldsOwnSubtree =
+ related(top, el) || (unitOwnsOnlyThisField && related(unit, top) && related(unit, el));
+ out.skinned = !pinned && !coversTheView && !declaresItselfALayer && inFieldsOwnSubtree;
+ return out;
+}"""
+)
+
+_ACTIVE_IS_JS = (
+ r"""(arg) => {
+ const _q = """
+ + _ROOT_QUERY_JS
+ + r""";
+ const el = _q.find(arg.sel) || (arg.el && arg.el.isConnected ? arg.el : null);
+ if (!el) return null;
+ // A control inside a component reports its host as document.activeElement, so ask the root that
+ // actually holds the control rather than the document.
+ let root = null;
+ try { root = Node.prototype.getRootNode.call(el); } catch (e) { root = null; }
+ const active = root && root.activeElement ? root.activeElement : document.activeElement;
+ return active === el;
+}"""
+)
+
+
+class _FieldCovered(Exception):
+ """The field exists and is rendered, but something unrelated is on top of it."""
+
+
+class _FieldNotEditable(Exception):
+ """The field cannot accept typed text at all -- it is disabled, or readonly."""
+
+ def __init__(self, selector: str, read_only: bool) -> None:
+ super().__init__(selector)
+ self.selector = selector
+ self.read_only = read_only
+
+
# Design-system forms render a <select> at zero size behind a styled listbox proxy. Playwright's
# actionability wait never resolves against it, so select_option probes visibility first and only
# forces past actionability when the element exists but is genuinely hidden this way.
@@ -1738,6 +1886,21 @@ def build_browser_tools(
"it (the section header, the step, the modal trigger), then re-observe."
)
+ def _not_editable_error(exc: _FieldNotEditable) -> ToolResult:
+ if exc.read_only:
+ return ToolResult.error(
+ f"{exc.selector} is readonly — typing cannot change it. If it opens a list, click it and "
+ "pick an option instead; otherwise act on whatever sets it."
+ )
+ return ToolResult.error(f"{exc.selector} is disabled — it cannot be typed into until the page enables it")
+
+ def _covered_error(selector: str) -> ToolResult:
+ return ToolResult.error(
+ f"{selector} is rendered but something else is on top of it, so it cannot be typed into — a "
+ "person could not click it either. Dismiss whatever covers it (a dialog, an overlay, a cookie "
+ "banner), then re-observe."
+ )
+
async def _probe_arg(page: Any, selector: str) -> dict[str, Any]:
# Probes resolve per root, which cannot match a host-anchored selector whose two halves
# straddle a shadow boundary. The executor's own engine can, so it supplies the element the
@@ -2018,6 +2181,75 @@ def build_browser_tools(
await page.hover(selector, timeout=15000)
return ToolResult.ok(f"hovered {selector}")
+ async def _reachable_for_typing(page: Any, selector: str) -> tuple[bool, bool]:
+ """(reachable, occluded). Raises when the field cannot accept typed text at all. Shared by both
+ typing paths: fill() does no hit-testing, so without this a covered password or email field is
+ filled silently -- no timeout to notice, and a person could not have reached it."""
+ try:
+ probe = await page.evaluate(_TYPE_TARGET_PROBE_JS, await _probe_arg(page, selector))
+ except Exception:
+ probe = None
+ if isinstance(probe, dict) and probe.get("exists"):
+ # fill() waits for "enabled" and "editable" on its own, so without these the run pays a
+ # second full timeout for a state the probe has already read.
+ if probe.get("disabled") or probe.get("readOnly"):
+ raise _FieldNotEditable(selector, bool(probe.get("readOnly")))
+ occluded = bool(isinstance(probe, dict) and probe.get("occluded"))
+ if occluded and not probe.get("skinned"):
+ return False, occluded
+ return True, occluded
+
+ async def _focus_for_typing(page: Any, selector: str) -> bool:
+ """Put the caret in `selector`. False means the field is genuinely covered and must not be typed
+ into. A click is how a widget learns to open its suggestion list, so it stays the first move."""
+ reachable, occluded = await _reachable_for_typing(page, selector)
+ if not reachable:
+ return False
+ if occluded:
+ # Forcing skips the hit-target check but still dispatches at coordinates, so the wrapper
+ # can take the event; the focus check below is what makes the outcome deterministic.
+ # Failures are NOT swallowed: force already removed the only reason this click was
+ # expected to fail, so what is left (a detached node, a navigation) is real.
+ # A URL is the wrong question: history.pushState changes it without leaving the page,
+ # and a widget that syncs filter state into the URL on click would abort typing on a
+ # field that never moved. A navigation clears window, so a token planted on it answers
+ # "is this still the same document" exactly -- the same technique the pre-snapshot uses.
+ await page.evaluate("() => { window.__tv3_doc = 1; }")
+ await page.click(selector, timeout=15000, force=True)
+ try:
+ await page.wait_for_load_state("domcontentloaded", timeout=1000)
+ except Exception:
+ pass
+ try:
+ same_document = bool(await page.evaluate("() => window.__tv3_doc === 1"))
+ except Exception:
+ same_document = False
+ if not same_document:
+ # The wrapper was a link and the click followed it. The selector may well match
+ # something on the destination, so typing now would put the text somewhere nobody
+ # asked for.
+ return False
+ try:
+ # The click may have remounted or hidden the field -- a wrapper that swaps its input
+ # on click is an ordinary SPA shape. fill() would wait its own full timeout for a
+ # node that is gone or invisible, which is the cost this whole path exists to avoid.
+ await page.wait_for_selector(selector, state="visible", timeout=1200)
+ except Exception:
+ return False
+ else:
+ await page.click(selector, timeout=15000)
+ try:
+ focused = await page.evaluate(_ACTIVE_IS_JS, await _probe_arg(page, selector))
+ except Exception:
+ focused = None
+ # None is "could not tell" -- a selector document.querySelector cannot parse, or a probe that
+ # threw. Only an explicit False is evidence the caret went somewhere else.
+ if focused is False:
+ # focus() needs no hit target, so it repairs a skin that swallowed the click without
+ # forwarding it. Typing then goes to the field rather than wherever the caret was.
+ await page.focus(selector, timeout=15000)
+ return True
+
async def _commit_typeahead(
page: Any, selector: str, value: str, rounds: int
) -> tuple[str | None, str | None, bool]:
@@ -2091,7 +2323,8 @@ def build_browser_tools(
# Keystroke-type (so a widget's async suggestion fetch fires on real key events). Snapshot the
# visible DOM just before typing so the finder treats only NEW/reacting nodes as suggestions —
# static page text that merely shares a word with the value can't be mistaken for one.
- await page.click(selector, timeout=15000)
+ if not await _focus_for_typing(page, selector):
+ raise _FieldCovered(selector)
await page.fill(selector, "", timeout=15000)
presnapshot_ok = True
try:
@@ -2170,7 +2403,12 @@ def build_browser_tools(
if text and clear and not press_enter and await _field_type(page, selector) not in _NON_TYPEAHEAD_TYPES:
# keystroke-type (via _type_and_commit) so a widget that fetches suggestions on key events —
# not just on a single `input` from fill — still surfaces them, then commit the best match.
- committed, opt_txt, readable = await _type_and_commit(page, selector, text, rounds=3)
+ try:
+ committed, opt_txt, readable = await _type_and_commit(page, selector, text, rounds=3)
+ except _FieldCovered:
+ return _covered_error(selector)
+ except _FieldNotEditable as exc:
+ return _not_editable_error(exc)
if opt_txt and committed:
return ToolResult.ok(
f"typed into {selector}; it is a typeahead — selected {opt_txt!r} (committed value: {committed!r})"
@@ -2205,6 +2443,15 @@ def build_browser_tools(
"commit was verified; re-observe to confirm the value before relying on it"
)
return ToolResult.ok(f"typed into {selector}")
+ # The types that skip the typeahead probe still must not be typed into through an overlay.
+ # They reach fill()/type(), which do no hit-testing, so nothing here would fail on its own --
+ # the text simply lands in a field the person could not have reached.
+ try:
+ reachable, _ = await _reachable_for_typing(page, selector)
+ except _FieldNotEditable as exc:
+ return _not_editable_error(exc)
+ if not reachable:
+ return _covered_error(selector)
if clear:
await page.fill(selector, text, timeout=15000)
else:
@@ -2346,7 +2593,12 @@ def build_browser_tools(
return error
selector = args["selector"]
value = _resolve_text(args["value"])
- committed, opt_txt, readable = await _type_and_commit(page, selector, value, rounds=8)
+ try:
+ committed, opt_txt, readable = await _type_and_commit(page, selector, value, rounds=8)
+ except _FieldCovered:
+ return _covered_error(selector)
+ except _FieldNotEditable as exc:
+ return _not_editable_error(exc)
if opt_txt is None:
# The suggestion finder pierces open shadow roots, so inside a component it now sees a
# list rendered in that root -- but a portalled or closed-root list stays invisible, so a
diff --git a/tests/unit/test_taskv3_tools.py b/tests/unit/test_taskv3_tools.py
index a5f209228..ef0fc29a5 100644
--- a/tests/unit/test_taskv3_tools.py
+++ b/tests/unit/test_taskv3_tools.py
@@ -3220,6 +3220,519 @@ async def test_observe_reports_a_reused_component_id_as_reused_not_as_anonymous(
assert "have no id, name or data-testid of their own" not in r.content, r.content
+# No <label> anywhere, deliberately: an earlier version of this fix keyed on "does the field have a
+# visible label", which passes this fixture for a reason that has nothing to do with the occluder.
+_COVERED_FIELD_HTML = """
+<div data-role="illustrated-input" style="position:relative;width:200px;height:30px">
+ <input id="city" type="text" style="position:absolute;left:0;top:0;width:200px;height:30px">
+ <div id="skin-a" style="position:absolute;left:0;top:0;width:200px;height:30px"></div>
+ <div id="skin-b" style="position:absolute;left:0;top:0;width:200px;height:30px"></div>
+</div>
+<script>
+// The decorative treatment repaints, so a DIFFERENT wrapper is topmost on each retry. A fix that
+// remembers "the thing that blocked me" would pass against one static cover and fail against this.
+var i = 0;
+setInterval(function () {
+ i++;
+ document.getElementById('skin-a').style.zIndex = (i % 2) ? '2' : '1';
+ document.getElementById('skin-b').style.zIndex = (i % 2) ? '1' : '2';
+}, 40);
+</script>
+"""
+
+
+# The label is the point: an accessible production form has one, and a discriminator that keys on
+# the FIELD rather than on the OCCLUDER reads it as reachable and types into a field behind a modal.
+_COVERED_BY_UNRELATED_HTML = """
+<label for="city" style="display:block">City</label>
+<div data-role="illustrated-input" style="position:relative;width:200px;height:30px">
+ <input id="city" type="text" style="position:absolute;left:0;top:0;width:200px;height:30px">
+</div>
+<div id="modal" style="position:fixed;left:0;top:0;width:100%;height:100%;background:#fff"></div>
+"""
+
+
+# The production shape: the field's own ANCESTOR paints over it. A negative z-index puts the input
+# behind its wrapper, so elementFromPoint returns the wrapper and Playwright's hit-target check fails.
+_COVERED_BY_ANCESTOR_HTML = """
+<div id="wrap" data-role="illustrated-input" style="position:relative;width:200px;height:30px;background:#eee">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_drives_a_field_a_decorative_wrapper_covers() -> None:
+ # Playwright's actionability check PASSES on this input -- it is visible, enabled and stable --
+ # and the click then fails the separate HIT-TARGET check, retrying for the full 15s before
+ # raising an unhandled TimeoutError out of _type_and_commit's first line. The suggestion ladder
+ # never runs, so the field is never typed into at all.
+ async with _content_page(_COVERED_FIELD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+ # force=True skips the hit-target check but still dispatches a real mouse event at
+ # coordinates, so the wrapper can receive it instead. Assert the intended element actually
+ # ended up focused rather than inferring it from the value having landed.
+ assert await page.evaluate("() => document.activeElement && document.activeElement.id") == "city"
+ # The bug spent 15s per attempt; that tax is the whole cost story on this shape.
+ assert elapsed < 10, elapsed
+
+
+@_skip_no_browser
+async def test_type_drives_a_field_its_own_ancestor_paints_over() -> None:
+ # The shape seen in production: the interceptor is the field's own wrapper, not a sibling. An
+ # ancestor is the one occluder that cannot be a page-level overlay, so it is always the widget.
+ async with _content_page(_COVERED_BY_ANCESTOR_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+ assert elapsed < 10, elapsed
+
+
+@_skip_no_browser
+async def test_type_fails_loud_and_fast_when_an_unrelated_overlay_covers_the_field() -> None:
+ # The other half of commit-or-loud: a field genuinely behind a modal must NOT be forced -- that
+ # would type into something the user cannot see. It must say so at once rather than after 15s.
+ async with _content_page(_COVERED_BY_UNRELATED_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+ assert elapsed < 10, elapsed
+
+
+# The field hangs directly off <body>, so EVERY overlay on the page is "inside its parent". A purely
+# structural skin test reads a full-viewport modal as this field's own decoration.
+_COVERED_MODAL_SHARES_PARENT_HTML = """
+<input id="city" type="text" style="position:absolute;left:0;top:0;width:200px;height:30px">
+<div id="modal" style="position:fixed;left:0;top:0;width:100%;height:100%;background:#fff;z-index:9"></div>
+"""
+
+
+# Below the fold: elementFromPoint answers about the viewport and returns null off-screen, which reads
+# as "nothing on top" and silently restores the pre-fix path for most fields on a real form.
+_COVERED_BELOW_THE_FOLD_HTML = """
+<div style="height:3000px"></div>
+<div data-role="illustrated-input" style="position:relative;width:200px;height:30px">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+</div>
+"""
+
+
+_DISABLED_UNDER_SKIN_HTML = """
+<div data-role="illustrated-input" style="position:relative;width:200px;height:30px;background:#eee">
+ <input id="city" type="text" disabled style="position:relative;z-index:-1;width:200px;height:30px">
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_refuses_a_modal_that_merely_shares_the_fields_parent() -> None:
+ # Structure alone cannot tell a skin from a backdrop when the parent is the page. The occluder
+ # has to be the size of the field too, or every overlay qualifies.
+ async with _content_page(_COVERED_MODAL_SHARES_PARENT_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+ assert time.monotonic() - start < 10
+
+
+@_skip_no_browser
+async def test_type_sees_the_cover_on_a_field_below_the_fold() -> None:
+ # The probe must ask about the layout the click is about to meet, not the one on screen now.
+ async with _content_page(_COVERED_BELOW_THE_FOLD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+ assert elapsed < 10, elapsed
+
+
+@_skip_no_browser
+async def test_type_says_a_disabled_field_is_disabled_instead_of_waiting_for_it() -> None:
+ # force= gets the click past a disabled control, but fill() then waits for "enabled" on its own,
+ # so ignoring what the probe already read costs a second full timeout.
+ async with _content_page(_DISABLED_UNDER_SKIN_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "error", r.content
+ assert "disabled" in r.content
+ assert elapsed < 10, elapsed
+
+
+# The skin is a link. Forcing the click follows it, and the selector may well match something on the
+# destination -- so "did the field stop resolving" cannot tell this from a re-render, but the URL can.
+# Needs a routed origin: set_content leaves the page on about:blank, where nothing navigates.
+_SKIN_IS_A_LINK_HTML = """
+<a id="wrap" href="/elsewhere" style="position:relative;display:block;width:200px;height:30px;background:#eee">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+</a>
+"""
+
+
+@_skip_no_browser
+async def test_type_stops_when_the_forced_click_navigates_away() -> None:
+ from playwright.async_api import async_playwright # noqa: PLC0415
+
+ async with async_playwright() as pw:
+ browser = await pw.chromium.launch(headless=True)
+ try:
+ context = await browser.new_context(viewport={"width": 1024, "height": 900})
+ page = await context.new_page()
+
+ async def _serve(route: Any) -> None:
+ body = "<h1>elsewhere</h1>" if route.request.url.endswith("/elsewhere") else _SKIN_IS_A_LINK_HTML
+ await route.fulfill(status=200, content_type="text/html", body=body)
+
+ await page.route("**/*", _serve)
+ await page.goto("http://skin.test/start")
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "error", r.content
+ assert page.url.endswith("/elsewhere"), page.url
+ # Not a 15s fill() wait against a selector on some other document.
+ assert elapsed < 10, elapsed
+ finally:
+ await browser.close()
+
+
+# scrollIntoView inherits CSS scroll-behavior. Smooth scrolling animates while the rect is read
+# synchronously on the next line, so the element is still off-screen and the probe sees nothing.
+_SMOOTH_SCROLL_BELOW_FOLD_HTML = """
+<style>html { scroll-behavior: smooth; }</style>
+<div style="height:3000px"></div>
+<div data-role="illustrated-input" style="position:relative;width:200px;height:30px">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+</div>
+"""
+
+
+# The input is a sub-region of the control it belongs to: an icon-padded pill search bar. Measuring
+# the skin against the INPUT's box rejects a legitimate decoration that is doing nothing wrong.
+_PILL_SKIN_HTML = """
+<div style="position:relative;width:320px;height:48px">
+ <input id="city" type="text" style="position:absolute;left:48px;top:0;width:220px;height:48px;border:none;background:transparent">
+ <div id="pill-skin" style="position:absolute;left:0;top:0;width:320px;height:48px;border-radius:24px"></div>
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_sees_the_cover_even_when_the_page_scrolls_smoothly() -> None:
+ async with _content_page(_SMOOTH_SCROLL_BELOW_FOLD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+ assert elapsed < 10, elapsed
+
+
+@_skip_no_browser
+async def test_type_drives_a_field_that_is_a_sub_region_of_its_own_control() -> None:
+ # A skin is sized like the control it decorates, not like the raw input inside it.
+ async with _content_page(_PILL_SKIN_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+
+
+@_skip_no_browser
+async def test_type_continues_when_the_click_only_rewrites_the_url() -> None:
+ # pushState changes the URL without leaving the page. The field never moved, so aborting here
+ # would refuse to type into a field that is still sitting there.
+ from playwright.async_api import async_playwright # noqa: PLC0415
+
+ async with async_playwright() as pw:
+ browser = await pw.chromium.launch(headless=True)
+ try:
+ context = await browser.new_context(viewport={"width": 1024, "height": 900})
+ page = await context.new_page()
+
+ async def _serve(route: Any) -> None:
+ await route.fulfill(
+ status=200,
+ content_type="text/html",
+ body="""
+ <div id="wrap" style="position:relative;width:200px;height:30px;background:#eee">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+ </div>
+ <script>
+ document.getElementById('wrap').addEventListener('click', function () {
+ history.pushState(null, '', '/search?q=');
+ });
+ </script>""",
+ )
+
+ await page.route("**/*", _serve)
+ await page.goto("http://skin.test/start")
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+ assert "/search" in page.url, "fixture must actually rewrite the URL"
+ finally:
+ await browser.close()
+
+
+# The ordinary modal shape: a fixed backdrop wrapping a statically-positioned panel. Reading the hit
+# element's own position says "relative" and the panel is barely larger than the field.
+_DIALOG_PANEL_OVER_FIELD_HTML = """
+<input id="city" type="text" style="position:absolute;left:40px;top:40px;width:200px;height:30px">
+<div id="backdrop" style="position:fixed;left:0;top:0;width:100%;height:100%">
+ <div id="dialog" style="position:relative;left:40px;top:40px;width:210px;height:36px;background:#fff">Confirm</div>
+</div>
+"""
+
+
+# Sticky pins to the viewport once stuck, so a sticky bar lying over a field is not that field's skin.
+_STICKY_BAR_OVER_FIELD_HTML = """
+<div id="bar" style="position:sticky;top:0;z-index:5;width:300px;height:40px;background:#ddd">promo</div>
+<input id="city" type="text" style="position:relative;top:-40px;width:200px;height:30px">
+"""
+
+
+# A wrapper that swaps its own input on click -- an ordinary SPA remount. The selector then resolves
+# to nothing, and fill() would wait its whole timeout for a node that no longer exists.
+_FIELD_REMOUNTS_ON_CLICK_HTML = """
+<div id="wrap" style="position:relative;width:200px;height:30px;background:#eee">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+</div>
+<script>
+document.getElementById('wrap').addEventListener('click', function () {
+ var old = document.getElementById('city');
+ if (old) { old.remove(); }
+});
+</script>
+"""
+
+
+@_skip_no_browser
+async def test_type_refuses_a_dialog_panel_whose_backdrop_is_the_pinned_one() -> None:
+ async with _content_page(_DIALOG_PANEL_OVER_FIELD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+
+
+@_skip_no_browser
+async def test_type_refuses_a_sticky_bar_lying_over_the_field() -> None:
+ async with _content_page(_STICKY_BAR_OVER_FIELD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+
+
+@_skip_no_browser
+async def test_type_stops_when_the_forced_click_removes_the_field() -> None:
+ async with _content_page(_FIELD_REMOUNTS_ON_CLICK_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ start = time.monotonic()
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ elapsed = time.monotonic() - start
+ assert r.status == "error", r.content
+ # Not a 15s fill() wait for a node that is gone.
+ assert elapsed < 10, elapsed
+
+
+# A container that blocks the form it WRAPS. The old rule exempted every ancestor on the grounds that
+# a dialog is never an ancestor of what it covers, which is not true of a blocking wrapper.
+_BLOCKING_ANCESTOR_HTML = """
+<div id="shade" style="position:absolute;left:0;top:0;width:1024px;height:900px;background:rgba(0,0,0,0.4)">
+ <input id="city" type="text" style="position:relative;z-index:-1;width:200px;height:30px">
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_refuses_an_ancestor_that_blocks_the_form_it_wraps() -> None:
+ async with _content_page(_BLOCKING_ANCESTOR_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+
+
+# email/password/tel/number/date and textarea skip the typeahead probe entirely and reach fill(),
+# which does no hit-testing -- so nothing fails on its own and the text simply lands in a field
+# nobody could have reached. Login and signup forms behind a consent banner are the everyday shape.
+_COVERED_EMAIL_FIELD_HTML = """
+<label for="em" style="display:block">Email</label>
+<input id="em" type="email" style="position:absolute;left:0;top:0;width:200px;height:30px">
+<div id="consent" style="position:fixed;left:0;top:0;width:100%;height:100%;background:#fff">Accept cookies</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_refuses_a_covered_field_whose_type_skips_the_typeahead_probe() -> None:
+ async with _content_page(_COVERED_EMAIL_FIELD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#em", "text": "[email protected]"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#em", "el => el.value") == ""
+
+
+# Design systems routinely put an inner wrapper between the input and the element the skin is
+# positioned against, so "the field's immediate parent" is narrower than "the field's own control".
+_SKIN_ONE_WRAPPER_DEEPER_HTML = """
+<div class="field-outer" style="position:relative;width:200px;height:30px">
+ <div class="input-inner" style="position:absolute;left:0;top:0;width:200px;height:30px">
+ <input id="city" type="text" style="width:200px;height:30px">
+ </div>
+ <div class="skin" style="position:absolute;left:0;top:0;width:200px;height:30px"></div>
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_drives_a_field_whose_skin_sits_a_wrapper_deeper() -> None:
+ async with _content_page(_SKIN_ONE_WRAPPER_DEEPER_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "ok", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == "Iowa City"
+
+
+# No positioning anywhere up the chain, so the occluder has no containing block of its own. Asking
+# "do they share a block" then degenerates into "are they on the same page", which every overlay is.
+_UNRELATED_BADGE_NO_POSITIONING_HTML = """
+<input id="city" type="text" style="position:absolute;left:0;top:0;width:200px;height:30px">
+<div id="badge" style="position:absolute;left:0;top:0;width:200px;height:30px;background:pink;z-index:9"></div>
+"""
+
+
+# The ordinary SPA layout: one positioned root wrapping the whole page. It contains the field AND
+# every overlay, so a shared-block test that does not ask whether the block is a CONTROL passes it.
+_POSITIONED_APP_ROOT_HTML = """
+<div id="app" style="position:relative;width:1024px;height:900px">
+ <input id="city" type="text" style="position:absolute;left:0;top:0;width:200px;height:30px">
+ <div id="popover" style="position:absolute;left:0;top:0;width:200px;height:30px;background:pink;z-index:9"></div>
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_refuses_an_unrelated_overlay_on_a_page_with_no_positioning() -> None:
+ async with _content_page(_UNRELATED_BADGE_NO_POSITIONING_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+
+
+@_skip_no_browser
+async def test_type_refuses_an_overlay_sharing_only_a_page_wide_app_root() -> None:
+ async with _content_page(_POSITIONED_APP_ROOT_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+
+
+# An inline-edit row dimmed while an async save is in flight. The row is small and positioned and
+# holds this field -- but it also holds another one, which makes it a layout region, not a control.
+_ROW_SAVING_OVERLAY_HTML = """
+<div id="row" style="position:relative;width:400px;height:40px">
+ <input id="qty" type="text" style="position:absolute;left:0;top:0;width:180px;height:40px">
+ <input id="price" type="text" style="position:absolute;left:200px;top:0;width:180px;height:40px">
+ <div id="saving" style="position:absolute;left:0;top:0;width:400px;height:40px;background:rgba(255,255,255,0.7)">Saving...</div>
+</div>
+"""
+
+
+# A help tooltip inside the same card as the field. The card holds no other control, so structure
+# alone accepts it -- but the element says what it is.
+_TOOLTIP_IN_THE_FIELDS_CARD_HTML = """
+<div id="card" style="position:relative;width:220px;height:40px">
+ <input id="city" type="text" style="position:absolute;left:0;top:0;width:220px;height:40px">
+ <div id="tip" role="tooltip" style="position:absolute;left:0;top:0;width:220px;height:40px;background:#ffd">Saved</div>
+</div>
+"""
+
+
+@_skip_no_browser
+async def test_type_refuses_a_row_overlay_in_a_container_holding_other_fields() -> None:
+ async with _content_page(_ROW_SAVING_OVERLAY_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#qty", "text": "42"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#qty", "el => el.value") == ""
+
+
+@_skip_no_browser
+async def test_type_refuses_an_occluder_that_says_it_is_an_overlay() -> None:
+ async with _content_page(_TOOLTIP_IN_THE_FIELDS_CARD_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ r = await _tool(tools, "type").handler({"selector": "#city", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#city", "el => el.value") == ""
+
+
+# A host-anchored selector's two halves straddle a shadow boundary, so no single root matches it and
+# a per-root lookup finds nothing. If the reachability probe reads that as "no field here" the guard
+# is silently off for exactly the controls host-anchoring made addressable.
+_HOST_ANCHORED_COVERED_HTML = """
+<ds-input id="host" style="display:block;position:relative;width:200px;height:30px"></ds-input>
+<div id="modal" style="position:fixed;left:0;top:0;width:100%;height:100%;background:#fff"></div>
+<script>
+var r = document.getElementById('host').attachShadow({mode: 'open'});
+r.innerHTML = '<input id="ctrl" type="text" style="width:200px;height:30px">';
+</script>
+"""
+
+
+@_skip_no_browser
+async def test_type_still_checks_reachability_for_a_host_anchored_selector() -> None:
+ async with _content_page(_HOST_ANCHORED_COVERED_HTML) as page:
+ tools = build_browser_tools(_fixed_page_provider(page))
+ # The selector the engine mints for a control inside a repeated component.
+ r = await _tool(tools, "type").handler({"selector": "#host #ctrl", "text": "Iowa City"})
+ assert r.status == "error", r.content
+ assert await page.eval_on_selector("#host #ctrl", "el => el.value") == ""
+
+
@_skip_no_browser
@pytest.mark.asyncio
async def test_select_option_on_hidden_native_select_sets_value_and_fires_change() -> None: