Skip to content

Automate browser based workflows with AI

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__.py
index 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 Lifecycle
diff --git a/skyvern/cli/mcp_tools/blocks.py b/skyvern/cli/mcp_tools/blocks.py
index 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.py
index 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_html
try:
diff --git a/skyvern/cli/mcp_tools/session.py b/skyvern/cli/mcp_tools/session.py
index 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.py
index 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_seconds
or 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 err
diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.py
index 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 | No
return 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_label
if 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, False
if 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.py
index 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 inspect
import json
import pytest
@@ -77,3 +78,28 @@ async def test_block_validate_pdf_fill() -> None:
assert result["ok"] is True
assert 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 doc
diff --git a/tests/unit/test_mcp_workflow_guidance.py b/tests/unit/test_mcp_workflow_guidance.py
index 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 pytest
from skyvern.cli.mcp_tools import mcp
from skyvern.cli.mcp_tools.blocks import skyvern_block_schema
+from skyvern.cli.mcp_tools.inspection import skyvern_get_html
from 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 True
assert "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 params
diff --git a/tests/unit/test_select_option_blocking_overlay.py b/tests/unit/test_select_option_blocking_overlay.py
new file mode 100644
index 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)