Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Clarify MCP tool descriptions to fix wrong-tool routing errors (#7333)
Aaron Perez8bacea6ec0a5
diff --git a/skyvern/cli/mcp_tools/__init__.py b/skyvern/cli/mcp_tools/__init__.pyindex a9aae2ca5..d3c176266 100644--- a/skyvern/cli/mcp_tools/__init__.py+++ b/skyvern/cli/mcp_tools/__init__.py@@ -295,6 +295,15 @@ Precision tools support intent (AI), selector (deterministic), or hybrid (both)- console_messages and network_requests capture events from session start — call anytime.- Workflow, schedule, credential, script, folder, and block tools do NOT need a browser session.- schedule_create requires an existing workflow_permanent_id — call workflow_list or workflow_create first.+- get_html reads an element by selector on the CURRENT page — navigate first; there is no fetch-HTML-by-URL.+- workflow_get and workflow_run need a KNOWN workflow_permanent_id (wpid_); run starts a NEW run. To \+search, browse, or paginate workflows use workflow_list — do NOT pass query/search/page/only_workflows \+to workflow_get or workflow_create. To re-run an existing run, use workflow_retry with its workflow_run_id (wr_).+- workflow_create/update take the ENTIRE workflow serialized into `definition` (title, blocks, and \+parameters all inside); flat top-level fields are rejected.+- browser_session_create MAKES a new session and takes no session_id/url/steps/selector — load a url with \+navigate, run steps with execute, using the returned session_id. session_list returns ALL sessions (no pagination).+- block_schema takes a block_type string only (no definition/format); validate a full block with block_validate(block_json=...).## Session Lifecyclediff --git a/skyvern/cli/mcp_tools/blocks.py b/skyvern/cli/mcp_tools/blocks.pyindex c8e2e593f..5dff4dfeb 100644--- a/skyvern/cli/mcp_tools/blocks.py+++ b/skyvern/cli/mcp_tools/blocks.py@@ -403,7 +403,11 @@ async def skyvern_block_schema(),] = None,) -> dict[str, Any]:- """Get the schema for a workflow block type, or list all available types if block_type is omitted."""+ """Get the schema for a workflow block type, or list all available types if block_type is omitted.++ Accepts ONLY a block_type string (e.g. 'navigation'); it does NOT accept a block definition or a+ format argument. To check a full block definition you have authored, use skyvern_block_validate+ (block_json=...) instead."""action = "skyvern_block_schema"@@ -490,7 +494,9 @@ async def skyvern_block_validate(Field(description="When true, structurally reject non-code browser/page block types (code-only mode)"),] = False,) -> dict[str, Any]:- """Validate a workflow block definition before using it in skyvern_workflow_create. Returns field-level errors."""+ """Validate a single workflow block definition (pass it as a JSON string in block_json) before using+ it in skyvern_workflow_create. Returns field-level errors. To look up the schema or fields for a+ block type first, use skyvern_block_schema(block_type=...)."""action = "skyvern_block_validate"try:diff --git a/skyvern/cli/mcp_tools/inspection.py b/skyvern/cli/mcp_tools/inspection.pyindex c09c12083..09979bd56 100644--- a/skyvern/cli/mcp_tools/inspection.py+++ b/skyvern/cli/mcp_tools/inspection.py@@ -767,7 +767,10 @@ async def skyvern_get_html(session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,) -> dict[str, Any]:- """Get HTML content of a DOM element. Returns innerHTML by default; set outer=true for outerHTML."""+ """Get HTML content of a DOM element identified by `selector` on the CURRENT page. Returns innerHTML+ by default; set outer=true for outerHTML. This does NOT accept a url and cannot fetch HTML by URL —+ to read a page you have not opened yet, navigate there first with skyvern_navigate(url=...), then+ call this with a selector."""from skyvern.cli.core.browser_ops import do_get_htmltry:diff --git a/skyvern/cli/mcp_tools/session.py b/skyvern/cli/mcp_tools/session.pyindex f2bb6a13e..63997390d 100644--- a/skyvern/cli/mcp_tools/session.py+++ b/skyvern/cli/mcp_tools/session.py@@ -102,6 +102,11 @@ async def skyvern_browser_session_create() -> dict[str, Any]:"""Create a new browser session to start interacting with websites. Cloud session results include app_url to watch the run live. Creates a cloud-hosted browser by default with geographic proxy support. This must be called before using any browser tools (navigate, click, extract, etc.).+ This tool CREATES a new session and returns its id; it takes no session_id, url, steps, or selector.+ To load a URL, run a sequence of steps, or act on an EXISTING session, first create the session, then+ call skyvern_navigate(url=..., session_id=...), skyvern_execute(steps=[...], session_id=...), or the+ click/type tools with that session_id.+Use local=true for a local Chromium instance.The session persists across tool calls until explicitly closed."""@@ -381,7 +386,8 @@ async def skyvern_browser_session_close(async def skyvern_browser_session_list() -> dict[str, Any]:- """List all active browser sessions. Use to find available sessions to connect to."""+ """List all active browser sessions. Use to find available sessions to connect to. Returns every+ active session in one call — it takes no arguments and does not paginate (no page/page_size)."""with Timer() as timer:try:skyvern = get_skyvern()diff --git a/skyvern/cli/mcp_tools/workflow.py b/skyvern/cli/mcp_tools/workflow.pyindex b75bc7314..76b8bfff9 100644--- a/skyvern/cli/mcp_tools/workflow.py+++ b/skyvern/cli/mcp_tools/workflow.py@@ -1239,8 +1239,12 @@ async def skyvern_workflow_get(workflow_id: Annotated[str, "Workflow permanent ID (starts with wpid_)"],version: Annotated[int | None, "Specific version to retrieve (latest if omitted)"] = None,) -> dict[str, Any]:- """Get the full definition of a specific workflow. Use when you need to inspect a workflow's- blocks, parameters, and configuration before running or updating it."""+ """Get the full definition of ONE workflow by its known workflow_id (wpid_...). Use to inspect a+ workflow's blocks, parameters, and configuration before running or updating it.++ This fetches a single workflow by id only — it does NOT search, browse, or paginate, and rejects+ arguments like query/search/page/page_size/only_workflows. To find a workflow by name or see what+ exists, call skyvern_workflow_list first, then pass the returned workflow_id here."""if err := validate_workflow_id(workflow_id, "skyvern_workflow_get"):return err@@ -1368,6 +1372,14 @@ async def skyvern_workflow_create("""Create a reusable, versioned workflow from a YAML or JSON definition. For multi-page automations,scheduling, and repeated runs — not one-off trials (use skyvern_run_task for those).+ The ENTIRE workflow — its title, blocks, and parameters — must be serialized INTO the `definition`+ string (YAML or JSON). Do NOT pass title, blocks, parameters, or other workflow fields as separate+ top-level arguments; only definition/format/folder_id/code_only are accepted and any other top-level+ field is rejected. Minimal JSON definition:+ {"title": "My workflow", "workflow_definition": {"blocks": [...], "parameters": [...]}}.+ This creates from a definition — it does not list or search; to browse existing workflows use+ skyvern_workflow_list.+One block per step: "navigation" for actions, "extraction" for data. Do NOT use deprecated "task" type.Call skyvern_block_schema() for block types and schemas. Use {{parameter_key}} for input references.Defaults to AI agent execution (run_with="agent"). For JSON definitions, code_version=2 is also@@ -1459,7 +1471,11 @@ async def skyvern_workflow_update(] = False,) -> dict[str, Any]:"""Update an existing workflow's definition. Use when you need to modify a workflow's blocks,- parameters, or configuration. Creates a new version of the workflow."""+ parameters, or configuration. Creates a new version of the workflow.++ The ENTIRE updated workflow — its title, blocks, and parameters — must be serialized INTO the+ `definition` string; do NOT pass title/blocks/parameters as separate top-level arguments (only+ workflow_id/definition/format/code_only are accepted, any other top-level field is rejected)."""if err := validate_workflow_id(workflow_id, "skyvern_workflow_update"):return err@@ -1690,6 +1706,9 @@ async def skyvern_workflow_run(] = None,) -> dict[str, Any]:"""Run a Skyvern workflow with parameters. Use when you need to execute an automation workflow.+ Starts a NEW run and requires a workflow_id (wpid_...), NOT a workflow_run_id. To re-run an existing+ terminal run with its original parameters, use skyvern_workflow_retry (which takes a workflow_run_id);+ to inspect a past run, use skyvern_workflow_status or skyvern_workflow_run_list.Returns immediately by default (async) — set wait=true to block until completion.Default timeout is 300s (5 minutes). For longer workflows, increase timeout_secondsor use wait=false and poll with skyvern_workflow_status."""@@ -1893,7 +1912,8 @@ async def skyvern_workflow_retry(workflow_run_id: Annotated[str, "Workflow run ID to retry (wr_...)"],) -> dict[str, Any]:"""Retry a terminal workflow run. Creates a new workflow run using the original run- parameters and run settings."""+ parameters and run settings. Takes a workflow_run_id (wr_...), NOT a workflow_id — to start a+ fresh run from a workflow definition instead, use skyvern_workflow_run."""if err := validate_workflow_run_id(workflow_run_id, "skyvern_workflow_retry"):return errdiff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.pyindex 1fa1a947b..dfecabc1f 100644--- a/skyvern/webeye/actions/handler.py+++ b/skyvern/webeye/actions/handler.py@@ -1420,6 +1420,60 @@ def _select_value_is_ambiguous(options: list[SkyvernOptionType], value: str | Noreturn sum(1 for option in options if option.get("value") == value) > 1+# A focus-click before select_option only needs to focus a visible <select>; if an overlay+# intercepts it we want to bail fast and let select_option commit via the DOM, not stall for the+# full BROWSER_ACTION_TIMEOUT_MS on every covered select. (SKY-11618)+_SELECT_FOCUS_CLICK_TIMEOUT_MS = 1000+++async def _best_effort_focus_click_before_select(*, locator: Locator, action: actions.SelectOptionAction) -> None:+ """Click a native <select> to focus it before select_option.++ Best-effort: an overlay (e.g. a consent/opt-out modal) can intercept this click, but+ select_option commits the value via the DOM regardless — a failed focus-click must not+ abort the selection. Uses a short timeout so an intercepted click bails fast. (SKY-11618)+ """+ try:+ await locator.click(timeout=_SELECT_FOCUS_CLICK_TIMEOUT_MS)+ except Exception:+ LOG.info(+ "Failed to click before select action; continuing to select_option",+ exc_info=True,+ action=action,+ locator=locator,+ )+++_DROPDOWN_SURROGATE_ROLES = frozenset({"combobox", "listbox", "option"})+# aria-haspopup values that advertise a dropdown-style popup (a styled-select trigger). Per ARIA,+# "true" is equivalent to "menu"; only "dialog" (and "false") denote a non-dropdown popup, so those+# are excluded — a consent/opt-out modal trigger uses "dialog" and must not qualify.+_DROPDOWN_SURROGATE_HASPOPUP = frozenset({"listbox", "menu", "tree", "grid", "true"})+++async def _is_dropdown_surrogate_blocker(element: SkyvernElement) -> bool:+ """True when a blocking element looks like a styled-dropdown surrogate for a native <select>+ (another <select>, a combobox/listbox/option widget, or a trigger with a dropdown+ aria-haspopup) rather than an unrelated overlay such as a consent/opt-out modal.++ Used only on the fallback after native select_option fails: a failed native selection does not+ prove the overlapping element is a real dropdown, so we require this evidence before retargeting+ the select action onto it — otherwise an unrelated modal could hijack the selection. Rejecting a+ genuine-but-unrecognized trigger here is safe: it returns the honest native-select failure rather+ than click-navigating the wrong element. (SKY-11618)+ """+ if element.get_tag_name() == InteractiveElement.SELECT:+ return True+ try:+ role = (await element.get_attr("role") or "").strip().lower()+ if role in _DROPDOWN_SURROGATE_ROLES:+ return True+ haspopup = (await element.get_attr("aria-haspopup") or "").strip().lower()+ except Exception:+ return False+ return haspopup in _DROPDOWN_SURROGATE_HASPOPUP++async def _select_deterministic_normal_option(*,action: actions.SelectOptionAction,@@ -1432,19 +1486,7 @@ async def _select_deterministic_normal_option(action_result: list[ActionResult] = []is_success = False- try:- await locator.click(- timeout=settings.BROWSER_ACTION_TIMEOUT_MS,- )- except Exception as e:- LOG.info(- "Failed to click before select action",- exc_info=True,- action=action,- locator=locator,- )- action_result.append(ActionFailure(e))- return action_result+ await _best_effort_focus_click_before_select(locator=locator, action=action)value = matched_value if matched_value is not None else matched_labelif value is not None and not _select_value_is_ambiguous(skyvern_element.get_options(), value):@@ -3839,44 +3881,75 @@ async def handle_select_option_action(action=action,)+ # Idempotent no-op: if the requested value is already selected, we're done — regardless of+ # visibility. (normal_select does this check too, but the hidden-select path below skips+ # normal_select, so run it here to avoid a false failure on an already-correct hidden select.)try:- await skyvern_element.scroll_into_view()- blocking_element, exist = await skyvern_element.find_blocking_element(dom=dom)+ current_selected = await skyvern_element.get_attr("selected")+ if current_selected and current_selected in (action.option.label, action.option.value):+ return [ActionSuccess()]except Exception:- LOG.warning(- "Failed to find the blocking element, continue to select on the original <select>",- exc_info=True,- )- return await normal_select(- action=action, skyvern_element=skyvern_element, builder=dom.scraped_page, task=task, step=step- )-- if not exist:- return await normal_select(- action=action, skyvern_element=skyvern_element, builder=dom.scraped_page, task=task, step=step- )-- if blocking_element is None:- LOG.info("Try to scroll the element into view, then detecting the blocking element")+ LOG.info("Failed to confirm current <select> value; proceeding with the select action")++ # A VISIBLE native <select> is the real control: drive it via select_option (which commits+ # the value through the DOM even under an overlay such as a consent/opt-out modal). Try that+ # first and, on failure, only click-navigate a genuine dropdown surrogate so an unrelated+ # modal can't hijack it. A hidden native <select> (display:none behind a styled dropdown)+ # can't be driven by select_option — the overlapping element IS the styled widget that+ # replaced it, so click-navigate that widget directly (the pre-refactor behavior). (SKY-11618)+ select_is_visible = await skyvern_element.is_visible()+ normal_select_result: list[ActionResult] | None = None+ if select_is_visible:try:- await skyvern_element.scroll_into_view()- blocking_element, exist = await skyvern_element.find_blocking_element(dom=dom)- except Exception:- LOG.warning(- "Failed to find the blocking element when scrolling into view, fallback to normal select",- action=action,- exc_info=True,- )- return await normal_select(+ normal_select_result = await normal_select(action=action, skyvern_element=skyvern_element, builder=dom.scraped_page, task=task, step=step)+ except Exception as e:+ # normal_select can raise before returning (e.g. an LLM/provider error). Don't lose+ # the styled-dropdown fallback below — record the failure and keep going.+ LOG.warning("normal_select raised; falling back to blocking-element detection", exc_info=True)+ normal_select_result = [ActionFailure(exception=e)]+ if _normal_select_successful(normal_select_result):+ return normal_select_result++ blocking_element: SkyvernElement | None = None+ exist = False+ try:+ await skyvern_element.scroll_into_view()+ blocking_element, exist = await skyvern_element.find_blocking_element(dom=dom)+ if not exist or blocking_element is None:+ await skyvern_element.scroll_into_view()+ blocking_element, exist = await skyvern_element.find_blocking_element(dom=dom)+ except Exception:+ LOG.warning("Failed to find the blocking element for <select>", action=action, exc_info=True)+ blocking_element, exist = None, Falseif not exist or blocking_element is None:- return await normal_select(- action=action, skyvern_element=skyvern_element, builder=dom.scraped_page, task=task, step=step+ # No styled widget to click-navigate. Return the visible native failure if we ran it; a+ # hidden <select> with no surrogate can't be driven at all, so fail fast (don't run+ # select_option on a hidden node — it would only burn the visibility timeout).+ if normal_select_result is not None:+ return normal_select_result+ return [ActionFailure(EmptySelect(element_id=action.element_id))]++ # For a VISIBLE <select>, require dropdown-surrogate evidence before retargeting, so an+ # unrelated overlay (e.g. a consent/opt-out modal) can't hijack a failed selection. For a+ # hidden backing <select>, the overlapping element is the styled widget that replaced it —+ # click-navigate it regardless (its dropdown role may sit on an ancestor of the hit node).+ if select_is_visible and not await _is_dropdown_surrogate_blocker(blocking_element):+ LOG.info(+ "<select> blocked by a non-dropdown element (likely an overlay); returning the native "+ "select result instead of click-navigating it",+ blocking_element=blocking_element.get_id(),)+ return (+ normal_select_result+ if normal_select_result is not None+ else [ActionFailure(EmptySelect(element_id=action.element_id))]+ )+LOG.info(- "<select> is blocked by another element, going to select on the blocking element",+ "<select> not set via select_option; selecting on the blocking (styled-dropdown) element",blocking_element=blocking_element.get_id(),)select_action = SelectOptionAction(@@ -7527,19 +7600,7 @@ async def normal_select(),)- try:- await locator.click(- timeout=settings.BROWSER_ACTION_TIMEOUT_MS,- )- except Exception as e:- LOG.info(- "Failed to click before select action",- exc_info=True,- action=action,- locator=locator,- )- action_result.append(ActionFailure(e))- return action_result+ await _best_effort_focus_click_before_select(locator=locator, action=action)if not is_success and value is not None:try:diff --git a/tests/unit/test_mcp_block_tools.py b/tests/unit/test_mcp_block_tools.pyindex ceae16231..33182ab08 100644--- a/tests/unit/test_mcp_block_tools.py+++ b/tests/unit/test_mcp_block_tools.py@@ -2,6 +2,7 @@from __future__ import annotations+import inspectimport jsonimport pytest@@ -77,3 +78,28 @@ async def test_block_validate_pdf_fill() -> None:assert result["ok"] is Trueassert result["data"]["valid"] is True+++def test_block_schema_takes_block_type_only_not_a_definition() -> None:+ """block_schema accepts only a block_type string; a full block definition belongs in block_validate.++ Guards the routing contract (SKY-12140/12141): callers that send a `definition`/`format` payload+ to block_schema are misrouted. The fix is the tool description, NOT adding those params here — so+ the function must keep rejecting them at the Python boundary.+ """+ params = inspect.signature(skyvern_block_schema).parameters+ assert set(params) == {"block_type"}++ with pytest.raises(TypeError):+ skyvern_block_schema(definition="{}", format="json") # type: ignore[call-arg]+++def test_block_schema_docstring_routes_full_definitions_to_block_validate() -> None:+ doc = skyvern_block_schema.__doc__ or ""+ assert "block_type" in doc+ assert "skyvern_block_validate" in doc+++def test_block_validate_docstring_cross_refs_block_schema() -> None:+ doc = skyvern_block_validate.__doc__ or ""+ assert "skyvern_block_schema" in docdiff --git a/tests/unit/test_mcp_workflow_guidance.py b/tests/unit/test_mcp_workflow_guidance.pyindex c9f0285e2..410d2369e 100644--- a/tests/unit/test_mcp_workflow_guidance.py+++ b/tests/unit/test_mcp_workflow_guidance.py@@ -1,10 +1,21 @@from __future__ import annotations+import inspect+import pytestfrom skyvern.cli.mcp_tools import mcpfrom skyvern.cli.mcp_tools.blocks import skyvern_block_schema+from skyvern.cli.mcp_tools.inspection import skyvern_get_htmlfrom skyvern.cli.mcp_tools.prompts import BUILD_WORKFLOW_CONTENT+from skyvern.cli.mcp_tools.session import skyvern_browser_session_create, skyvern_browser_session_list+from skyvern.cli.mcp_tools.workflow import (+ skyvern_workflow_create,+ skyvern_workflow_get,+ skyvern_workflow_retry,+ skyvern_workflow_run,+ skyvern_workflow_update,+)def test_build_workflow_prompt_guides_text_prompt_defaults() -> None:@@ -44,3 +55,71 @@ async def test_text_prompt_block_schema_example_omits_raw_llm_key() -> None:assert result["ok"] is Trueassert "llm_key" not in result["data"]["example"]assert "model" not in result["data"]["example"]+++# --- Tool-routing hints in tool descriptions (mechanism (c): wrong-tool / missing-arg calls) ---+# These guard the cross-references that steer an MCP client to the right tool. Tool names are stable+# API identifiers, so asserting they appear in the routing docstrings is a contract check, not prose.+++def test_workflow_get_routes_search_and_browse_to_workflow_list() -> None:+ """get fetches ONE workflow by known id; search/browse/paginate belong on workflow_list (SKY-12087/89/90/91)."""+ doc = skyvern_workflow_get.__doc__ or ""+ assert "skyvern_workflow_list" in doc+ params = inspect.signature(skyvern_workflow_get).parameters+ assert params["workflow_id"].default is inspect.Parameter.empty+++def test_workflow_create_routes_list_intent_and_keeps_definition() -> None:+ """create builds from a serialized `definition`; list intent (only_workflows) belongs on workflow_list+ (SKY-12088), and the whole workflow (incl. title) serializes INTO `definition` (SKY-12072/12107/12108/12109)."""+ doc = skyvern_workflow_create.__doc__ or ""+ assert "skyvern_workflow_list" in doc+ assert "definition" in doc+++def test_workflow_update_keeps_serialized_definition() -> None:+ """update takes the whole workflow serialized into `definition`; flat fields are rejected (SKY-12072)."""+ doc = skyvern_workflow_update.__doc__ or ""+ assert "definition" in doc+ params = inspect.signature(skyvern_workflow_update).parameters+ assert params["definition"].default is inspect.Parameter.empty+++def test_workflow_run_routes_retry_intent_to_workflow_retry() -> None:+ """run starts a NEW run (needs workflow_id); a workflow_run_id means retry an existing run (SKY-12051)."""+ doc = skyvern_workflow_run.__doc__ or ""+ assert "skyvern_workflow_retry" in doc+ params = inspect.signature(skyvern_workflow_run).parameters+ assert params["workflow_id"].default is inspect.Parameter.empty+ assert "workflow_run_id" not in params+++def test_workflow_retry_cross_refs_workflow_run() -> None:+ doc = skyvern_workflow_retry.__doc__ or ""+ assert "skyvern_workflow_run" in doc+++def test_browser_session_create_makes_session_and_routes_url_and_steps() -> None:+ """create MAKES a session; a session_id/url/steps/selector means act on an EXISTING session via+ navigate/execute instead (SKY-12092/12093/12095/12103)."""+ doc = skyvern_browser_session_create.__doc__ or ""+ assert "skyvern_navigate" in doc+ assert "skyvern_execute" in doc+ params = set(inspect.signature(skyvern_browser_session_create).parameters)+ assert not ({"session_id", "url", "steps", "selector"} & params)+++def test_browser_session_list_takes_no_pagination() -> None:+ """session_list returns ALL sessions in one call; it has no page/page_size (SKY-12110)."""+ params = set(inspect.signature(skyvern_browser_session_list).parameters)+ assert not ({"page", "page_size"} & params)+++def test_get_html_reads_current_page_by_selector_not_by_url() -> None:+ """get_html reads an element by selector on the CURRENT page; no HTML-by-URL — navigate first (SKY-12104)."""+ doc = skyvern_get_html.__doc__ or ""+ assert "skyvern_navigate" in doc+ params = set(inspect.signature(skyvern_get_html).parameters)+ assert "selector" in params+ assert "url" not in paramsdiff --git a/tests/unit/test_select_option_blocking_overlay.py b/tests/unit/test_select_option_blocking_overlay.pynew file mode 100644index 000000000..e3af06d3b--- /dev/null+++ b/tests/unit/test_select_option_blocking_overlay.py@@ -0,0 +1,308 @@+"""SKY-11618: a native ``<select>`` must be driven via ``select_option`` (normal_select) first,+so an unrelated overlay (a consent/opt-out/FCRA modal) covering the control can no longer hijack+the selection into click-navigation.++Root cause: the select handler treated ANY element overlapping the ``<select>``'s center as a+"blocking" custom dropdown and click-navigated it — so a modal painted over the control was+click-navigated instead of the value being committed. The fix tries ``normal_select``+(``select_option``, which commits the native value via the DOM regardless of the overlay) first,+and only falls back to click-navigating an overlapping element when that genuinely fails.+"""++from __future__ import annotations++from unittest.mock import AsyncMock, MagicMock++import pytest++from skyvern.webeye.utils.dom import InteractiveElement, SkyvernElement+++class TestSelectOptionFirst:+ """The select handler calls ``normal_select`` first; an overlapping element is only+ click-navigated when the native ``select_option`` fails."""++ @staticmethod+ def _make_select_element(is_visible: bool = True, selected: str | None = None) -> SkyvernElement:+ elem = object.__new__(SkyvernElement)+ elem.get_tag_name = MagicMock(return_value=InteractiveElement.SELECT) # type: ignore[method-assign]+ elem.get_id = MagicMock(return_value="SEL1") # type: ignore[method-assign]+ elem.is_custom_option = AsyncMock(return_value=False) # type: ignore[method-assign]+ elem.is_selectable = AsyncMock(return_value=True) # type: ignore[method-assign]+ elem.is_disabled = AsyncMock(return_value=False) # type: ignore[method-assign]+ elem.is_visible = AsyncMock(return_value=is_visible) # type: ignore[method-assign]+ elem.get_attr = AsyncMock(return_value=selected) # type: ignore[method-assign]+ elem.scroll_into_view = AsyncMock(return_value=None) # type: ignore[method-assign]+ elem.find_blocking_element = AsyncMock() # type: ignore[method-assign]+ return elem++ async def _run(+ self,+ monkeypatch: pytest.MonkeyPatch,+ *,+ normal_success: bool,+ blocking_return: tuple = (None, False),+ blocker_is_checkbox: bool = False,+ normal_raises: bool = False,+ blocker_is_surrogate: bool = True,+ select_visible: bool = True,+ preselected: str | None = None,+ ) -> tuple:+ from skyvern.webeye.actions import handler as handler_module+ from skyvern.webeye.actions.actions import SelectOption, SelectOptionAction+ from skyvern.webeye.actions.responses import ActionFailure, ActionSuccess++ select_element = self._make_select_element(is_visible=select_visible, selected=preselected)+ select_element.find_blocking_element = AsyncMock(return_value=blocking_return) # type: ignore[method-assign]++ dom_instance = MagicMock()+ dom_instance.scraped_page = MagicMock()+ dom_instance.get_skyvern_element_by_id = AsyncMock(return_value=select_element)+ monkeypatch.setattr(handler_module, "DomUtil", MagicMock(return_value=dom_instance))++ if normal_raises:+ normal_select = AsyncMock(side_effect=Exception("LLM provider error"))+ else:+ normal_result = [ActionSuccess()] if normal_success else [ActionFailure(Exception("no option"))]+ normal_select = AsyncMock(return_value=normal_result)+ monkeypatch.setattr(handler_module, "normal_select", normal_select)++ checkbox_routed = ["CHECKBOX_ROUTED"]+ handle_checkbox = AsyncMock(return_value=checkbox_routed)+ monkeypatch.setattr(handler_module, "handle_checkbox_action", handle_checkbox)++ blocking_element = blocking_return[0]+ if blocking_element is not None:+ blocking_element.get_id = MagicMock(return_value="BLK1")+ blocking_element.is_checkbox = AsyncMock(return_value=blocker_is_checkbox)+ blocking_element.is_radio = AsyncMock(return_value=False)+ blocking_element.is_btn_input = AsyncMock(return_value=False)+ # dropdown surrogate -> reassign & click-navigate; otherwise (a modal) -> honest failure+ blocking_element.get_tag_name = MagicMock(return_value="div")+ blocking_element.get_attr = AsyncMock(return_value="combobox" if blocker_is_surrogate else "dialog")++ scraped_page = MagicMock()+ scraped_page.id_to_element_dict = {"SEL1": {"id": "SEL1", "tagName": "select"}}++ action = SelectOptionAction(element_id="SEL1", option=SelectOption(label="California", value="CA"))++ results = await handler_module.handle_select_option_action(+ action=action,+ page=MagicMock(),+ scraped_page=scraped_page,+ task=MagicMock(),+ step=MagicMock(),+ )+ return results, normal_select, select_element, handle_checkbox++ @pytest.mark.asyncio+ async def test_overlay_present_but_select_option_succeeds_no_click_navigation(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ # The modal-hijack scenario: normal_select (select_option) commits the value, so the+ # handler returns immediately and never inspects/click-navigates the overlapping element.+ results, normal_select, select_element, _ = await self._run(monkeypatch, normal_success=True)++ normal_select.assert_awaited_once()+ assert normal_select.await_args.kwargs["skyvern_element"] is select_element+ select_element.find_blocking_element.assert_not_awaited()+ assert len(results) == 1 and results[0].__class__.__name__ == "ActionSuccess"++ @pytest.mark.asyncio+ async def test_select_option_fails_no_blocker_returns_normal_result(self, monkeypatch: pytest.MonkeyPatch) -> None:+ results, normal_select, select_element, handle_checkbox = await self._run(+ monkeypatch, normal_success=False, blocking_return=(None, False)+ )++ normal_select.assert_awaited_once()+ select_element.find_blocking_element.assert_awaited() # looked for a blocker, found none+ handle_checkbox.assert_not_awaited()+ assert len(results) == 1 and results[0].__class__.__name__ == "ActionFailure"++ @pytest.mark.asyncio+ async def test_select_option_fails_with_blocker_falls_back_to_click_navigation(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ # When select_option fails AND an element overlaps the control, reassign to it (the styled+ # custom-dropdown fallback). Routed here to a checkbox stub to prove the reassignment path.+ blocker = MagicMock()+ results, normal_select, _, handle_checkbox = await self._run(+ monkeypatch, normal_success=False, blocking_return=(blocker, True), blocker_is_checkbox=True+ )++ normal_select.assert_awaited_once()+ handle_checkbox.assert_awaited_once()+ assert results == ["CHECKBOX_ROUTED"]++ @pytest.mark.asyncio+ async def test_select_option_fails_with_modal_blocker_no_hijack(self, monkeypatch: pytest.MonkeyPatch) -> None:+ # select_option failed AND the overlapping element is an unrelated modal (not a dropdown+ # surrogate): do NOT retarget onto it — return the honest native-select failure.+ blocker = MagicMock()+ results, normal_select, _, handle_checkbox = await self._run(+ monkeypatch,+ normal_success=False,+ blocking_return=(blocker, True),+ blocker_is_checkbox=True,+ blocker_is_surrogate=False,+ )++ handle_checkbox.assert_not_awaited()+ assert len(results) == 1 and results[0].__class__.__name__ == "ActionFailure"++ @pytest.mark.asyncio+ async def test_normal_select_raises_still_falls_back_to_blocker(self, monkeypatch: pytest.MonkeyPatch) -> None:+ # normal_select can raise (e.g. an LLM/provider error). The styled-dropdown fallback must+ # still run instead of the whole action erroring out.+ blocker = MagicMock()+ results, normal_select, _, handle_checkbox = await self._run(+ monkeypatch,+ normal_success=False,+ normal_raises=True,+ blocking_return=(blocker, True),+ blocker_is_checkbox=True,+ )++ normal_select.assert_awaited_once()+ handle_checkbox.assert_awaited_once()+ assert results == ["CHECKBOX_ROUTED"]++ @pytest.mark.asyncio+ async def test_hidden_backing_select_click_navigates_widget_even_without_role(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ # A hidden backing <select> (display:none) behind a styled dropdown must NOT burn+ # select_option visibility timeouts, and the overlapping widget IS the intended target — so+ # click-navigate it even when the hit node itself carries no dropdown role (role on ancestor).+ blocker = MagicMock()+ results, normal_select, _, handle_checkbox = await self._run(+ monkeypatch,+ normal_success=False,+ select_visible=False,+ blocking_return=(blocker, True),+ blocker_is_checkbox=True,+ blocker_is_surrogate=False,+ )++ normal_select.assert_not_awaited()+ handle_checkbox.assert_awaited_once()+ assert results == ["CHECKBOX_ROUTED"]++ @pytest.mark.asyncio+ async def test_hidden_select_no_surrogate_fails_fast_without_running_select_option(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ # Hidden <select> with no styled widget: fail fast; never run select_option on a hidden node.+ results, normal_select, _, _ = await self._run(+ monkeypatch, normal_success=False, select_visible=False, blocking_return=(None, False)+ )++ normal_select.assert_not_awaited()+ assert len(results) == 1 and results[0].__class__.__name__ == "ActionFailure"++ @pytest.mark.asyncio+ async def test_already_selected_hidden_select_is_idempotent_success(self, monkeypatch: pytest.MonkeyPatch) -> None:+ # A hidden <select> already holding the requested value is a no-op success — must not fail+ # or drive a blocker just because the visibility gate skips normal_select.+ results, normal_select, select_element, handle_checkbox = await self._run(+ monkeypatch, normal_success=False, select_visible=False, preselected="CA"+ )++ normal_select.assert_not_awaited()+ select_element.find_blocking_element.assert_not_awaited()+ handle_checkbox.assert_not_awaited()+ assert len(results) == 1 and results[0].__class__.__name__ == "ActionSuccess"++ @pytest.mark.asyncio+ async def test_normal_select_raises_no_blocker_returns_failure(self, monkeypatch: pytest.MonkeyPatch) -> None:+ results, normal_select, select_element, handle_checkbox = await self._run(+ monkeypatch, normal_success=False, normal_raises=True, blocking_return=(None, False)+ )++ select_element.find_blocking_element.assert_awaited()+ handle_checkbox.assert_not_awaited()+ assert len(results) == 1 and results[0].__class__.__name__ == "ActionFailure"+++class TestIsDropdownSurrogateBlocker:+ """The visible-<select> fallback guard: click-navigate a blocker only if it's a genuine+ dropdown surrogate, never an unrelated modal. Locks the role/aria-haspopup matrix."""++ @staticmethod+ def _elem(*, tag: str = "div", role: str | None = None, haspopup: str | None = None) -> MagicMock:+ elem = MagicMock()+ elem.get_tag_name = MagicMock(return_value=tag)+ attrs = {"role": role, "aria-haspopup": haspopup}+ elem.get_attr = AsyncMock(side_effect=lambda name, *a, **k: attrs.get(name))+ return elem++ @pytest.mark.parametrize(+ ("tag", "role", "haspopup", "expected"),+ [+ pytest.param("select", None, None, True, id="native_select"),+ pytest.param("div", "combobox", None, True, id="role_combobox"),+ pytest.param("ul", "listbox", None, True, id="role_listbox"),+ pytest.param("button", None, "listbox", True, id="haspopup_listbox"),+ pytest.param("button", None, "menu", True, id="haspopup_menu"),+ pytest.param("button", None, "true", True, id="haspopup_true_is_menu"),+ pytest.param("button", None, "dialog", False, id="haspopup_dialog_excluded"),+ pytest.param("button", None, "false", False, id="haspopup_false_excluded"),+ pytest.param("div", "dialog", None, False, id="role_dialog_modal"),+ pytest.param("button", None, None, False, id="plain_modal_button"),+ ],+ )+ @pytest.mark.asyncio+ async def test_matrix(self, tag: str, role: str | None, haspopup: str | None, expected: bool) -> None:+ from skyvern.webeye.actions import handler as handler_module++ elem = self._elem(tag=tag, role=role, haspopup=haspopup)+ assert await handler_module._is_dropdown_surrogate_blocker(elem) is expected+++class TestSelectCommitsUnderOverlay:+ """The value must still commit when an overlay intercepts the focus-click before+ ``select_option`` — the pre-click is best-effort; ``select_option`` sets the native value+ via the DOM regardless."""++ @pytest.mark.asyncio+ async def test_best_effort_focus_click_swallows_intercepted_click(self) -> None:+ from skyvern.webeye.actions import handler as handler_module+ from skyvern.webeye.actions.actions import SelectOption, SelectOptionAction++ locator = MagicMock()+ locator.click = AsyncMock(side_effect=Exception("click intercepted by overlay"))+ action = SelectOptionAction(element_id="SEL1", option=SelectOption(label="California", value="CA"))++ # Must not raise — an intercepted focus-click cannot abort the selection.+ await handler_module._best_effort_focus_click_before_select(locator=locator, action=action)+ locator.click.assert_awaited_once()++ @pytest.mark.asyncio+ async def test_deterministic_select_commits_when_preclick_intercepted(self) -> None:+ from skyvern.webeye.actions import handler as handler_module+ from skyvern.webeye.actions.actions import SelectOption, SelectOptionAction+ from skyvern.webeye.actions.responses import ActionSuccess++ locator = MagicMock()+ locator.click = AsyncMock(side_effect=Exception("click intercepted by overlay"))+ locator.select_option = AsyncMock(return_value=None) # DOM select succeeds regardless++ skyvern_element = MagicMock()+ skyvern_element.get_options = MagicMock(return_value=[{"value": "CA", "label": "California"}])++ action = SelectOptionAction(element_id="SEL1", option=SelectOption(label="California", value="CA"))++ result = await handler_module._select_deterministic_normal_option(+ action=action,+ skyvern_element=skyvern_element,+ locator=locator,+ matched_label="California",+ matched_value="CA",+ matched_index=0,+ )++ # The intercepted pre-click did not abort: select_option ran and the value committed.+ locator.click.assert_awaited_once()+ locator.select_option.assert_awaited_once()+ assert locator.select_option.await_args.kwargs["value"] == "CA"+ assert len(result) == 1 and isinstance(result[0], ActionSuccess)