Skip to content

Automate browser based workflows with AI

feat(SKY-11944): skyvern_select_option works on custom dropdowns and autocomplete, not just native <select> (#7454)

Marc Kelechava7021e7792e0c
diff --git a/skyvern/cli/core/browser_ops.py b/skyvern/cli/core/browser_ops.py
index be63b1835..4aad0655d 100644
--- a/skyvern/cli/core/browser_ops.py
+++ b/skyvern/cli/core/browser_ops.py
@@ -16,11 +16,15 @@ from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Callable, Literal
+import structlog
+
from skyvern.forge.sdk.settings_manager import SettingsManager
from skyvern.webeye.utils.page import JS_FUNCTION_DEFS, SkyvernFrame
from .guards import GuardError
+LOG = structlog.get_logger(__name__)
+
@dataclass
class NavigateResult:
@@ -1280,3 +1284,503 @@ async def do_execute(
results=results,
error_step=next((r.step for r in results if not r.ok), None),
)
+
+
+_DOM_FALLBACK_OPTION_WAIT_MS = 3000
+_CUSTOM_SELECT_KEY_EVENT_RETRY_MS = 1000
+
+_CUSTOM_SELECT_TARGET_JS = r"""
+(element) => {
+ const tag = element.tagName.toLowerCase();
+ const type = tag === "input" ? (element.type || "").toLowerCase() : "";
+ const isPassword = tag === "input" && type === "password";
+ const haspopupValue = element.getAttribute("aria-haspopup");
+ const optionish = Boolean(element.querySelector('[role="option"], [role="listbox"], [data-value]'));
+ const related = Boolean(`${element.getAttribute("aria-controls") || ""} ${element.getAttribute("aria-owns") || ""}`.trim());
+ const tabindex = element.hasAttribute("tabindex") && Number(element.getAttribute("tabindex")) >= 0;
+ const editable = (["input", "textarea"].includes(tag) || element.isContentEditable) &&
+ !isPassword && !element.readOnly && !element.disabled &&
+ (element.getAttribute("aria-readonly") || "").toLowerCase() !== "true";
+ const ownedIds = `${element.getAttribute("aria-controls") || ""} ${element.getAttribute("aria-owns") || ""}`.trim().split(/\s+/).filter(Boolean);
+ return {tag, type, isPassword, role: (element.getAttribute("role") || "").toLowerCase(),
+ haspopup: haspopupValue !== null && !["", "false"].includes(haspopupValue.toLowerCase()), editable,
+ optionish, related, selectlike: tabindex && (optionish || related),
+ ownedSelectors: ownedIds.map((id) => "#" + CSS.escape(id))};
+}
+"""
+
+_CUSTOM_SELECT_IS_OBSERVED_JS = r"""
+(element, observedSelectors) => observedSelectors.some((selector) => document.querySelector(selector) === element)
+"""
+
+_CUSTOM_SELECT_SCOPED_OPTIONS_JS = r"""
+(element, target) => {
+ const optionSelectors = target.optionSelectors || [];
+ const options = optionSelectors.map((selector) => [selector, document.querySelector(selector)]).filter((entry) => entry[1]);
+ const ownedIds = `${element.getAttribute("aria-controls") || ""} ${element.getAttribute("aria-owns") || ""}`.trim().split(/\s+/).filter(Boolean);
+ const owned = ownedIds.map((id) => document.getElementById(id)).filter(Boolean);
+ let scoped = [];
+ if (ownedIds.length) {
+ // Declared ownership is exclusive even before the owned root mounts: the poll loop
+ // retries until it appears; falling back earlier could click an unrelated widget.
+ scoped = options.filter((entry) => owned.some((root) => root.contains(entry[1])));
+ } else if (target.bareInput) {
+ const before = new Set(target.beforeOptionSelectors || []);
+ const widgetSelector = 'input, textarea, select, button, [role="combobox"], [role="listbox"], [role="textbox"], [aria-haspopup], [tabindex]:not([role="option"]), [contenteditable]:not([contenteditable="false"])';
+ let ownContainer = null;
+ for (let parent = element.parentElement, depth = 0; parent && depth < 4; parent = parent.parentElement, depth += 1) {
+ const hasOtherWidget = Array.from(parent.querySelectorAll(widgetSelector)).some((node) => node !== element);
+ if (hasOtherWidget) break;
+ ownContainer = parent;
+ }
+ scoped = options.filter((entry) => !before.has(entry[0]) || Boolean(ownContainer && ownContainer.contains(entry[1])));
+ } else {
+ scoped = options.filter((entry) => element.contains(entry[1]));
+ }
+ if (!ownedIds.length && !target.bareInput && !scoped.length) {
+ for (let parent = element.parentElement, depth = 0; parent && depth < 4; parent = parent.parentElement, depth += 1) {
+ scoped = options.filter((entry) => parent.contains(entry[1]));
+ if (scoped.length) break; }
+ }
+ // The DOM scan can mark the control itself, its display text, and option containers as
+ // role=option. Real options are leaf candidates; when container candidates exist, only
+ // leaves inside a container count — that excludes display children of the control.
+ const containers = scoped.filter((entry) => entry[1] !== element && scoped.some((other) => other[1] !== entry[1] && entry[1].contains(other[1])));
+ let leaves = scoped.filter((entry) => entry[1] !== element && !scoped.some((other) => other[1] !== entry[1] && entry[1].contains(other[1])));
+ if (containers.length) leaves = leaves.filter((entry) => containers.some((root) => root[1].contains(entry[1])));
+ const describe = (entry) => ({selector: entry[0],
+ label: (entry[1].innerText || entry[1].textContent || entry[1].getAttribute("aria-label") || "").replace(/\s+/g, " ").trim(),
+ value: entry[1].value || entry[1].getAttribute("value") || entry[1].getAttribute("data-value") || ""});
+ return leaves.map(describe);
+}
+"""
+
+_CUSTOM_SELECT_COMMIT_JS = r"""
+(element, target) => {
+ const option = document.querySelector(target.matched);
+ const optionNodes = target.options.map((selector) => document.querySelector(selector)).filter(Boolean);
+ const clone = element.cloneNode(true);
+ const cloneFor = (node) => {
+ const path = [];
+ for (let current = node; current && current !== element; current = current.parentElement) {
+ const parent = current.parentElement;
+ if (!parent) return null;
+ path.unshift(Array.prototype.indexOf.call(parent.children, current));
+ }
+ let current = clone;
+ for (const index of path) current = current && current.children[index];
+ return current;
+ };
+ const optionClones = optionNodes.filter((node) => element.contains(node)).map(cloneFor).filter(Boolean);
+ optionClones.forEach((node) => node.remove());
+ const text = (clone.innerText || clone.textContent || "").replace(/\s+/g, " ").trim();
+ const ownedIds = `${element.getAttribute("aria-controls") || ""} ${element.getAttribute("aria-owns") || ""}`.trim().split(/\s+/).filter(Boolean);
+ const roots = [element.parentElement, ...ownedIds.map((id) => document.getElementById(id))].filter(Boolean);
+ const seen = new Set();
+ const nodeKey = (node) => {
+ if (node.id) return `#${node.id}`;
+ if (node.tagName.toLowerCase() === "input" && node.type === "hidden" && node.name) {
+ return `input:hidden:${node.name}`;
+ }
+ return null;
+ };
+ const channelCandidates = [];
+ roots.forEach((root) => [root, ...root.querySelectorAll("*")].forEach((node) => {
+ if (seen.has(node) || optionNodes.some((optionNode) => optionNode === node || optionNode.contains(node))) return;
+ seen.add(node);
+ const key = nodeKey(node);
+ if (!key) return;
+ if (node.tagName.toLowerCase() === "input" && node.type === "hidden") {
+ channelCandidates.push({key: `${key}:value`, value: node.value || ""});
+ }
+ if (node.hasAttribute("data-value")) {
+ channelCandidates.push({key: `${key}:data-value`, value: node.getAttribute("data-value") || ""});
+ }
+ }));
+ const keyCounts = channelCandidates.reduce((counts, channel) => {
+ counts.set(channel.key, (counts.get(channel.key) || 0) + 1);
+ return counts;
+ }, new Map());
+ const containerChannels = channelCandidates.filter((channel) => keyCounts.get(channel.key) === 1);
+ return {
+ text, value: element.value || element.getAttribute("value") || "",
+ dataValue: element.getAttribute("data-value") || "", containerChannels,
+ channelValues: channelCandidates.map((channel) => channel.value),
+ expanded: element.getAttribute("aria-expanded"), optionVisible: Boolean(option && option.getClientRects().length),
+ optionPresent: Boolean(option),
+ optionSelected: Boolean(option && (option.selected || option.getAttribute("aria-selected") === "true"))};
+}
+"""
+
+
+class CustomSelectOpenError(RuntimeError):
+ """Opening the widget (the initial click/fill) failed before any option was acted on."""
+
+
+class CustomSelectRestoreError(RuntimeError):
+ """The custom-select value could not be restored, so another action path is unsafe."""
+
+
+class CustomSelectPasswordError(RuntimeError):
+ """The target is a password input — a terminal, no-fallback rejection so the secret
+ value never reaches the native fill or the AI-fallback LLM payload."""
+
+
+class CustomSelectClassifyError(RuntimeError):
+ """The target could not be classified (detached/navigated mid-probe). The caller must
+ fail closed before any value-bearing AI fallback rather than treat it as native deferral."""
+
+
+class CustomSelectMatchError(RuntimeError):
+ def __init__(self, selector: str, requested_option: str, observed_options: list[str]) -> None:
+ super().__init__(f"No unambiguous match for {requested_option!r}")
+ self.selector = selector
+ self.requested_option = requested_option
+ self.observed_options = observed_options
+
+
+def _normalized_option(value: Any) -> str:
+ return " ".join(str(value or "").split()).casefold()
+
+
+def _custom_select_commit_channels(snapshot: dict[str, Any]) -> dict[str, str]:
+ return {
+ str(channel["key"]): _normalized_option(channel.get("value"))
+ for channel in snapshot.get("containerChannels") or []
+ if isinstance(channel, dict) and channel.get("key")
+ }
+
+
+async def _custom_select_dom_elements(page: Any, scan_selectors: list[str] | None) -> list[dict[str, Any]]:
+ if not scan_selectors:
+ return await _get_dom_observe_elements(page)
+ elements: dict[str, dict[str, Any]] = {}
+ for scan_selector in scan_selectors:
+ for element in await _get_dom_observe_elements(page, scan_selector):
+ selector = str(element.get("selector") or "")
+ if selector:
+ elements[selector] = element
+ return list(elements.values())
+
+
+async def _restore_custom_select_value(control: Any, original_value: str | None, timeout: int) -> None:
+ if original_value is None:
+ raise CustomSelectRestoreError("Could not restore original value before fallback")
+ try:
+ await control.fill(original_value, timeout=timeout)
+ restored_value = await control.evaluate(
+ "element => element.value ?? element.textContent ?? ''",
+ timeout=timeout,
+ )
+ except Exception as e:
+ raise CustomSelectRestoreError("Could not restore original value before fallback") from e
+ if str(restored_value) != original_value:
+ raise CustomSelectRestoreError("Could not verify restored original value before fallback")
+
+
+async def _scoped_custom_options(
+ page: Any,
+ control: Any,
+ dom_elements: list[dict[str, Any]] | None = None,
+ *,
+ before_option_selectors: set[str] | None = None,
+ bare_input: bool = False,
+ scan_selectors: list[str] | None = None,
+) -> list[dict[str, Any]]:
+ if dom_elements is None:
+ dom_elements = await _custom_select_dom_elements(page, scan_selectors)
+ options = [element for element in dom_elements if element.get("role") == "option" and element.get("selector")]
+ selectors = [str(element["selector"]) for element in options]
+ scoped = await control.evaluate(
+ _CUSTOM_SELECT_SCOPED_OPTIONS_JS,
+ {
+ "optionSelectors": selectors,
+ "beforeOptionSelectors": list(before_option_selectors or ()),
+ "bareInput": bare_input,
+ },
+ )
+ if not isinstance(scoped, list):
+ return []
+ by_selector = {str(element["selector"]): element for element in options}
+ enriched = []
+ for entry in scoped:
+ element = by_selector.get(str(entry.get("selector") or "")) if isinstance(entry, dict) else None
+ if element is not None:
+ enriched.append({**element, "label": str(entry.get("label") or ""), "value": str(entry.get("value") or "")})
+ return enriched
+
+
+_LIVE_PASSWORD_JS = (
+ "(s) => { const el = document.querySelector(s); "
+ "return !!el && el.tagName === 'INPUT' && (el.getAttribute('type') || '').toLowerCase() === 'password'; }"
+)
+
+
+async def _assert_live_target_not_password(page: Any, selector: str) -> None:
+ """Re-check the LIVE element immediately before writing to it — guards a TOCTOU swap to a
+ password input between classification and the fill. Unknown state fails closed."""
+ try:
+ is_password = bool(await page.evaluate(_LIVE_PASSWORD_JS, selector))
+ except Exception as e:
+ raise CustomSelectClassifyError(selector) from e
+ if is_password:
+ raise CustomSelectPasswordError(selector)
+
+
+async def do_select_option(
+ page: Any,
+ selector: str,
+ value: str,
+ *,
+ by_label: bool = False,
+ timeout: int = 30000,
+ restore_value_on_failure: bool = False,
+ fail_closed_on_unknown: bool = False,
+) -> str | None:
+ """Deterministic custom-select pipeline: classify the control, open (click) or
+ filter (fill) it, scope scan-observed options to it, click the unique match, then
+ verify a committed-state transition. Returns None to defer to the native path."""
+ probe_timeout = min(timeout, _NATIVE_OPTION_PROBE_TIMEOUT_MS)
+ try:
+ control = page.locator(selector).first
+ target = await control.evaluate(_CUSTOM_SELECT_TARGET_JS, timeout=probe_timeout)
+ except Exception as e:
+ LOG.debug("custom-select classification probe failed", selector=selector, exc_info=True)
+ # Unknown classification: the caller decides (native deferral for direct calls,
+ # fail-closed before value-bearing AI fallback) — never silently defer to the LLM.
+ raise CustomSelectClassifyError(selector) from e
+
+ if target.get("isPassword") or (
+ isinstance(target, dict)
+ and target.get("tag") == "input"
+ and str(target.get("type") or "").casefold() == "password"
+ ):
+ # Terminal, no fallback: never fill a password field and never let its value reach
+ # the native SDK / AI-fallback LLM payload via a hybrid selector+intent call.
+ raise CustomSelectPasswordError(selector)
+ if not isinstance(target, dict) or target.get("tag") == "select":
+ return None
+ bare_typeahead = bool(target.get("tag") == "input" and target.get("editable") and not target.get("related"))
+ dom_fallback = target.get("role") not in {"combobox", "listbox"} and not target.get("haspopup")
+ if dom_fallback or bare_typeahead:
+ dom_elements = await _get_dom_observe_elements(page)
+ else:
+ dom_elements = []
+ before_option_selectors = {
+ str(element["selector"])
+ for element in dom_elements
+ if bare_typeahead and element.get("role") == "option" and element.get("selector")
+ }
+ if dom_fallback:
+ observed_selectors = [str(element["selector"]) for element in dom_elements if element.get("selector")]
+ try:
+ observed = await control.evaluate(_CUSTOM_SELECT_IS_OBSERVED_JS, observed_selectors, timeout=probe_timeout)
+ except Exception as e:
+ if fail_closed_on_unknown:
+ raise CustomSelectClassifyError(selector) from e
+ return None
+ if not observed:
+ return None
+ scan_observed_shape = observed and (target.get("optionish") or target.get("related"))
+ bare_typeahead = bool(bare_typeahead and observed)
+ if not target.get("selectlike") and not scan_observed_shape and not bare_typeahead:
+ return None
+
+ started_at = time.monotonic()
+ deadline = started_at + timeout / 1000
+ # Deliberately overrides larger caller timeouts: dom-fallback ticks re-scan the page,
+ # and a control this ambiguous should fail fast to the native path, not poll for minutes.
+ option_deadline = min(deadline, started_at + _DOM_FALLBACK_OPTION_WAIT_MS / 1000) if dom_fallback else deadline
+ original_value: str | None = None
+ if target.get("editable"):
+ if restore_value_on_failure:
+ try:
+ original_value = str(
+ await control.evaluate(
+ "element => element.value ?? element.textContent ?? ''", timeout=probe_timeout
+ )
+ )
+ except Exception:
+ original_value = None
+ if target.get("editable"):
+ await _assert_live_target_not_password(page, selector)
+ try:
+ if target.get("editable"):
+ await control.fill(value, timeout=timeout)
+ else:
+ await control.click(timeout=timeout)
+ except Exception as e:
+ if target.get("editable") and restore_value_on_failure:
+ await _restore_custom_select_value(control, original_value, probe_timeout)
+ raise CustomSelectOpenError(str(e) or type(e).__name__) from e
+
+ requested = _normalized_option(value)
+ options: list[dict[str, Any]] = []
+ observed_options: list[str] = []
+ matches: list[dict[str, Any]] = []
+ commit_target: dict[str, Any] = {}
+ before_commit: dict[str, Any] | None = None
+ last_click_error: Exception | None = None
+ # Owned roots are exclusive scope, so the per-tick re-scan can walk just those
+ # subtrees instead of the whole document (full-page walks get expensive on real pages).
+ raw_scan_selectors = target.get("ownedSelectors")
+ scan_selectors = (
+ [str(scan_selector) for scan_selector in raw_scan_selectors if str(scan_selector)]
+ if isinstance(raw_scan_selectors, list)
+ else None
+ )
+ key_event_retry_at = min(option_deadline, started_at + _CUSTOM_SELECT_KEY_EVENT_RETRY_MS / 1000)
+ used_key_event_retry = False
+ saw_scoped_options = False
+ poll_delay = 0.1
+ # Each tick re-scans fresh: the pre-open/pre-fill scan can only see the collapsed
+ # control's display text (not the real options), and matching that display against
+ # the requested value clicks a no-op display node instead of a real option.
+ while (now := time.monotonic()) < option_deadline:
+ options = await _scoped_custom_options(
+ page,
+ control,
+ before_option_selectors=before_option_selectors,
+ bare_input=bare_typeahead,
+ scan_selectors=scan_selectors,
+ )
+ saw_scoped_options = saw_scoped_options or bool(options)
+ observed_options = _extract_options({"children": options}) or observed_options
+ matches = []
+ for option in options:
+ candidates = {
+ _normalized_option(option.get("name")),
+ _normalized_option(option.get("label")),
+ } - {""}
+ if not by_label:
+ candidates.add(_normalized_option(option.get("value")))
+ if requested in candidates:
+ matches.append(option)
+ if len(matches) == 1:
+ matched_selector = str(matches[0]["selector"])
+ commit_target = {
+ "matched": matched_selector,
+ "options": [str(option["selector"]) for option in options],
+ }
+ try:
+ before_commit = await control.evaluate(_CUSTOM_SELECT_COMMIT_JS, commit_target, timeout=probe_timeout)
+ except Exception:
+ matches = []
+ else:
+ try:
+ await page.locator(matched_selector).first.click(timeout=probe_timeout)
+ except Exception as e:
+ last_click_error = e
+ matches = []
+ else:
+ last_click_error = None
+ break
+ if target.get("editable") and not used_key_event_retry and not saw_scoped_options and now >= key_event_retry_at:
+ retry_dom_elements = await _custom_select_dom_elements(page, scan_selectors)
+ if bare_typeahead:
+ before_option_selectors = {
+ str(element["selector"])
+ for element in retry_dom_elements
+ if element.get("role") == "option" and element.get("selector")
+ }
+ await _assert_live_target_not_password(page, selector)
+ try:
+ await control.fill("", timeout=timeout)
+ await control.press_sequentially(value, timeout=timeout)
+ except Exception as e:
+ if restore_value_on_failure:
+ await _restore_custom_select_value(control, original_value, probe_timeout)
+ raise CustomSelectOpenError(str(e) or type(e).__name__) from e
+ used_key_event_retry = True
+ poll_delay = 0.1
+ continue
+ await asyncio.sleep(poll_delay)
+ poll_delay = min(poll_delay * 1.5, 0.5)
+
+ if len(matches) != 1:
+ if last_click_error is not None:
+ raise RuntimeError(str(last_click_error)) from last_click_error
+ # Pre-option-click failure: no option was acted on, so a caller that will retry
+ # through another path (AI fallback) can safely see the pre-fill value again.
+ # Post-option failures above leave the widget alone — replaying them is unsafe.
+ if target.get("editable") and restore_value_on_failure:
+ await _restore_custom_select_value(control, original_value, probe_timeout)
+ if dom_fallback and not bare_typeahead and not observed_options:
+ return None
+ raise CustomSelectMatchError(selector, value, observed_options)
+
+ matched = matches[0]
+ matched_label = str(matched.get("name") or matched.get("label") or value)
+ matched_value = str(matched.get("value") or "")
+ expected_values = {requested, _normalized_option(matched_value)} - {""}
+ display_labels = {
+ _normalized_option(matched.get("name")),
+ _normalized_option(matched.get("label")),
+ } - {""}
+ # For any editable target the helper's own fill() wrote the control value, so it is
+ # not commit evidence — only the specific data-value, option state, and display text count.
+ # Only explicitly attributable selection channels (element value / data-value / hidden
+ # inputs) count — never arbitrary data-* like data-loading.
+ editable_target = bool(target.get("editable"))
+ before = before_commit if isinstance(before_commit, dict) else {}
+
+ def _stable_values(snapshot: dict[str, Any]) -> set[str]:
+ values = {_normalized_option(snapshot.get("dataValue"))}
+ if not editable_target:
+ values.add(_normalized_option(snapshot.get("value")))
+ return values - {""}
+
+ before_stable_values = _stable_values(before)
+ before_channels = _custom_select_commit_channels(before)
+ before_channel_values = {_normalized_option(v) for v in (before.get("channelValues") or [])} - {""}
+ before_text = _normalized_option(before.get("text"))
+ while time.monotonic() < deadline:
+ committed = await control.evaluate(_CUSTOM_SELECT_COMMIT_JS, commit_target, timeout=probe_timeout)
+ if isinstance(committed, dict):
+ committed_stable_values = _stable_values(committed)
+ committed_channels = _custom_select_commit_channels(committed)
+ text = _normalized_option(committed.get("text"))
+ value_transition = bool(expected_values.intersection(committed_stable_values - before_stable_values))
+ # A container channel proves commit when it newly carries the requested value.
+ # Same-key change → compare against that key's own before value. New key (possible
+ # sibling-removal key shift) → require the value to be absent from all before
+ # channels so an unchanged input cannot masquerade as newly added.
+ container_transition = editable_target and any(
+ value
+ and value in expected_values
+ and value != before_channels.get(key)
+ and (key in before_channels or value not in before_channel_values)
+ for key, value in committed_channels.items()
+ )
+ # Deselection veto: only when the matched option is STILL PRESENT and its selected
+ # state flips true->false. An unmounted option (widget closed on commit) is NOT a
+ # deselection signal and must fall through to the positive-evidence checks.
+ selected_to_unselected = bool(
+ before.get("optionSelected") and committed.get("optionPresent") and not committed.get("optionSelected")
+ )
+ if selected_to_unselected:
+ break
+ selected_transition = not before.get("optionSelected") and bool(committed.get("optionSelected"))
+ stable_idempotent = bool(
+ expected_values.intersection(before_stable_values).intersection(committed_stable_values)
+ ) or bool(before.get("optionSelected") and committed.get("optionSelected"))
+ text_transition = any(
+ not (before_text == label or re.search(rf"(?<!\w){re.escape(label)}(?!\w)", before_text))
+ and (text == label or re.search(rf"(?<!\w){re.escape(label)}(?!\w)", text))
+ for label in display_labels
+ )
+ if value_transition or container_transition or selected_transition or text_transition or stable_idempotent:
+ return matched_label
+ attributable_list_close = bool(
+ editable_target
+ and not before_channels
+ and not committed_channels
+ and before.get("optionVisible")
+ and not committed.get("optionVisible")
+ )
+ if attributable_list_close:
+ return matched_label
+ await asyncio.sleep(poll_delay)
+ poll_delay = min(poll_delay * 1.5, 0.5)
+
+ raise RuntimeError(f"Custom select did not commit {matched_label!r}")
diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.py
index f60558419..7a8396c5a 100644
--- a/skyvern/cli/mcp_tools/browser.py
+++ b/skyvern/cli/mcp_tools/browser.py
@@ -3,6 +3,7 @@ from __future__ import annotations
import asyncio
import base64
import json
+import os
import re
from datetime import datetime, timezone
from typing import Annotated, Any, Callable, Literal
@@ -14,6 +15,10 @@ from pydantic import Field
from skyvern.cli.core.browser_ops import (
_ALLOWED_EXECUTE_TOOLS,
MAX_EXECUTE_STEPS,
+ CustomSelectClassifyError,
+ CustomSelectMatchError,
+ CustomSelectOpenError,
+ CustomSelectPasswordError,
ExecuteStep,
ObserveFrameError,
ToolStepError,
@@ -27,6 +32,7 @@ from skyvern.cli.core.browser_ops import (
do_navigate,
do_observe,
do_screenshot,
+ do_select_option,
parse_extract_schema,
ref_map_from_elements,
ref_to_selector,
@@ -44,6 +50,7 @@ from skyvern.cli.core.guards import resolve_ai_mode as _resolve_ai_mode
from skyvern.cli.core.guards import (
validate_wait_until,
)
+from skyvern.core.script_generations.skyvern_page import SkyvernPage
from skyvern.schemas.run_blocks import CredentialType
from ._common import (
@@ -94,6 +101,10 @@ def _blank_to_none(value: str | None) -> str | None:
return value if value is None or value.strip() else None
+def _add_timing_prefix(timing_ms: dict[str, int], elapsed_ms: int) -> dict[str, int]:
+ return {name: elapsed_ms + duration for name, duration in timing_ms.items()}
+
+
def _truncate_error_message(message: str) -> str:
message = message.strip()
if len(message) <= _ERROR_MESSAGE_MAX_CHARS:
@@ -367,7 +378,9 @@ async def skyvern_click(
resolved = await page.click(selector=selector, prompt=intent, ai=ai_mode, **kwargs) # type: ignore[arg-type]
else:
assert selector is not None
- resolved = await page.click(selector=selector, _skip_element_prep=skip_element_prep, **kwargs)
+ if isinstance(page, SkyvernPage):
+ kwargs["_skip_element_prep"] = skip_element_prep
+ resolved = await page.click(selector=selector, **kwargs)
timer.mark("sdk")
except PlaywrightTimeoutError as e:
if direct_action and selector is not None:
@@ -907,7 +920,10 @@ async def skyvern_type(
await page.fill(selector=selector, value=text, prompt=intent, ai=ai_mode, timeout=action_timeout) # type: ignore[arg-type]
else:
assert selector is not None
- await page.fill(selector, text, timeout=action_timeout, _skip_element_prep=skip_element_prep)
+ fill_kwargs: dict[str, Any] = {"timeout": action_timeout}
+ if isinstance(page, SkyvernPage):
+ fill_kwargs["_skip_element_prep"] = skip_element_prep
+ await page.fill(selector, text, **fill_kwargs)
else:
kwargs: dict[str, Any] = {"timeout": action_timeout}
if delay is not None:
@@ -919,7 +935,9 @@ async def skyvern_type(
await loc.type(text, **kwargs)
else:
assert selector is not None
- await page.type(selector, text, _skip_element_prep=skip_element_prep, **kwargs)
+ if isinstance(page, SkyvernPage):
+ kwargs["_skip_element_prep"] = skip_element_prep
+ await page.type(selector, text, **kwargs)
timer.mark("sdk")
except PlaywrightTimeoutError as e:
if direct_action and selector is not None:
@@ -1156,6 +1174,9 @@ async def skyvern_select_option(
"""Select an option from a dropdown menu. Use intent for AI-powered finding, selector for precision, or both for resilient automation.
For free-text input fields, use skyvern_type instead. For non-dropdown buttons or links, use skyvern_click.
+ Targeting a plain text input types the value while probing for suggestions and fails closed if none appear;
+ hybrid calls restore the original value before the AI fallback runs, direct calls leave the typed value.
+ The deterministic attempt and each SDK fallback stage get their own timeout budget rather than one shared deadline.
"""
selector = _blank_to_none(selector)
intent = _blank_to_none(intent)
@@ -1171,6 +1192,18 @@ async def skyvern_select_option(
),
)
+ # Credential-intent guard (parity with skyvern_type/skyvern_act): a password/credential
+ # intent must not reach the AI fallback, even with no selector or a stale one.
+ try:
+ if intent is not None:
+ check_password_prompt(intent)
+ except GuardError as e:
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),
+ )
+
try:
page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)
except BrowserNotAvailableError:
@@ -1180,6 +1213,158 @@ async def skyvern_select_option(
direct_action = is_direct_action(selector, ai_mode, deterministic=deterministic)
action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
+ # Credential safety runs OUTSIDE the custom-select gate and the kill switch: a password
+ # target must never be filled or have its value forwarded to the AI-fallback LLM payload.
+ # When the target type cannot be determined, fail closed for the value-bearing AI path.
+ password_target: bool | None = False
+ if selector is not None:
+ scope: Any = getattr(page, "_locator_scope", None) or getattr(page, "page", page)
+ try:
+ password_target = bool(
+ await scope.locator(selector).first.evaluate(
+ "el => el.tagName === 'INPUT' && (el.getAttribute('type') || '').toLowerCase() === 'password'",
+ timeout=min(action_timeout, 1000),
+ )
+ )
+ except Exception:
+ password_target = None
+ if password_target or (password_target is None and ai_mode is not None and not deterministic):
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ "Cannot select an option on a password field",
+ CREDENTIAL_HINT,
+ ),
+ )
+
+ # Operational kill switch: restores the exact pre-custom-select behavior
+ # (native <select> only, no classification probe) without a code rollback.
+ custom_select_disabled = os.environ.get("SKYVERN_DISABLE_CUSTOM_SELECT", "").strip().lower() in ("1", "true", "yes")
+ custom_attempt_ms = 0
+ if selector is not None and not custom_select_disabled:
+ custom_selection = None
+ custom_fallback_attempted = False
+ with Timer() as custom_timer:
+ try:
+ custom_selection = await do_select_option(
+ getattr(page, "_locator_scope", None) or getattr(page, "page", page),
+ selector,
+ value,
+ by_label=by_label,
+ timeout=action_timeout,
+ restore_value_on_failure=ai_mode == "fallback" and not deterministic,
+ fail_closed_on_unknown=ai_mode is not None and not deterministic,
+ )
+ if custom_selection is not None:
+ custom_timer.mark("sdk")
+ except CustomSelectPasswordError:
+ # Terminal for every call shape (direct AND hybrid): a password value must
+ # never reach the native SDK fill or the AI-fallback LLM payload.
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=custom_timer.timing_ms,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ "Cannot select an option on a password field",
+ CREDENTIAL_HINT,
+ ),
+ )
+ except CustomSelectClassifyError:
+ # Target detached/navigated mid-probe (TOCTOU after the boundary check). Fail
+ # closed for the value-bearing AI path; a direct call defers to the native
+ # SDK, which cannot forward the value to an LLM.
+ if ai_mode is not None and not deterministic:
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=custom_timer.timing_ms,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ "Could not verify the target before AI selection",
+ "Re-observe the element and retry with a stable selector",
+ ),
+ )
+ except CustomSelectMatchError as e:
+ if deterministic or ai_mode != "fallback":
+ observed = ", ".join(e.observed_options) or "none"
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=custom_timer.timing_ms,
+ error=make_error(
+ ErrorCode.ACTION_FAILED,
+ f"No unambiguous option matched {e.requested_option!r}",
+ f"Retry with one of the observed options: {observed}",
+ details={
+ "element_state": "no_unambiguous_match",
+ "selector": e.selector,
+ "requested_option": e.requested_option,
+ "observed_options": e.observed_options,
+ },
+ ),
+ )
+ custom_fallback_attempted = True
+ except CustomSelectOpenError as e:
+ # The widget never opened (click intercepted, fill timeout) — nothing was
+ # acted on, so hybrid calls may still recover through the AI fallback.
+ if deterministic or ai_mode != "fallback":
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=custom_timer.timing_ms,
+ error=make_error(
+ ErrorCode.ACTION_FAILED,
+ _exception_message(e),
+ "Could not open the dropdown to inspect its options",
+ details=_exception_details(e),
+ ),
+ )
+ custom_fallback_attempted = True
+ except Exception as e:
+ # Post-option-click failures (an option was clicked but did not verifiably
+ # commit) leave the widget in an unknown state — replaying through the AI
+ # fallback could double-act, so these are terminal even for hybrid calls.
+ # Only the pre-option branches above may fall through.
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=custom_timer.timing_ms,
+ error=make_error(
+ ErrorCode.ACTION_FAILED,
+ _exception_message(e),
+ "The custom dropdown selection could not be verified",
+ details=_exception_details(e),
+ ),
+ )
+ if custom_fallback_attempted:
+ custom_attempt_ms = custom_timer.timing_ms.get("total", 0)
+ if custom_selection is not None:
+ return make_result(
+ "skyvern_select_option",
+ browser_context=ctx,
+ data={
+ "selector": selector,
+ "intent": intent,
+ "ai_mode": ai_mode,
+ "value": value,
+ "selected_option": {"label": custom_selection},
+ "sdk_equivalent": (
+ f"# No single SDK method -- open/filter {selector!r}, "
+ f"then click exact observed option {custom_selection!r}"
+ ),
+ },
+ timing_ms=custom_timer.timing_ms,
+ )
+
with Timer() as timer:
try:
# selector_mode="direct" pins the selector with no AI fall-back. Only an intent-only call
@@ -1208,6 +1393,20 @@ async def skyvern_select_option(
"skyvern_select_option", ctx, timer, page, selector, e, action_timeout
)
code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILED
+ if custom_attempt_ms:
+ timer.mark("total")
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=_add_timing_prefix(timer.timing_ms, custom_attempt_ms),
+ error=make_error(
+ code,
+ _exception_message(e),
+ "Check selector and available options",
+ details=_exception_details(e),
+ ),
+ )
return make_result(
"skyvern_select_option",
ok=False,
@@ -1226,6 +1425,20 @@ async def skyvern_select_option(
return await _direct_failure_result(
"skyvern_select_option", ctx, timer, page, selector, e, action_timeout
)
+ if custom_attempt_ms:
+ timer.mark("total")
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=_add_timing_prefix(timer.timing_ms, custom_attempt_ms),
+ error=make_error(
+ code,
+ _exception_message(e),
+ "Check selector and available options",
+ details=_exception_details(e),
+ ),
+ )
return make_result(
"skyvern_select_option",
ok=False,
@@ -1250,6 +1463,13 @@ async def skyvern_select_option(
data["sdk_equivalent"] = f'await page.select_option(prompt="{intent}", value="{value}")'
elif selector:
data["sdk_equivalent"] = f'await page.select_option("{selector}", value="{value}")'
+ if custom_attempt_ms:
+ return make_result(
+ "skyvern_select_option",
+ browser_context=ctx,
+ data=data,
+ timing_ms=_add_timing_prefix(timer.timing_ms, custom_attempt_ms),
+ )
return make_result(
"skyvern_select_option",
browser_context=ctx,
diff --git a/tests/unit/_mcp_browser_fakes.py b/tests/unit/_mcp_browser_fakes.py
index a649b1ae3..dd0ab41e5 100644
--- a/tests/unit/_mcp_browser_fakes.py
+++ b/tests/unit/_mcp_browser_fakes.py
@@ -9,6 +9,7 @@ import pytest
from skyvern.cli.core.result import BrowserContext
from skyvern.cli.core.session_manager import SessionState
+from skyvern.core.script_generations.skyvern_page import SkyvernPage
def make_real_wait_for_timeout() -> AsyncMock:
@@ -75,7 +76,7 @@ def make_probe_locator(
def make_skyvern_page(page: MagicMock) -> MagicMock:
- wrapper = MagicMock()
+ wrapper = MagicMock(spec=SkyvernPage)
wrapper.page = page
wrapper.url = page.url
if "evaluate" in page.__dict__:
@@ -87,6 +88,35 @@ def make_skyvern_page(page: MagicMock) -> MagicMock:
return wrapper
+def make_select_option_page(*, locator_scope: Any | None = None) -> tuple[SimpleNamespace, AsyncMock]:
+ native_select_option = AsyncMock(return_value="selected")
+ raw_page = MagicMock()
+ # The credential-safety boundary probe reads whether the target is a password input.
+ probe = MagicMock()
+ probe.first = probe
+ probe.evaluate = AsyncMock(return_value=False)
+ probe.select_option = AsyncMock(return_value="selected")
+ raw_page.locator = MagicMock(return_value=probe)
+ page = SimpleNamespace(page=raw_page, select_option=native_select_option)
+ if locator_scope is not None:
+ if isinstance(locator_scope, MagicMock):
+ locator_scope.locator = MagicMock(return_value=probe)
+ page._locator_scope = locator_scope
+ return page, native_select_option
+
+
+def make_select_like_page(target: dict[str, Any]) -> tuple[MagicMock, MagicMock]:
+ control = MagicMock()
+ control.first = control
+ control.evaluate = AsyncMock(return_value=target)
+ control.click = AsyncMock()
+ control.fill = AsyncMock()
+ page = MagicMock()
+ page.evaluate = AsyncMock(return_value=[])
+ page.locator = MagicMock(return_value=control)
+ return page, control
+
+
def patch_get_page(monkeypatch: pytest.MonkeyPatch, module: Any, page: MagicMock, ctx: BrowserContext) -> AsyncMock:
mock = AsyncMock(return_value=(make_skyvern_page(page), ctx))
monkeypatch.setattr(module, "get_page", mock)
diff --git a/tests/unit/test_mcp_browser_tools.py b/tests/unit/test_mcp_browser_tools.py
index f91a0359b..cdeb04694 100644
--- a/tests/unit/test_mcp_browser_tools.py
+++ b/tests/unit/test_mcp_browser_tools.py
@@ -4,15 +4,29 @@ from __future__ import annotations
import asyncio
from types import SimpleNamespace
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, Mock, call
import pytest
+from skyvern.cli.core import browser_ops
+from skyvern.cli.core.browser_ops import (
+ CustomSelectClassifyError,
+ CustomSelectMatchError,
+ CustomSelectOpenError,
+ CustomSelectPasswordError,
+ do_select_option,
+)
from skyvern.cli.core.result import BrowserContext, set_concise_responses
from skyvern.cli.mcp_tools import browser as mcp_browser
from skyvern.cli.mcp_tools import mcp
from skyvern.client.errors import InternalServerError, UnprocessableEntityError
-from tests.unit._mcp_browser_fakes import make_probe_locator, make_real_wait_for_timeout
+from tests.unit._mcp_browser_fakes import (
+ make_probe_locator,
+ make_real_wait_for_timeout,
+ make_select_like_page,
+ make_select_option_page,
+ make_skyvern_page,
+)
@pytest.mark.asyncio
@@ -236,7 +250,8 @@ async def test_run_task_schema_description_demotes_autonomous_trial() -> None:
def _click_page(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
click = AsyncMock(return_value="#resolved")
- page = SimpleNamespace(click=click)
+ page = make_skyvern_page(MagicMock())
+ page.click = click
context = BrowserContext(mode="cloud_session", session_id="pbs_test")
monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
return click
@@ -293,6 +308,19 @@ async def test_skyvern_click_selector_is_resilient_by_default(monkeypatch: pytes
assert click.await_args.kwargs["_skip_element_prep"] is True
+async def test_skyvern_click_page_adapter_never_receives_private_kwarg(monkeypatch: pytest.MonkeyPatch) -> None:
+ click = AsyncMock(return_value="#resolved")
+ page = SimpleNamespace(page=MagicMock(), click=click)
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_click(selector="#submit")
+
+ assert result["ok"] is True
+ assert "_skip_element_prep" not in click.await_args.kwargs
+
+
@pytest.mark.asyncio
async def test_skyvern_click_selector_mode_direct_is_deterministic(monkeypatch: pytest.MonkeyPatch) -> None:
click = _click_page(monkeypatch)
@@ -640,8 +668,12 @@ async def test_skyvern_click_intent_only_uses_proactive_ai(monkeypatch: pytest.M
assert click.await_args.kwargs.get("mode") != "direct"
-def _action_page(monkeypatch: pytest.MonkeyPatch, **methods: AsyncMock) -> None:
- page = SimpleNamespace(**methods)
+def _action_page(monkeypatch: pytest.MonkeyPatch, *, skyvern_page: bool = False, **methods: AsyncMock) -> None:
+ page = make_skyvern_page(MagicMock()) if skyvern_page else SimpleNamespace(page=MagicMock())
+ if skyvern_page:
+ page.evaluate = AsyncMock(return_value=False)
+ for name, method in methods.items():
+ setattr(page, name, method)
context = BrowserContext(mode="cloud_session", session_id="pbs_test")
monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
@@ -676,11 +708,11 @@ def _native_option_page(
@pytest.mark.asyncio
async def test_skyvern_type_selector_is_resilient_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
fill = AsyncMock(return_value="Noor")
- _action_page(monkeypatch, fill=fill)
+ _action_page(monkeypatch, skyvern_page=True, fill=fill)
result = await mcp_browser.skyvern_type(selector="#first_name", text="Noor")
- assert result["ok"] is True
+ assert result["ok"] is True, result
assert fill.await_args.kwargs.get("mode") != "direct"
assert fill.await_args.kwargs["_skip_element_prep"] is True
@@ -703,14 +735,40 @@ async def test_skyvern_type_selector_only_append_skips_skyvern_page_prep(
monkeypatch: pytest.MonkeyPatch,
) -> None:
type_text = AsyncMock(return_value="Noor")
- _action_page(monkeypatch, type=type_text)
+ _action_page(monkeypatch, skyvern_page=True, type=type_text)
result = await mcp_browser.skyvern_type(selector="#first_name", text="Noor", clear=False)
- assert result["ok"] is True
+ assert result["ok"] is True, result
assert type_text.await_args.kwargs["_skip_element_prep"] is True
[email protected]("clear", [True, False], ids=["fill", "type"])
[email protected]("page_kind", ["adapter", "raw"])
+async def test_skyvern_type_page_adapter_never_receives_private_kwarg(
+ monkeypatch: pytest.MonkeyPatch,
+ clear: bool,
+ page_kind: str,
+) -> None:
+ action = AsyncMock(return_value="Noor")
+ method = "fill" if clear else "type"
+ if page_kind == "adapter":
+ _action_page(monkeypatch, **{method: action})
+ else:
+ page = MagicMock()
+ page.page = page
+ page.evaluate = AsyncMock(return_value=False)
+ setattr(page, method, action)
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_type(selector="#first_name", text="Noor", clear=clear)
+
+ assert result["ok"] is True
+ assert "_skip_element_prep" not in action.await_args.kwargs
+
+
@pytest.mark.asyncio
async def test_skyvern_type_selector_plus_intent_falls_back_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
fill = AsyncMock(return_value="Noor")
@@ -1010,6 +1068,1181 @@ async def test_skyvern_select_option_selector_mode_direct_is_deterministic(monke
assert select.await_args.kwargs["ai"] is None
+async def test_skyvern_select_option_routes_custom_widget_through_core_helper(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+ do_select_option = AsyncMock(return_value="Music")
+ monkeypatch.setattr(mcp_browser, "do_select_option", do_select_option, raising=False)
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category",
+ value="music",
+ selector_mode="direct",
+ timeout=4321,
+ )
+
+ assert result["ok"] is True
+ assert result["data"]["sdk_equivalent"] == (
+ "# No single SDK method -- open/filter '#category', then click exact observed option 'Music'"
+ )
+ do_select_option.assert_awaited_once_with(
+ page.page,
+ "#category",
+ "music",
+ by_label=False,
+ timeout=4321,
+ restore_value_on_failure=False,
+ fail_closed_on_unknown=False,
+ )
+ native_select_option.assert_not_awaited()
+
+
+async def test_skyvern_select_option_routes_custom_widget_through_working_frame(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ frame = MagicMock()
+ page, native_select_option = make_select_option_page(locator_scope=frame)
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+ custom_select = AsyncMock(return_value="Music")
+ monkeypatch.setattr(mcp_browser, "do_select_option", custom_select)
+
+ result = await mcp_browser.skyvern_select_option(selector="#category", value="music", timeout=4321)
+
+ assert result["ok"] is True
+ custom_select.assert_awaited_once_with(
+ frame,
+ "#category",
+ "music",
+ by_label=False,
+ timeout=4321,
+ restore_value_on_failure=False,
+ fail_closed_on_unknown=False,
+ )
+ native_select_option.assert_not_awaited()
+
+
+async def test_do_select_option_keeps_native_select_on_existing_path() -> None:
+ page, control = make_select_like_page({"tag": "select", "role": "combobox", "haspopup": False, "editable": False})
+
+ result = await do_select_option(page, "#region", "east", timeout=1)
+
+ assert result is None
+ control.click.assert_not_awaited()
+
+
+async def test_do_select_option_defers_password_input_without_mutating_it() -> None:
+ page, control = make_select_like_page(
+ {
+ "tag": "input",
+ "type": "password",
+ "isPassword": True,
+ "role": "textbox",
+ "haspopup": False,
+ # Defense in depth must reject even a bad classifier payload.
+ "editable": True,
+ }
+ )
+
+ with pytest.raises(CustomSelectPasswordError):
+ await do_select_option(page, "#secret", "hunter2", timeout=100)
+
+ # Only the classification probe ran — no fill/click, value untouched.
+ assert control.evaluate.await_count == 1
+ control.fill.assert_not_awaited()
+ control.fill.assert_not_awaited()
+ control.click.assert_not_awaited()
+ page.evaluate.assert_not_awaited()
+
+
+ "target",
+ [
+ {"tag": "div", "role": "combobox", "haspopup": False, "editable": False},
+ {"tag": "div", "role": "listbox", "haspopup": False, "editable": False},
+ {"tag": "button", "role": "", "haspopup": True, "editable": False},
+ ],
+)
+async def test_do_select_option_recognizes_aria_custom_selects(
+ monkeypatch: pytest.MonkeyPatch,
+ target: dict[str, object],
+) -> None:
+ page, control = make_select_like_page(target)
+ dom_options = [{"selector": "#music", "role": "option", "name": "Music"}]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_options))
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#music", "label": "Music", "value": "music"}],
+ {"text": "Select", "value": "", "dataValues": [""], "expanded": "true", "optionSelected": False},
+ {"text": "Music", "value": "", "dataValues": ["music"], "expanded": "false", "optionSelected": False},
+ ]
+
+ result = await do_select_option(page, "#category", "music", timeout=100)
+
+ assert result == "Music"
+ assert control.click.await_count == 2
+
+
+async def test_do_select_option_scan_observed_control_uses_widened_shape(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {
+ "tag": "button",
+ "role": "",
+ "haspopup": False,
+ "editable": False,
+ "selectlike": False,
+ "optionish": True,
+ "related": False,
+ }
+ page, control = make_select_like_page(target)
+ dom_options = [
+ {"selector": "#category", "role": "button", "name": "Category"},
+ {"selector": "#music", "role": "option", "name": "Music"},
+ ]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_options))
+ control.evaluate.side_effect = [
+ target,
+ True,
+ [{"selector": "#music", "label": "Music", "value": "music"}],
+ {"text": "Select", "value": "", "dataValues": [""], "expanded": "true", "optionSelected": False},
+ {"text": "Music", "value": "", "dataValues": ["music"], "expanded": "false", "optionSelected": False},
+ ]
+
+ result = await do_select_option(page, "#category", "music", timeout=100)
+
+ assert result == "Music"
+
+
+async def test_do_select_option_matches_observed_accessible_name(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "button", "role": "combobox", "haspopup": False, "editable": False}
+ page, control = make_select_like_page(target)
+ dom_options = [{"selector": "#us", "role": "option", "name": "United States"}]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_options))
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#us", "label": "US", "value": "us"}],
+ {"text": "Choose", "value": "", "dataValues": [""], "expanded": "true", "optionSelected": False},
+ {"text": "US", "value": "", "dataValues": ["us"], "expanded": "false", "optionSelected": False},
+ ]
+
+ result = await do_select_option(page, "#country", "United States", by_label=True, timeout=100)
+
+ assert result == "United States"
+
+
+async def test_do_select_option_rejects_substring_value_false_commit(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "button", "role": "combobox", "haspopup": False, "editable": False}
+ page, control = make_select_like_page(target)
+ dom_options = [{"selector": "#oregon", "role": "option", "name": "OR"}]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_options))
+ before = {
+ "text": "Choose OR state",
+ "value": "",
+ "dataValues": ["north"],
+ "expanded": "true",
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#oregon", "label": "OR", "value": "OR"}],
+ before,
+ {**before, "expanded": "false"},
+ ]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="did not commit 'OR'"):
+ await do_select_option(page, "#state", "or", timeout=100)
+
+
+async def test_do_select_option_accepts_idempotent_exact_committed_value(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "button", "role": "combobox", "haspopup": False, "editable": False}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#oregon", "role": "option", "name": "OR"}]),
+ )
+ committed = {
+ "text": "Oregon",
+ "value": "OR",
+ "dataValues": [],
+ "expanded": "false",
+ "optionVisible": False,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#oregon", "label": "OR", "value": "OR"}],
+ committed,
+ committed,
+ ]
+
+ assert await do_select_option(page, "#state", "or", timeout=100) == "OR"
+ assert control.click.await_count == 2
+ assert control.evaluate.await_count == 4
+
+
+async def test_do_select_option_rejects_toggle_deselect_of_requested_value(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "button", "role": "combobox", "haspopup": False, "editable": False}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#oregon", "role": "option", "name": "OR"}]),
+ )
+ # Coincidental static data-value="OR" that never changes, while the matched option stays
+ # present and its aria-selected flips true->false — the deselection veto must reject.
+ before = {
+ "text": "OR",
+ "value": "",
+ "dataValue": "OR",
+ "expanded": "true",
+ "optionVisible": True,
+ "optionPresent": True,
+ "optionSelected": True,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#oregon", "label": "OR", "value": "OR"}],
+ before,
+ {**before, "optionVisible": False, "optionPresent": True, "optionSelected": False},
+ ]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="did not commit 'OR'"):
+ await do_select_option(page, "#state", "or", timeout=100)
+
+
+async def test_do_select_option_ignores_unrelated_stable_data_attribute(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "button", "role": "combobox", "haspopup": False, "editable": False}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#oregon", "role": "option", "name": "OR"}]),
+ )
+ before = {
+ "text": "Choose state",
+ "value": "",
+ "dataValue": "",
+ "dataValues": ["OR"],
+ "expanded": "true",
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#oregon", "label": "OR", "value": "OR"}],
+ before,
+ {**before, "optionVisible": False},
+ ]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="did not commit 'OR'"):
+ await do_select_option(page, "#state", "or", timeout=100)
+
+
[email protected]("editable", [False, True])
+async def test_do_select_option_uses_writable_target_action(
+ monkeypatch: pytest.MonkeyPatch,
+ editable: bool,
+) -> None:
+ target = {"tag": "input", "role": "combobox", "haspopup": True, "editable": editable}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#west", "role": "option", "name": "West"}]),
+ )
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#west", "label": "West", "value": "west"}],
+ {"text": "", "value": "", "dataValues": [], "expanded": "true", "optionSelected": False},
+ {"text": "West", "value": "west", "dataValues": [], "expanded": "false", "optionSelected": False},
+ ]
+
+ assert await do_select_option(page, "#state", "west", timeout=100) == "West"
+ assert control.fill.await_count == int(editable)
+
+
+async def test_do_select_option_scan_observed_bare_input_uses_typeahead(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "input", "role": "textbox", "haspopup": False, "editable": True, "selectlike": False}
+ page, control = make_select_like_page(target)
+ dom_elements = [{"selector": "#town", "role": "textbox", "name": "Town"}]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_elements))
+ monkeypatch.setattr(
+ browser_ops,
+ "_scoped_custom_options",
+ AsyncMock(return_value=[{"selector": "#fairview", "role": "option", "name": "Fairview", "label": "Fairview"}]),
+ )
+ control.evaluate.side_effect = [
+ target,
+ True,
+ {"text": "", "value": "Fairview", "dataValues": [], "expanded": None, "optionSelected": False},
+ {"text": "", "value": "Fairview", "dataValues": [], "expanded": None, "optionSelected": True},
+ ]
+
+ assert await do_select_option(page, "#town", "Fairview", timeout=100) == "Fairview"
+ control.fill.assert_awaited_once_with("Fairview", timeout=100)
+
+
+async def test_do_select_option_bare_input_rejects_preexisting_neighbor_option(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {
+ "tag": "input",
+ "role": "textbox",
+ "haspopup": False,
+ "editable": True,
+ "selectlike": False,
+ "related": False,
+ }
+ page, control = make_select_like_page(target)
+ dom_elements = [
+ {"selector": "#town", "role": "textbox", "name": "Town"},
+ {"selector": "#neighbor-fairview", "role": "option", "name": "Fairview"},
+ ]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_elements))
+ scoped_options = AsyncMock(return_value=[])
+ monkeypatch.setattr(browser_ops, "_scoped_custom_options", scoped_options)
+ control.evaluate.side_effect = [target, True]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(CustomSelectMatchError):
+ await do_select_option(page, "#town", "Fairview", timeout=100)
+
+ assert scoped_options.await_args.kwargs["before_option_selectors"] == {"#neighbor-fairview"}
+ assert scoped_options.await_args.kwargs["bare_input"] is True
+ control.fill.assert_awaited_once_with("Fairview", timeout=100)
+ assert control.click.await_count == 0
+
+
+async def test_do_select_option_bare_input_fill_value_does_not_verify_commit(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {
+ "tag": "input",
+ "role": "textbox",
+ "haspopup": False,
+ "editable": True,
+ "selectlike": False,
+ "related": False,
+ }
+ page, control = make_select_like_page(target)
+ dom_elements = [{"selector": "#town", "role": "textbox", "name": "Town"}]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_elements))
+ monkeypatch.setattr(
+ browser_ops,
+ "_scoped_custom_options",
+ AsyncMock(return_value=[{"selector": "#fairview", "role": "option", "name": "Fairview"}]),
+ )
+ before = {
+ "text": "Searching",
+ "value": "Fairview",
+ "dataValues": [],
+ "expanded": None,
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [target, True, before, {**before, "text": "Idle"}]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="did not commit 'Fairview'"):
+ await do_select_option(page, "#town", "Fairview", timeout=100)
+
+
+async def test_do_select_option_editable_list_close_requires_absent_container_channels(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "input", "role": "combobox", "haspopup": True, "editable": True}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#lakewood", "role": "option", "name": "Lakewood"}]),
+ )
+ before = {
+ "text": "",
+ "value": "Lakewood",
+ "dataValue": "",
+ "dataValues": [],
+ "containerChannels": [{"key": "#city-value:value", "value": ""}],
+ "expanded": "true",
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#lakewood", "label": "Lakewood", "value": "Lakewood"}],
+ before,
+ {**before, "expanded": "false", "optionVisible": False},
+ ]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="did not commit 'Lakewood'"):
+ await do_select_option(page, "#city", "Lakewood", timeout=100)
+
+
[email protected]("committed_value", ["Lakewood", "city-123"], ids=["requested", "matched-option-value"])
+async def test_do_select_option_accepts_editable_container_channel_transition(
+ monkeypatch: pytest.MonkeyPatch,
+ committed_value: str,
+) -> None:
+ target = {"tag": "input", "role": "combobox", "haspopup": True, "editable": True}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#lakewood", "role": "option", "name": "Lakewood"}]),
+ )
+ before = {
+ "text": "",
+ "value": "Lakewood",
+ "dataValue": "",
+ "dataValues": [],
+ "containerChannels": [{"key": "#city-value:value", "value": ""}],
+ "expanded": "true",
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#lakewood", "label": "Lakewood", "value": committed_value}],
+ before,
+ {
+ **before,
+ "containerChannels": [{"key": "#city-value:value", "value": committed_value}],
+ },
+ ]
+
+ assert await do_select_option(page, "#city", "Lakewood", by_label=True, timeout=100) == "Lakewood"
+
+
+async def test_do_select_option_rejects_new_unrelated_container_channel(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "input", "role": "combobox", "haspopup": True, "editable": True}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#lakewood", "role": "option", "name": "Lakewood"}]),
+ )
+ before = {
+ "text": "",
+ "value": "Lakewood",
+ "dataValue": "",
+ "dataValues": [],
+ "containerChannels": [{"key": "input:hidden:city:value", "value": ""}],
+ "expanded": "true",
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#lakewood", "label": "Lakewood", "value": "Lakewood"}],
+ before,
+ {
+ **before,
+ "containerChannels": [
+ {"key": "input:hidden:city:value", "value": ""},
+ {"key": "#city-widget:data-loading", "value": "true"},
+ ],
+ "expanded": "false",
+ "optionVisible": False,
+ },
+ ]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="did not commit 'Lakewood'"):
+ await do_select_option(page, "#city", "Lakewood", timeout=100)
+
+
+async def test_do_select_option_keeps_editable_list_close_as_channel_free_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {"tag": "input", "role": "combobox", "haspopup": True, "editable": True}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#lakewood", "role": "option", "name": "Lakewood"}]),
+ )
+ before = {
+ "text": "",
+ "value": "Lakewood",
+ "dataValue": "",
+ "dataValues": [],
+ "containerChannels": [],
+ "expanded": "true",
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#lakewood", "label": "Lakewood", "value": "Lakewood"}],
+ before,
+ {**before, "expanded": "false", "optionVisible": False},
+ ]
+
+ assert await do_select_option(page, "#city", "Lakewood", timeout=100) == "Lakewood"
+
+
[email protected]("bare_input", [False, True], ids=["aria", "bare"])
+async def test_do_select_option_retries_editable_with_real_key_events_when_fill_has_no_options(
+ monkeypatch: pytest.MonkeyPatch,
+ bare_input: bool,
+) -> None:
+ target = {
+ "tag": "input",
+ "role": "textbox" if bare_input else "combobox",
+ "haspopup": not bare_input,
+ "editable": True,
+ "selectlike": False,
+ "related": not bare_input,
+ }
+ page, control = make_select_like_page(target)
+ control.press_sequentially = AsyncMock()
+ dom_elements = [{"selector": "#city", "role": target["role"], "name": "City"}]
+ observe = AsyncMock(return_value=dom_elements)
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", observe)
+ option = {"selector": "#lakewood", "role": "option", "name": "Lakewood", "label": "Lakewood"}
+ scoped_options = AsyncMock(side_effect=[[], [], [], [option]])
+ monkeypatch.setattr(browser_ops, "_scoped_custom_options", scoped_options)
+ before = {
+ "text": "",
+ "value": "Lakewood",
+ "dataValue": "",
+ "dataValues": [],
+ "containerChannels": [],
+ "expanded": "true",
+ "optionVisible": True,
+ "optionSelected": False,
+ }
+ evaluate_results: list[object] = [target]
+ if bare_input:
+ evaluate_results.append(True)
+ evaluate_results.extend([before, {**before, "optionSelected": True}])
+ control.evaluate.side_effect = evaluate_results
+ monkeypatch.setattr(
+ browser_ops,
+ "time",
+ SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 0.5, 1.01, 1.02, 1.03])),
+ )
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ assert await do_select_option(page, "#city", "Lakewood", timeout=2000) == "Lakewood"
+ assert control.fill.await_args_list == [call("Lakewood", timeout=2000), call("", timeout=2000)]
+ control.press_sequentially.assert_awaited_once_with("Lakewood", timeout=2000)
+ assert observe.await_count == (2 if bare_input else 1)
+
+
+async def test_do_select_option_retry_failure_restores_original_value(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {
+ "tag": "input",
+ "role": "combobox",
+ "haspopup": True,
+ "editable": True,
+ "related": True,
+ }
+ page, control = make_select_like_page(target)
+ control.press_sequentially = AsyncMock(side_effect=RuntimeError("keydown failed"))
+ control.evaluate.side_effect = [target, "Original city", "Original city"]
+ monkeypatch.setattr(browser_ops, "_scoped_custom_options", AsyncMock(side_effect=[[], []]))
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=[]))
+ monkeypatch.setattr(
+ browser_ops,
+ "time",
+ SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 1.01])),
+ )
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(CustomSelectOpenError, match="keydown failed"):
+ await do_select_option(
+ page,
+ "#city",
+ "Lakewood",
+ timeout=2000,
+ restore_value_on_failure=True,
+ )
+
+ assert control.fill.await_args_list == [
+ call("Lakewood", timeout=2000),
+ call("", timeout=2000),
+ call("Original city", timeout=1000),
+ ]
+
+
+async def test_do_select_option_retry_restore_failure_is_terminal(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {
+ "tag": "input",
+ "role": "combobox",
+ "haspopup": True,
+ "editable": True,
+ "related": True,
+ }
+ page, control = make_select_like_page(target)
+ control.press_sequentially = AsyncMock(side_effect=RuntimeError("keydown failed"))
+ control.fill.side_effect = [None, None, RuntimeError("restore blocked")]
+ control.evaluate.side_effect = [target, "Original city"]
+ monkeypatch.setattr(browser_ops, "_scoped_custom_options", AsyncMock(side_effect=[[], []]))
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=[]))
+ monkeypatch.setattr(
+ browser_ops,
+ "time",
+ SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 1.01])),
+ )
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(browser_ops.CustomSelectRestoreError, match="restore original value"):
+ await do_select_option(
+ page,
+ "#city",
+ "Lakewood",
+ timeout=2000,
+ restore_value_on_failure=True,
+ )
+
+
+async def test_scoped_custom_options_scans_all_owned_roots(monkeypatch: pytest.MonkeyPatch) -> None:
+ page = MagicMock()
+ control = MagicMock()
+ control.evaluate = AsyncMock(return_value=[{"selector": "#second-option", "label": "Second", "value": "second"}])
+ observe = AsyncMock(
+ side_effect=[
+ [],
+ [{"selector": "#second-option", "role": "option", "name": "Second"}],
+ ]
+ )
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", observe)
+
+ options = await browser_ops._scoped_custom_options(
+ page,
+ control,
+ scan_selectors=["#first-root", "#second-root"],
+ )
+
+ assert options == [
+ {"selector": "#second-option", "role": "option", "name": "Second", "label": "Second", "value": "second"}
+ ]
+ assert [item.args[1] for item in observe.await_args_list] == ["#first-root", "#second-root"]
+
+
+async def test_do_select_option_surfaces_option_click_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+ target = {"tag": "button", "role": "combobox", "haspopup": True, "editable": False}
+ page, control = make_select_like_page(target)
+ monkeypatch.setattr(
+ browser_ops,
+ "_get_dom_observe_elements",
+ AsyncMock(return_value=[{"selector": "#west", "role": "option", "name": "West"}]),
+ )
+ control.evaluate.side_effect = [
+ target,
+ [{"selector": "#west", "label": "West", "value": "west"}],
+ {"text": "Choose", "value": "", "dataValues": [], "expanded": "true", "optionSelected": False},
+ ]
+ control.click.side_effect = [None, RuntimeError("click intercepted by overlay")]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 1])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ with pytest.raises(RuntimeError, match="click intercepted by overlay"):
+ await do_select_option(page, "#state", "west", timeout=100)
+
+
+async def test_do_select_option_scan_observed_control_without_options_uses_bounded_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = {
+ "tag": "button",
+ "role": "",
+ "haspopup": False,
+ "editable": False,
+ "selectlike": True,
+ "optionish": False,
+ "related": True,
+ }
+ page, control = make_select_like_page(target)
+ dom_elements = [{"selector": "#empty", "role": "button", "name": "Empty"}]
+ monkeypatch.setattr(browser_ops, "_get_dom_observe_elements", AsyncMock(return_value=dom_elements))
+ scoped_options = AsyncMock(return_value=[])
+ monkeypatch.setattr(browser_ops, "_scoped_custom_options", scoped_options)
+ control.evaluate.side_effect = [target, True]
+ monkeypatch.setattr(browser_ops, "time", SimpleNamespace(monotonic=Mock(side_effect=[0, 0, 4])))
+ monkeypatch.setattr(browser_ops, "asyncio", SimpleNamespace(sleep=AsyncMock()))
+
+ result = await do_select_option(page, "#empty", "anything", timeout=30000)
+
+ assert result is None
+ scoped_options.assert_awaited_once()
+
+
+async def test_skyvern_select_option_no_match_preserves_structured_option_list(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+ observed_options = ["Books", "Music", "Games"]
+ monkeypatch.setattr(
+ mcp_browser,
+ "do_select_option",
+ AsyncMock(side_effect=CustomSelectMatchError("#category", "podcasts", observed_options)),
+ raising=False,
+ )
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category",
+ value="podcasts",
+ selector_mode="direct",
+ timeout=4321,
+ )
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.ACTION_FAILED
+ assert result["error"]["details"] == {
+ "element_state": "no_unambiguous_match",
+ "selector": "#category",
+ "requested_option": "podcasts",
+ "observed_options": observed_options,
+ }
+ assert result["error"]["hint"]
+ native_select_option.assert_not_awaited()
+
+
+async def test_skyvern_select_option_custom_failure_preserves_hybrid_ai_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(
+ mcp_browser,
+ "do_select_option",
+ AsyncMock(side_effect=CustomSelectMatchError("#category", "podcasts", ["Music"])),
+ )
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="podcasts"
+ )
+
+ assert result["ok"] is True
+ native_select_option.assert_awaited_once_with(
+ selector="#category", value="podcasts", prompt="the category dropdown", ai="fallback", timeout=30000
+ )
+
+
+async def test_skyvern_select_option_kill_switch_skips_custom_path(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ do_select = AsyncMock(side_effect=AssertionError("custom path must not run when disabled"))
+ monkeypatch.setattr(mcp_browser, "do_select_option", do_select)
+ monkeypatch.setenv("SKYVERN_DISABLE_CUSTOM_SELECT", "1")
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="music"
+ )
+
+ assert result["ok"] is True
+ do_select.assert_not_awaited()
+ native_select_option.assert_awaited_once()
+
+
+async def test_skyvern_select_option_open_failure_preserves_hybrid_ai_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(
+ mcp_browser,
+ "do_select_option",
+ AsyncMock(side_effect=CustomSelectOpenError("click intercepted")),
+ )
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="music"
+ )
+
+ assert result["ok"] is True
+ native_select_option.assert_awaited_once()
+
+
+async def test_skyvern_select_option_open_failure_terminal_for_direct_calls(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(
+ mcp_browser,
+ "do_select_option",
+ AsyncMock(side_effect=CustomSelectOpenError("click intercepted")),
+ )
+
+ result = await mcp_browser.skyvern_select_option(selector="#category", value="music", selector_mode="direct")
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.ACTION_FAILED
+ assert result["error"]["message"] == "click intercepted"
+ native_select_option.assert_not_awaited()
+
+
+async def test_do_select_option_open_click_failure_raises_open_error() -> None:
+ page, control = make_select_like_page({"tag": "div", "role": "combobox", "haspopup": True, "editable": False})
+ control.click = AsyncMock(side_effect=RuntimeError("intercepted"))
+
+ with pytest.raises(CustomSelectOpenError):
+ await do_select_option(page, "#x", "music", timeout=500)
+
+
+async def test_skyvern_select_option_credential_intent_rejected_before_session(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ get_page = AsyncMock(side_effect=AssertionError("get_page must not run for a credential intent"))
+ monkeypatch.setattr(mcp_browser, "get_page", get_page)
+
+ result = await mcp_browser.skyvern_select_option(intent="select the account password", value="s3cr3t")
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT
+ get_page.assert_not_awaited()
+
+
+async def test_skyvern_select_option_classify_error_fails_closed_for_hybrid(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(mcp_browser, "do_select_option", AsyncMock(side_effect=CustomSelectClassifyError("#x")))
+
+ # Hybrid selector+intent: a mid-probe detach must not forward the value to the AI fallback.
+ hybrid = await mcp_browser.skyvern_select_option(selector="#x", intent="the dropdown", value="leak-me")
+ assert hybrid["ok"] is False
+ assert hybrid["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT
+ native_select_option.assert_not_awaited()
+
+ # Direct call defers to the native SDK (which cannot forward the value to an LLM).
+ monkeypatch.setattr(mcp_browser, "do_select_option", AsyncMock(side_effect=CustomSelectClassifyError("#x")))
+ direct = await mcp_browser.skyvern_select_option(selector="#x", value="east", selector_mode="direct")
+ assert direct["ok"] is True
+ native_select_option.assert_awaited()
+
+
+async def test_skyvern_select_option_password_target_never_reaches_native_or_ai(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(
+ mcp_browser,
+ "do_select_option",
+ AsyncMock(side_effect=CustomSelectPasswordError("#pw")),
+ )
+
+ # Non-credential intent so this exercises the do_select_option CustomSelectPasswordError
+ # wrapper (a password TARGET), not the earlier credential-intent preflight.
+ result = await mcp_browser.skyvern_select_option(selector="#pw", intent="the flavor dropdown", value="s3cr3t")
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT
+ native_select_option.assert_not_awaited()
+
+
+async def test_skyvern_select_option_post_option_failure_skips_hybrid_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ do_select = AsyncMock(side_effect=RuntimeError("Custom select did not commit 'podcasts'"))
+ monkeypatch.setattr(mcp_browser, "do_select_option", do_select)
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="podcasts"
+ )
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.ACTION_FAILED
+ assert result["error"]["message"] == "Custom select did not commit 'podcasts'"
+ native_select_option.assert_not_awaited()
+ assert do_select.await_args.kwargs["restore_value_on_failure"] is True
+
+
+async def test_skyvern_select_option_restore_failure_skips_hybrid_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, native_select_option = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(
+ mcp_browser,
+ "do_select_option",
+ AsyncMock(side_effect=browser_ops.CustomSelectRestoreError("Could not restore original value")),
+ )
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="podcasts"
+ )
+
+ assert result["ok"] is False
+ assert result["error"]["message"] == "Could not restore original value"
+ native_select_option.assert_not_awaited()
+
+
+async def test_skyvern_select_option_direct_call_does_not_request_value_restore(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ page, _ = make_select_option_page()
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ do_select = AsyncMock(return_value="Music")
+ monkeypatch.setattr(mcp_browser, "do_select_option", do_select)
+
+ result = await mcp_browser.skyvern_select_option(selector="#category", value="music", selector_mode="direct")
+
+ assert result["ok"] is True
+ assert do_select.await_args.kwargs["restore_value_on_failure"] is False
+
+
[email protected]("disable_custom", [False, True], ids=["classifier-none", "kill-switch"])
+async def test_skyvern_select_option_pure_native_timing_matches_origin(
+ monkeypatch: pytest.MonkeyPatch,
+ disable_custom: bool,
+) -> None:
+ class FakeTimer:
+ clock_ms = 0
+
+ def __init__(self) -> None:
+ self.started_ms = 0
+ self.marks: dict[str, int] = {}
+
+ def __enter__(self) -> FakeTimer:
+ self.started_ms = self.clock_ms
+ return self
+
+ def __exit__(self, *_args: object) -> None:
+ self.marks["total"] = self.clock_ms - self.started_ms
+
+ def mark(self, name: str) -> None:
+ self.marks[name] = self.clock_ms - self.started_ms
+
+ @property
+ def timing_ms(self) -> dict[str, int]:
+ return self.marks.copy()
+
+ async def classify_native(*_args: object, **_kwargs: object) -> None:
+ FakeTimer.clock_ms += 100
+ return None
+
+ async def select_native(*_args: object, **_kwargs: object) -> str:
+ FakeTimer.clock_ms += 200
+ return "east"
+
+ page, _ = make_select_option_page()
+ page.select_option = AsyncMock(side_effect=select_native)
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ custom_select = AsyncMock(side_effect=classify_native)
+ monkeypatch.setattr(mcp_browser, "do_select_option", custom_select)
+ monkeypatch.setattr(mcp_browser, "Timer", FakeTimer)
+ if disable_custom:
+ monkeypatch.setenv("SKYVERN_DISABLE_CUSTOM_SELECT", "1")
+ else:
+ monkeypatch.delenv("SKYVERN_DISABLE_CUSTOM_SELECT", raising=False)
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#region",
+ value="east",
+ selector_mode="direct",
+ )
+
+ assert result["ok"] is True
+ assert result["timing_ms"] == {"sdk": 200, "total": 200}
+
+ async def reject_native(*_args: object, **_kwargs: object) -> None:
+ FakeTimer.clock_ms += 200
+ raise RuntimeError("invalid native option")
+
+ FakeTimer.clock_ms = 0
+ page.select_option = AsyncMock(side_effect=reject_native)
+ failed = await mcp_browser.skyvern_select_option(
+ selector="#region",
+ value="missing",
+ selector_mode="direct",
+ )
+
+ assert failed["ok"] is False
+ assert failed["timing_ms"] == {}
+ if disable_custom:
+ custom_select.assert_not_awaited()
+ else:
+ assert custom_select.await_count == 2
+
+
+async def test_skyvern_select_option_hybrid_timing_includes_custom_attempt(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ class FakeTimer:
+ clock_ms = 0
+
+ def __init__(self) -> None:
+ self.started_ms = 0
+ self.marks: dict[str, int] = {}
+
+ def __enter__(self) -> FakeTimer:
+ self.started_ms = self.clock_ms
+ return self
+
+ def __exit__(self, *_args: object) -> None:
+ self.marks["total"] = self.clock_ms - self.started_ms
+
+ def mark(self, name: str) -> None:
+ self.marks[name] = self.clock_ms - self.started_ms
+
+ @property
+ def timing_ms(self) -> dict[str, int]:
+ return self.marks.copy()
+
+ async def fail_custom(*_args: object, **_kwargs: object) -> None:
+ FakeTimer.clock_ms += 100
+ raise CustomSelectMatchError("#category", "podcasts", ["Music"])
+
+ async def select_fallback(*_args: object, **_kwargs: object) -> str:
+ FakeTimer.clock_ms += 200
+ return "podcasts"
+
+ page, _ = make_select_option_page()
+ page.select_option = AsyncMock(side_effect=select_fallback)
+ monkeypatch.setattr(
+ mcp_browser,
+ "get_page",
+ AsyncMock(return_value=(page, BrowserContext(mode="cloud_session", session_id="pbs_test"))),
+ )
+ monkeypatch.setattr(mcp_browser, "do_select_option", AsyncMock(side_effect=fail_custom))
+ monkeypatch.setattr(mcp_browser, "Timer", FakeTimer)
+
+ result = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="podcasts"
+ )
+
+ assert result["ok"] is True
+ assert result["timing_ms"]["total"] == 300
+
+ async def fail_fallback(*_args: object, **_kwargs: object) -> None:
+ FakeTimer.clock_ms += 200
+ raise RuntimeError("fallback failed")
+
+ FakeTimer.clock_ms = 0
+ page.select_option = AsyncMock(side_effect=fail_fallback)
+ failed = await mcp_browser.skyvern_select_option(
+ selector="#category", intent="the category dropdown", value="podcasts"
+ )
+
+ assert failed["ok"] is False
+ assert failed["timing_ms"]["total"] == 300
+
+
@pytest.mark.asyncio
async def test_skyvern_select_option_intent_only_uses_proactive_ai(monkeypatch: pytest.MonkeyPatch) -> None:
select = AsyncMock(return_value="us")