Skip to content

Automate browser based workflows with AI

feat: iframe support for SDK, CLI, and MCP tools (#5319)

Marc Kelechavae95511e08640
diff --git a/skyvern/cli/commands/_state.py b/skyvern/cli/commands/_state.py
index 96482c85d..a19e4448d 100644
--- a/skyvern/cli/commands/_state.py
+++ b/skyvern/cli/commands/_state.py
@@ -17,6 +17,9 @@ class CLIState:
cdp_url: str | None = None
mode: str | None = None # "cloud", "local", or "cdp"
created_at: str | None = None
+ frame_selector: str | None = None
+ frame_name: str | None = None
+ frame_index: int | None = None
def save_state(state: CLIState) -> None:
diff --git a/skyvern/cli/commands/browser.py b/skyvern/cli/commands/browser.py
index 5c452731a..8ad64f954 100644
--- a/skyvern/cli/commands/browser.py
+++ b/skyvern/cli/commands/browser.py
@@ -17,7 +17,15 @@ import typer
from skyvern.cli.commands._output import console, output, output_error
from skyvern.cli.commands._state import CLIState, clear_state, load_state, save_state
from skyvern.cli.core.artifacts import save_artifact
-from skyvern.cli.core.browser_ops import do_act, do_extract, do_navigate, do_screenshot
+from skyvern.cli.core.browser_ops import (
+ do_act,
+ do_extract,
+ do_frame_list,
+ do_frame_main,
+ do_frame_switch,
+ do_navigate,
+ do_screenshot,
+)
from skyvern.cli.core.client import get_skyvern
from skyvern.cli.core.guards import (
CREDENTIAL_HINT,
@@ -37,7 +45,9 @@ from skyvern.cli.mcp_tools.browser import skyvern_run_task as tool_run_task
browser_app = typer.Typer(help="Browser automation commands.", no_args_is_help=True)
session_app = typer.Typer(help="Manage browser sessions.", no_args_is_help=True)
+frame_app = typer.Typer(help="Manage iframe context.", no_args_is_help=True)
browser_app.add_typer(session_app, name="session")
+browser_app.add_typer(frame_app, name="frame")
@dataclass(frozen=True)
@@ -96,6 +106,31 @@ def _resolve_ai_target(selector: str | None, intent: str | None, *, operation: s
return ai_mode
+async def _apply_cli_frame_state(page: Any) -> None:
+ """Re-apply saved frame state from CLIState to a fresh SkyvernBrowserPage.
+
+ CLI commands get a new page object each invocation. If the user previously
+ ran ``skyvern browser frame switch``, the target frame is persisted in
+ CLIState and must be re-entered before executing the action.
+ """
+ state = load_state()
+ if not state:
+ return
+ selector = state.frame_selector
+ name = state.frame_name
+ index = state.frame_index
+ if selector is None and name is None and index is None:
+ return
+ try:
+ await do_frame_switch(page, selector=selector, name=name, index=index)
+ except Exception as e:
+ console.print(f"[yellow]Warning: saved frame state is stale, clearing ({e})[/yellow]")
+ state.frame_selector = None
+ state.frame_name = None
+ state.frame_index = None
+ save_state(state)
+
+
def _validate_wait_state(state: str) -> None:
if state not in VALID_ELEMENT_STATES:
raise GuardError(f"Invalid state: {state}", "Use visible, hidden, attached, or detached")
@@ -294,6 +329,12 @@ def navigate(
browser = await _connect_browser(connection)
page = await browser.get_working_page()
result = await do_navigate(page, url, timeout=timeout, wait_until=wait_until)
+ cli_state = load_state()
+ if cli_state:
+ cli_state.frame_selector = None
+ cli_state.frame_name = None
+ cli_state.frame_index = None
+ save_state(cli_state)
return {"url": result.url, "title": result.title}
try:
@@ -322,6 +363,7 @@ def screenshot(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
result = await do_screenshot(page, full_page=full_page, selector=selector)
if output_path:
@@ -365,6 +407,7 @@ def evaluate(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
result = await page.evaluate(expression)
return {"result": result}
@@ -398,6 +441,7 @@ def click(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
kwargs: dict[str, Any] = {"timeout": timeout}
if button:
@@ -443,6 +487,7 @@ def hover(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
if ai_mode is not None:
locator = page.locator(selector=selector, prompt=intent, ai=ai_mode) # type: ignore[arg-type]
@@ -489,6 +534,7 @@ def type_text(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
if selector:
try:
@@ -554,6 +600,7 @@ def scroll(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
if intent:
ai_mode = "fallback" if selector else "proactive"
@@ -601,6 +648,7 @@ def select(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
if ai_mode is not None:
await page.select_option(selector=selector, value=value, prompt=intent, ai=ai_mode, timeout=timeout) # type: ignore[arg-type]
@@ -639,6 +687,7 @@ def press_key(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
if intent or selector:
ai_mode, err = resolve_ai_mode(selector, intent)
@@ -694,6 +743,7 @@ def wait(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
waited_for = ""
if time_ms is not None:
@@ -751,6 +801,7 @@ def act(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
result = await do_act(page, prompt)
return {"prompt": result.prompt, "completed": result.completed}
@@ -779,6 +830,7 @@ def extract(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
result = await do_extract(page, prompt, schema=schema)
return {"prompt": prompt, "extracted": result.extracted}
@@ -806,6 +858,7 @@ def validate(
connection = _resolve_connection(session, cdp)
browser = await _connect_browser(connection)
page = await browser.get_working_page()
+ await _apply_cli_frame_state(page)
valid = await page.validate(prompt)
return {"prompt": prompt, "valid": valid}
@@ -1378,3 +1431,91 @@ def _print_serve_instructions_unified(result: dict[str, Any], browser_path: str)
console.print("[bold]Press Ctrl+C to stop.[/bold]")
console.print()
+
+
+# ---------------------------------------------------------------------------
+# Frame commands (iframe switching)
+# ---------------------------------------------------------------------------
+
+
+@frame_app.command("switch")
+def frame_switch(
+ selector: str | None = typer.Option(None, "--selector", "-s", help="CSS selector for the iframe element."),
+ name: str | None = typer.Option(None, "--name", "-n", help="Frame name attribute."),
+ index: int | None = typer.Option(None, "--index", "-i", help="Frame index (0 = main)."),
+ session: str | None = typer.Option(None, help="Browser session ID."),
+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """Switch into an iframe for subsequent commands."""
+
+ async def _run() -> dict:
+ connection = _resolve_connection(session, cdp)
+ browser = await _connect_browser(connection)
+ page = await browser.get_working_page()
+ result = await do_frame_switch(page, selector=selector, name=name, index=index)
+ state = load_state()
+ if state:
+ state.frame_selector = selector
+ state.frame_name = name
+ state.frame_index = index
+ save_state(state)
+ return {"frame_name": result.name, "frame_url": result.url}
+
+ try:
+ data = asyncio.run(_run())
+ output(data, action="frame_switch", json_mode=json_output)
+ except (ValueError, GuardError) as e:
+ output_error(str(e), hint="Use 'skyvern browser frame list' to find frames.", json_mode=json_output)
+ except Exception as e:
+ output_error(str(e), json_mode=json_output)
+
+
+@frame_app.command("main")
+def frame_main_cmd(
+ session: str | None = typer.Option(None, help="Browser session ID."),
+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """Switch back to the main page frame."""
+
+ async def _run() -> dict:
+ connection = _resolve_connection(session, cdp)
+ browser = await _connect_browser(connection)
+ page = await browser.get_working_page()
+ do_frame_main(page)
+ state = load_state()
+ if state:
+ state.frame_selector = None
+ state.frame_name = None
+ state.frame_index = None
+ save_state(state)
+ return {"status": "switched_to_main_frame"}
+
+ try:
+ data = asyncio.run(_run())
+ output(data, action="frame_main", json_mode=json_output)
+ except Exception as e:
+ output_error(str(e), json_mode=json_output)
+
+
+@frame_app.command("list")
+def frame_list_cmd(
+ session: str | None = typer.Option(None, help="Browser session ID."),
+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """List all frames on the current page."""
+
+ async def _run() -> list:
+ connection = _resolve_connection(session, cdp)
+ browser = await _connect_browser(connection)
+ page = await browser.get_working_page()
+ frames = await do_frame_list(page)
+ return [{"index": f.index, "name": f.name, "url": f.url, "is_main": f.is_main} for f in frames]
+
+ try:
+ data = asyncio.run(_run())
+ output(data, action="frame_list", json_mode=json_output)
+ except Exception as e:
+ output_error(str(e), json_mode=json_output)
diff --git a/skyvern/cli/core/browser_ops.py b/skyvern/cli/core/browser_ops.py
index e034bad5f..e922593f7 100644
--- a/skyvern/cli/core/browser_ops.py
+++ b/skyvern/cli/core/browser_ops.py
@@ -85,3 +85,49 @@ async def do_extract(
parsed_schema = parse_extract_schema(schema)
extracted = await page.extract(prompt=prompt, schema=parsed_schema)
return ExtractResult(extracted=extracted)
+
+
+# -- Frame operations --
+
+
+@dataclass
+class FrameInfo:
+ index: int
+ name: str
+ url: str
+ is_main: bool
+
+
+@dataclass
+class FrameSwitchResult:
+ name: str | None
+ url: str | None
+ selector: str | None = None
+ requested_name: str | None = None
+ index: int | None = None
+
+
+async def do_frame_switch(
+ page: Any,
+ *,
+ selector: str | None = None,
+ name: str | None = None,
+ index: int | None = None,
+) -> FrameSwitchResult:
+ result = await page.frame_switch(selector=selector, name=name, index=index)
+ return FrameSwitchResult(
+ name=result.get("name"),
+ url=result.get("url"),
+ selector=selector,
+ requested_name=name,
+ index=index,
+ )
+
+
+def do_frame_main(page: Any) -> None:
+ page.frame_main()
+
+
+async def do_frame_list(page: Any) -> list[FrameInfo]:
+ frames = await page.frame_list()
+ return [FrameInfo(index=f["index"], name=f["name"], url=f["url"], is_main=f["is_main"]) for f in frames]
diff --git a/skyvern/cli/core/session_manager.py b/skyvern/cli/core/session_manager.py
index 4b50d0e3b..ca234edbf 100644
--- a/skyvern/cli/core/session_manager.py
+++ b/skyvern/cli/core/session_manager.py
@@ -17,7 +17,7 @@ from .result import BrowserContext, ErrorCode, make_error
LOG = structlog.get_logger(__name__)
if TYPE_CHECKING:
- from playwright.async_api import Page
+ from playwright.async_api import Frame, Page
from skyvern.library.skyvern_browser import SkyvernBrowser
from skyvern.library.skyvern_browser_page import SkyvernBrowserPage
@@ -42,6 +42,8 @@ class SessionState:
# -- Multi-page inspection hooks --
_hooked_page_ids: set[int] = field(default_factory=set)
_hooked_handlers_map: dict[int, dict[str, Any]] = field(default_factory=dict)
+ # -- Iframe frame context --
+ _working_frame: Frame | None = None
_current_session: ContextVar[SessionState | None] = ContextVar("mcp_session", default=None)
@@ -242,6 +244,20 @@ async def get_page(
# Install page event listener for tab_wait_for_new (once per session)
_install_page_event_listener(state, browser)
+ # Propagate iframe frame context from session state to the page
+ if state._working_frame is not None:
+ # Guard against stale (detached) frame references
+ detached = False
+ try:
+ detached = state._working_frame.is_detached()
+ except AttributeError:
+ pass # frame object doesn't support is_detached (e.g., test mocks)
+ if detached:
+ LOG.debug("Clearing detached _working_frame from session state")
+ state._working_frame = None
+ else:
+ page._working_frame = state._working_frame
+
return page, ctx
diff --git a/skyvern/cli/mcp_tools/__init__.py b/skyvern/cli/mcp_tools/__init__.py
index 5cff5fe9a..a4210e1f4 100644
--- a/skyvern/cli/mcp_tools/__init__.py
+++ b/skyvern/cli/mcp_tools/__init__.py
@@ -19,6 +19,9 @@ from .browser import (
skyvern_evaluate,
skyvern_extract,
skyvern_file_upload,
+ skyvern_frame_list,
+ skyvern_frame_main,
+ skyvern_frame_switch,
skyvern_hover,
skyvern_login,
skyvern_navigate,
@@ -383,6 +386,11 @@ mcp.tool(tags={"tab_management"}, annotations=_MUT)(skyvern_tab_switch)
mcp.tool(tags={"tab_management"}, annotations=_DEST)(skyvern_tab_close)
mcp.tool(tags={"tab_management"}, annotations=_RO)(skyvern_tab_wait_for_new)
+# -- Frame management (iframe switching) --
+mcp.tool(tags={"browser_primitive"}, annotations=_MUT)(skyvern_frame_switch)
+mcp.tool(tags={"browser_primitive"}, annotations=_MUT)(skyvern_frame_main)
+mcp.tool(tags={"browser_primitive"}, annotations=_RO)(skyvern_frame_list)
+
# -- Inspection tools (console, network, dialog) --
mcp.tool(tags={"inspection"}, annotations=_RO)(skyvern_console_messages)
mcp.tool(tags={"inspection"}, annotations=_RO)(skyvern_network_requests)
@@ -461,6 +469,10 @@ __all__ = [
"skyvern_tab_switch",
"skyvern_tab_close",
"skyvern_tab_wait_for_new",
+ # Frame management (iframe switching)
+ "skyvern_frame_switch",
+ "skyvern_frame_main",
+ "skyvern_frame_list",
# Inspection (console, network, dialog)
"skyvern_console_messages",
"skyvern_network_requests",
diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.py
index e5948686f..e26e9511f 100644
--- a/skyvern/cli/mcp_tools/browser.py
+++ b/skyvern/cli/mcp_tools/browser.py
@@ -11,7 +11,16 @@ import structlog
from playwright.async_api import TimeoutError as PlaywrightTimeoutError
from pydantic import Field
-from skyvern.cli.core.browser_ops import do_act, do_extract, do_navigate, do_screenshot, parse_extract_schema
+from skyvern.cli.core.browser_ops import (
+ do_act,
+ do_extract,
+ do_frame_list,
+ do_frame_main,
+ do_frame_switch,
+ do_navigate,
+ do_screenshot,
+ parse_extract_schema,
+)
from skyvern.cli.core.guards import (
CREDENTIAL_HINT,
JS_PASSWORD_PATTERN,
@@ -33,7 +42,7 @@ from ._common import (
save_artifact,
)
from ._localhost import is_localhost_url
-from ._session import BrowserNotAvailableError, get_page, no_browser_error
+from ._session import BrowserNotAvailableError, get_current_session, get_page, no_browser_error
LOG = structlog.get_logger(__name__)
@@ -92,6 +101,11 @@ async def skyvern_navigate(
),
)
+ # Any navigation attempt may destroy iframes — clear frame state upfront
+ # (even failed navigations can partially load and destroy existing frames)
+ state = get_current_session()
+ state._working_frame = None
+
with Timer() as timer:
try:
result = await do_navigate(page, url, timeout=timeout, wait_until=wait_until)
@@ -1636,3 +1650,148 @@ async def skyvern_login(
},
timing_ms=timer.timing_ms,
)
+
+
+async def skyvern_frame_switch(
+ session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
+ cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
+ selector: Annotated[
+ str | None,
+ Field(description="CSS selector for the iframe element (e.g., '#payment-frame', 'iframe[name=checkout]')"),
+ ] = None,
+ name: Annotated[str | None, Field(description="Frame name attribute")] = None,
+ index: Annotated[
+ int | None, Field(description="Frame index (0 = main). Use skyvern_frame_list to find indices")
+ ] = None,
+) -> dict[str, Any]:
+ """Switch into an iframe so subsequent browser actions (click, type, extract, etc.) target elements inside it.
+
+ Use this for embedded payment forms, embedded widgets, or any content inside an <iframe>.
+ Call skyvern_frame_list first to discover available frames. Provide exactly one of selector, name, or index.
+ Call skyvern_frame_main to switch back to the main page.
+ """
+ params = sum(p is not None for p in (selector, name, index))
+ if params != 1:
+ return make_result(
+ "skyvern_frame_switch",
+ ok=False,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ "Exactly one of selector, name, or index is required",
+ "Use skyvern_frame_list to discover frames, then pass selector, name, or index",
+ ),
+ )
+
+ try:
+ page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)
+ except BrowserNotAvailableError:
+ return make_result("skyvern_frame_switch", ok=False, error=no_browser_error())
+
+ with Timer() as timer:
+ try:
+ result = await do_frame_switch(page, selector=selector, name=name, index=index)
+ timer.mark("sdk")
+
+ # Persist frame on session state for subsequent MCP calls
+ state = get_current_session()
+ state._working_frame = page._working_frame
+ except ValueError as e:
+ return make_result(
+ "skyvern_frame_switch",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=make_error(ErrorCode.INVALID_INPUT, str(e), "Use skyvern_frame_list to find valid frames"),
+ )
+ except Exception as e:
+ return make_result(
+ "skyvern_frame_switch",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=make_error(ErrorCode.ACTION_FAILED, str(e), "The iframe may not be loaded yet — try waiting"),
+ )
+
+ return make_result(
+ "skyvern_frame_switch",
+ browser_context=ctx,
+ data={
+ "frame_name": result.name,
+ "frame_url": result.url,
+ "switched_by": "selector" if selector else ("name" if name else "index"),
+ "sdk_equivalent": (
+ f'await page.frame_switch(selector="{selector}")'
+ if selector
+ else f'await page.frame_switch(name="{name}")'
+ if name
+ else f"await page.frame_switch(index={index})"
+ ),
+ },
+ timing_ms=timer.timing_ms,
+ )
+
+
+async def skyvern_frame_main(
+ 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]:
+ """Switch back to the main page frame after working inside an iframe.
+
+ Call this after skyvern_frame_switch when you're done interacting with iframe content
+ and want subsequent actions to target the main page again.
+ """
+ try:
+ page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)
+ except BrowserNotAvailableError:
+ return make_result("skyvern_frame_main", ok=False, error=no_browser_error())
+
+ do_frame_main(page)
+
+ # Clear frame on session state
+ state = get_current_session()
+ state._working_frame = None
+
+ return make_result(
+ "skyvern_frame_main",
+ browser_context=ctx,
+ data={"status": "switched_to_main_frame", "sdk_equivalent": "page.frame_main()"},
+ )
+
+
+async def skyvern_frame_list(
+ 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]:
+ """List all frames (including iframes) on the current page.
+
+ Returns each frame's index, name, URL, and whether it's the main frame.
+ Use the index, name, or a CSS selector with skyvern_frame_switch to enter an iframe.
+ """
+ try:
+ page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)
+ except BrowserNotAvailableError:
+ return make_result("skyvern_frame_list", ok=False, error=no_browser_error())
+
+ with Timer() as timer:
+ try:
+ frames = await do_frame_list(page)
+ timer.mark("sdk")
+ except Exception as e:
+ return make_result(
+ "skyvern_frame_list",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=make_error(ErrorCode.ACTION_FAILED, str(e), "Ensure a page is loaded first"),
+ )
+
+ return make_result(
+ "skyvern_frame_list",
+ browser_context=ctx,
+ data={
+ "frames": [{"index": f.index, "name": f.name, "url": f.url, "is_main": f.is_main} for f in frames],
+ "count": len(frames),
+ "sdk_equivalent": "await page.frame_list()",
+ },
+ timing_ms=timer.timing_ms,
+ )
diff --git a/skyvern/cli/mcp_tools/tabs.py b/skyvern/cli/mcp_tools/tabs.py
index dff09c88a..77c3cf69c 100644
--- a/skyvern/cli/mcp_tools/tabs.py
+++ b/skyvern/cli/mcp_tools/tabs.py
@@ -141,6 +141,8 @@ async def skyvern_tab_new(
try:
new_page = await browser._browser_context.new_page()
state._active_page = new_page
+ # New tab has no iframes yet — clear stale frame reference
+ state._working_frame = None
# Drain the event that _on_new_page() buffered for this explicitly
# created page, so tab_wait_for_new doesn't return it as a popup.
state._page_events = deque(
@@ -237,6 +239,8 @@ async def skyvern_tab_switch(
)
state._active_page = target
+ # Switching tabs invalidates any iframe frame reference from the old tab
+ state._working_frame = None
# bring_to_front is a no-op in headless but helps in headed mode
try:
@@ -319,6 +323,8 @@ async def skyvern_tab_close(
# Clear active page — get_working_page() will lazily pick the last remaining page
if closing_active or (state._active_page is not None and state._active_page is target):
state._active_page = None
+ # Closed tab's frame reference is no longer valid
+ state._working_frame = None
# Clean up inspection hooks for the closed page
state._hooked_page_ids.discard(target_id)
diff --git a/skyvern/core/script_generations/skyvern_page.py b/skyvern/core/script_generations/skyvern_page.py
index 568b728ee..772a98572 100644
--- a/skyvern/core/script_generations/skyvern_page.py
+++ b/skyvern/core/script_generations/skyvern_page.py
@@ -13,7 +13,7 @@ from pathlib import Path
from typing import TYPE_CHECKING, Any, Callable, Literal, overload
import structlog
-from playwright.async_api import Locator, Page
+from playwright.async_api import Frame, Locator, Page
from skyvern.config import settings
from skyvern.core.script_generations.fuzzy_matcher import match_option as _match_option
@@ -81,6 +81,7 @@ class SkyvernPage(Page):
self.page = page
self.current_label: str | None = None
self._ai = ai
+ self._working_frame: Frame | None = None
def __getattribute__(self, name: str) -> Any:
page = object.__getattribute__(self, "page")
@@ -94,6 +95,18 @@ class SkyvernPage(Page):
return object.__getattribute__(self, name)
+ @property
+ def _locator_scope(self) -> Page | Frame:
+ """Return the current locator scope: the working iframe if set, otherwise the page.
+
+ Use for element interaction (locator, click, fill). Keep self.page for
+ page-level operations (goto, keyboard, url, title, evaluate, reload, content).
+ """
+ frame = object.__getattribute__(self, "_working_frame")
+ if frame is not None:
+ return frame
+ return object.__getattribute__(self, "page")
+
async def _decorate_call(
self,
fn: Callable,
@@ -280,7 +293,7 @@ class SkyvernPage(Page):
if not selector:
raise ValueError("mode='direct' requires a selector.")
timeout = kwargs.pop("timeout", settings.BROWSER_ACTION_TIMEOUT_MS)
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await locator.click(timeout=timeout, **kwargs)
return selector
@@ -303,7 +316,7 @@ class SkyvernPage(Page):
error_to_raise = None
if selector:
try:
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await self._prepare_element(locator, timeout=timeout)
await locator.click(timeout=timeout, **kwargs)
return selector
@@ -314,7 +327,7 @@ class SkyvernPage(Page):
try:
await self.page.keyboard.press("Escape")
await asyncio.sleep(0.3)
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await locator.click(timeout=timeout, **kwargs)
LOG.info(
"CSS selector click succeeded after dismissing overlay",
@@ -353,7 +366,7 @@ class SkyvernPage(Page):
)
if selector:
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
await locator.click(timeout=timeout, **kwargs)
return selector
@@ -372,7 +385,7 @@ class SkyvernPage(Page):
if not selector:
raise ValueError("Hover requires a selector.")
- locator = self.page.locator(selector, **kwargs)
+ locator = self._locator_scope.locator(selector, **kwargs)
await locator.scroll_into_view_if_needed()
await locator.hover(timeout=timeout)
if hold_seconds and hold_seconds > 0:
@@ -468,7 +481,7 @@ class SkyvernPage(Page):
if value is None:
raise ValueError("mode='direct' requires a value.")
timeout = kwargs.pop("timeout", settings.BROWSER_ACTION_TIMEOUT_MS)
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await locator.fill(value, timeout=timeout, **kwargs)
return value
@@ -711,7 +724,7 @@ class SkyvernPage(Page):
timeout: float = settings.BROWSER_ACTION_TIMEOUT_MS,
) -> str:
"""Type into an autocomplete input and click the best matching dropdown option."""
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
# Clear existing value and type character-by-character to trigger autocomplete
await locator.clear(timeout=timeout)
@@ -802,7 +815,7 @@ class SkyvernPage(Page):
for sel in selectors_to_try:
try:
- locator = self.page.locator(sel)
+ locator = self._locator_scope.locator(sel)
count = await locator.count()
if count > 0:
return [locator.nth(i) for i in range(min(count, 10))] # cap at 10
@@ -881,7 +894,7 @@ class SkyvernPage(Page):
totp_identifier=totp_identifier,
totp_url=totp_url,
)
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await self._prepare_element(locator, timeout=timeout)
# Use locator.fill() (programmatic, single-shot) instead of typing
# character-by-character. Sequential typing triggers autocomplete
@@ -926,7 +939,7 @@ class SkyvernPage(Page):
if not selector:
raise ValueError("Selector is required but was not provided")
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await locator.fill(value, timeout=timeout)
return value
@@ -987,7 +1000,7 @@ class SkyvernPage(Page):
files,
organization_id=context.organization_id if context else None,
)
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
await locator.set_input_files(file_path, **kwargs)
except Exception as e:
error_to_raise = e
@@ -1022,7 +1035,7 @@ class SkyvernPage(Page):
raise ValueError("Parameter 'files' is required but was not provided")
file_path = await download_file_from_url(files, organization_id=context.organization_id if context else None)
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
await locator.set_input_files(file_path, timeout=timeout, **kwargs)
return files
@@ -1110,7 +1123,7 @@ class SkyvernPage(Page):
error_to_raise = None
if selector:
try:
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
await locator.select_option(value, timeout=timeout, **kwargs)
return value
except Exception as e:
@@ -1138,7 +1151,7 @@ class SkyvernPage(Page):
timeout=timeout,
)
if selector:
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
await locator.select_option(value, timeout=timeout, **kwargs)
return value
@@ -1561,7 +1574,7 @@ class SkyvernPage(Page):
)
elif field_tag == "select":
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
try:
await locator.select_option(label=str(value), timeout=settings.BROWSER_ACTION_TIMEOUT_MS)
except Exception:
@@ -1635,14 +1648,14 @@ class SkyvernPage(Page):
# Combobox / React Select: click to open, type to filter,
# click the matching option.
str_value = str(value)
- locator = self.page.locator(selector).first
+ locator = self._locator_scope.locator(selector).first
await locator.click(timeout=5000)
await asyncio.sleep(0.3)
await locator.fill("")
search_text = str_value.split(",")[0].strip()[:25]
await self.page.keyboard.type(search_text, delay=50)
await asyncio.sleep(0.5)
- option = self.page.locator('[class*="select__option"]:visible').first
+ option = self._locator_scope.locator('[class*="select__option"]:visible').first
try:
await option.click(timeout=3000)
except Exception:
@@ -2786,7 +2799,7 @@ class SkyvernPage(Page):
elif method == "select_option":
# Planned values are typically option labels (display text) from the batch planner.
# Try matching by label first, then fall back to value attribute.
- locator = self.page.locator(selector)
+ locator = self._locator_scope.locator(selector)
try:
await locator.select_option(label=str(planned_value), timeout=settings.BROWSER_ACTION_TIMEOUT_MS)
except Exception:
@@ -2813,7 +2826,7 @@ class SkyvernPage(Page):
if method == "fill_autocomplete":
await self.fill_autocomplete(selector=alt_selector, value=str(planned_value), ai=None)
elif method == "select_option":
- locator = self.page.locator(alt_selector)
+ locator = self._locator_scope.locator(alt_selector)
try:
await locator.select_option(
label=str(planned_value), timeout=settings.BROWSER_ACTION_TIMEOUT_MS
@@ -2854,7 +2867,7 @@ class SkyvernPage(Page):
# Post-fill validation for text fields: detect essays in short-text fields
if method in ("fill", "fill_autocomplete") and hint == "short text":
try:
- actual = await self.page.locator(selector).input_value(timeout=2000)
+ actual = await self._locator_scope.locator(selector).input_value(timeout=2000)
if actual and len(actual) > 100:
LOG.warning(
"fill_with_planned_value: value too long for short text field, re-filling with AI",
@@ -2937,8 +2950,12 @@ class SkyvernPage(Page):
)
return False
- # Check for visible error messages
- error_count = await self.page.locator(
+ # Check for visible error messages.
+ # NOTE: When a frame is active, this only detects errors inside that
+ # frame (e.g. payment form errors). Main-page error badges are not
+ # visible from within an iframe — this is intentional for frame-scoped
+ # validation but callers should be aware of the scoping.
+ error_count = await self._locator_scope.locator(
"[class*='error']:visible, [class*='invalid']:visible, "
"[role='alert']:visible, [aria-invalid='true']:visible"
).count()
@@ -3293,7 +3310,7 @@ class SkyvernPage(Page):
)
if selector:
- return self.page.locator(selector, **kwargs)
+ return self._locator_scope.locator(selector, **kwargs)
if prompt:
return AILocator(
@@ -3317,7 +3334,7 @@ class SkyvernPage(Page):
)
if selector:
- return self.page.locator(selector, **kwargs)
+ return self._locator_scope.locator(selector, **kwargs)
raise ValueError("Selector is required but was not provided")
diff --git a/skyvern/library/skyvern_browser_page.py b/skyvern/library/skyvern_browser_page.py
index aed52c9d3..84ff71ce0 100644
--- a/skyvern/library/skyvern_browser_page.py
+++ b/skyvern/library/skyvern_browser_page.py
@@ -1,6 +1,6 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
-from playwright.async_api import Page
+from playwright.async_api import Frame, Page
from skyvern.core.script_generations.skyvern_page import SkyvernPage
from skyvern.library.skyvern_browser_page_agent import SkyvernBrowserPageAgent
@@ -38,6 +38,79 @@ class SkyvernBrowserPage(SkyvernPage):
self._browser = browser
self.agent = SkyvernBrowserPageAgent(browser, page)
+ async def frame_switch(
+ self,
+ *,
+ selector: str | None = None,
+ name: str | None = None,
+ index: int | None = None,
+ ) -> dict[str, Any]:
+ """Switch the working context to an iframe. Exactly one parameter required.
+
+ Args:
+ selector: CSS selector for the iframe element (uses content_frame()).
+ name: Frame name attribute.
+ index: Frame index in page.frames list (0 = main frame).
+
+ Returns:
+ Dict with frame name, url, and the parameter used to switch.
+ """
+ params = sum(p is not None for p in (selector, name, index))
+ if params != 1:
+ raise ValueError("Exactly one of selector, name, or index is required.")
+
+ frame: Frame | None = None
+
+ if selector is not None:
+ element = await self.page.query_selector(selector)
+ if element is None:
+ raise ValueError(f"Selector '{selector}' did not match any element.")
+ frame = await element.content_frame()
+ if frame is None:
+ raise ValueError(f"Selector '{selector}' did not resolve to an iframe.")
+
+ elif name is not None:
+ frame = self.page.frame(name=name)
+ if frame is None:
+ raise ValueError(f"No frame found with name '{name}'.")
+
+ elif index is not None:
+ frames = self.page.frames
+ if index < 0 or index >= len(frames):
+ raise ValueError(f"Frame index {index} out of range (0-{len(frames) - 1}).")
+ frame = frames[index]
+
+ self._working_frame = frame
+ return {
+ "name": frame.name if frame else None,
+ "url": frame.url if frame else None,
+ "selector": selector,
+ "frame_name": name,
+ "index": index,
+ }
+
+ def frame_main(self) -> dict[str, str]:
+ """Switch back to the main page frame, clearing the working iframe."""
+ self._working_frame = None
+ return {"status": "switched_to_main_frame"}
+
+ async def frame_list(self) -> list[dict[str, Any]]:
+ """List all frames on the current page.
+
+ Returns:
+ List of dicts with name, url, is_main, and index for each frame.
+ """
+ frames = self.page.frames
+ return [
+ {
+ "index": i,
+ "name": f.name,
+ "url": f.url,
+ "is_main": f == self.page.main_frame,
+ }
+ for i, f in enumerate(frames)
+ ]
+
async def act(
self,
prompt: str,
diff --git a/tests/unit/test_iframe_e2e.py b/tests/unit/test_iframe_e2e.py
new file mode 100644
index 000000000..cbadd87d2
--- /dev/null
+++ b/tests/unit/test_iframe_e2e.py
@@ -0,0 +1,430 @@
+"""E2E tests for iframe support using a real headless Chromium browser.
+
+Tests the full stack: SkyvernPage._locator_scope, frame_switch/main/list on
+SkyvernBrowserPage, and the MCP tool functions — all against real iframes.
+
+Skipped in CI when Playwright browsers are not installed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+import pytest_asyncio
+from playwright.async_api import async_playwright
+
+from skyvern.core.script_generations.skyvern_page_ai import SkyvernPageAi
+from skyvern.library.skyvern_browser_page import SkyvernBrowserPage
+
+
+def _has_playwright_browser() -> bool:
+ """Check that Playwright's chromium binary exists for the current installed version."""
+ try:
+ from playwright.sync_api import sync_playwright # noqa: PLC0415
+
+ with sync_playwright() as p:
+ return Path(p.chromium.executable_path).exists()
+ except Exception:
+ return False
+
+
+_skip_no_browser = pytest.mark.skipif(
+ not _has_playwright_browser(),
+ reason="Requires Playwright browsers installed (run: playwright install chromium)",
+)
+
+pytestmark = _skip_no_browser
+
+# HTML fixture: main page with a form AND an iframe containing another form.
+MAIN_HTML = """\
+<!DOCTYPE html>
+<html>
+<body>
+ <h1 id="main-heading">Main Page</h1>
+ <input id="main-input" type="text" value="" placeholder="Main input" />
+ <button id="main-btn" onclick="document.getElementById('main-input').value='clicked'">Main Button</button>
+
+ <iframe id="payment-frame" name="payment" srcdoc='
+ <!DOCTYPE html>
+ <html><body>
+ <h2 id="iframe-heading">Payment Form</h2>
+ <input id="card-number" type="text" value="" placeholder="Card number" />
+ <input id="card-name" type="text" value="" placeholder="Name on card" />
+ <button id="pay-btn" onclick="document.getElementById(&apos;card-number&apos;).value=&apos;paid&apos;">Pay</button>
+ </body></html>
+ '></iframe>
+
+ <iframe id="empty-frame" name="empty" srcdoc="<html><body><p>Empty</p></body></html>"></iframe>
+</body>
+</html>
+"""
+
+
+class _NoopAi(SkyvernPageAi):
+ """Stub AI that raises if called — e2e tests use direct selectors only."""
+
+ def __init__(self) -> None:
+ pass
+
+ async def ai_click(self, **kwargs: Any) -> Any:
+ raise NotImplementedError("AI should not be called in e2e tests")
+
+ async def ai_input_text(self, **kwargs: Any) -> Any:
+ raise NotImplementedError("AI should not be called in e2e tests")
+
+ async def ai_act(self, prompt: str) -> Any:
+ raise NotImplementedError("AI should not be called in e2e tests")
+
+
+class _TestPage(SkyvernBrowserPage):
+ """SkyvernBrowserPage that doesn't need a full SkyvernBrowser."""
+
+ def __init__(self, page: Any) -> None:
+ # Use SkyvernPage.__init__ directly to avoid SkyvernBrowser dependency
+ from skyvern.core.script_generations.skyvern_page import SkyvernPage
+
+ SkyvernPage.__init__(self, page, _NoopAi())
+ self._browser = MagicMock()
+ self.agent = MagicMock()
+
+
+@pytest_asyncio.fixture
+async def browser_page():
+ """Launch a real headless Chromium and set up the test page."""
+ async with async_playwright() as p:
+ browser = await p.chromium.launch(headless=True)
+ context = await browser.new_context()
+ pw_page = await context.new_page()
+ await pw_page.set_content(MAIN_HTML)
+ # Wait for iframes to load
+ await pw_page.wait_for_selector("#payment-frame")
+ await asyncio.sleep(0.3)
+
+ page = _TestPage(pw_page)
+ yield page
+
+ await context.close()
+ await browser.close()
+
+
+# ---------------------------------------------------------------------------
+# E2E: _locator_scope with real iframes
+# ---------------------------------------------------------------------------
+
+
+class TestLocatorScopeE2E:
+ @pytest.mark.asyncio
+ async def test_locator_scope_defaults_to_page(self, browser_page: _TestPage) -> None:
+ heading = await browser_page._locator_scope.locator("#main-heading").text_content()
+ assert heading == "Main Page"
+
+ @pytest.mark.asyncio
+ async def test_locator_scope_scopes_to_frame(self, browser_page: _TestPage) -> None:
+ # Switch to iframe
+ await browser_page.frame_switch(selector="#payment-frame")
+ heading = await browser_page._locator_scope.locator("#iframe-heading").text_content()
+ assert heading == "Payment Form"
+
+ @pytest.mark.asyncio
+ async def test_main_page_element_not_found_in_iframe(self, browser_page: _TestPage) -> None:
+ await browser_page.frame_switch(selector="#payment-frame")
+ count = await browser_page._locator_scope.locator("#main-heading").count()
+ assert count == 0
+
+ @pytest.mark.asyncio
+ async def test_iframe_element_not_found_on_main_page(self, browser_page: _TestPage) -> None:
+ count = await browser_page._locator_scope.locator("#card-number").count()
+ assert count == 0
+
+
+# ---------------------------------------------------------------------------
+# E2E: frame_switch / frame_main / frame_list
+# ---------------------------------------------------------------------------
+
+
+class TestFrameSwitchE2E:
+ @pytest.mark.asyncio
+ async def test_switch_by_selector(self, browser_page: _TestPage) -> None:
+ result = await browser_page.frame_switch(selector="#payment-frame")
+ assert result["name"] == "payment"
+ assert browser_page._working_frame is not None
+
+ @pytest.mark.asyncio
+ async def test_switch_by_name(self, browser_page: _TestPage) -> None:
+ result = await browser_page.frame_switch(name="payment")
+ assert result["name"] == "payment"
+ assert browser_page._working_frame is not None
+
+ @pytest.mark.asyncio
+ async def test_switch_by_index(self, browser_page: _TestPage) -> None:
+ # Index 0 = main frame, 1 = payment iframe, 2 = empty iframe
+ result = await browser_page.frame_switch(index=1)
+ assert result["name"] == "payment"
+
+ @pytest.mark.asyncio
+ async def test_switch_back_to_main(self, browser_page: _TestPage) -> None:
+ await browser_page.frame_switch(selector="#payment-frame")
+ assert browser_page._working_frame is not None
+
+ browser_page.frame_main()
+ assert browser_page._working_frame is None
+
+ heading = await browser_page._locator_scope.locator("#main-heading").text_content()
+ assert heading == "Main Page"
+
+ @pytest.mark.asyncio
+ async def test_switch_to_different_iframe(self, browser_page: _TestPage) -> None:
+ await browser_page.frame_switch(name="payment")
+ heading = await browser_page._locator_scope.locator("#iframe-heading").text_content()
+ assert heading == "Payment Form"
+
+ await browser_page.frame_switch(name="empty")
+ text = await browser_page._locator_scope.locator("p").text_content()
+ assert text == "Empty"
+
+
+class TestFrameListE2E:
+ @pytest.mark.asyncio
+ async def test_lists_main_and_iframes(self, browser_page: _TestPage) -> None:
+ frames = await browser_page.frame_list()
+ assert len(frames) >= 3 # main + payment + empty
+ assert frames[0]["is_main"] is True
+ names = [f["name"] for f in frames]
+ assert "payment" in names
+ assert "empty" in names
+
+
+# ---------------------------------------------------------------------------
+# E2E: interactions INSIDE an iframe
+# ---------------------------------------------------------------------------
+
+
+class TestIframeInteractionE2E:
+ @pytest.mark.asyncio
+ async def test_fill_inside_iframe(self, browser_page: _TestPage) -> None:
+ await browser_page.frame_switch(selector="#payment-frame")
+
+ locator = browser_page._locator_scope.locator("#card-number")
+ await locator.fill("4242424242424242")
+
+ value = await locator.input_value()
+ assert value == "4242424242424242"
+
+ @pytest.mark.asyncio
+ async def test_click_inside_iframe(self, browser_page: _TestPage) -> None:
+ await browser_page.frame_switch(selector="#payment-frame")
+
+ await browser_page._locator_scope.locator("#pay-btn").click()
+ value = await browser_page._locator_scope.locator("#card-number").input_value()
+ assert value == "paid"
+
+ @pytest.mark.asyncio
+ async def test_fill_main_page_unaffected_by_iframe(self, browser_page: _TestPage) -> None:
+ # Fill in iframe
+ await browser_page.frame_switch(selector="#payment-frame")
+ await browser_page._locator_scope.locator("#card-number").fill("1234")
+
+ # Switch back and verify main page
+ browser_page.frame_main()
+ main_value = await browser_page._locator_scope.locator("#main-input").input_value()
+ assert main_value == "" # untouched
+
+ @pytest.mark.asyncio
+ async def test_click_main_page_after_iframe(self, browser_page: _TestPage) -> None:
+ await browser_page.frame_switch(selector="#payment-frame")
+ await browser_page._locator_scope.locator("#card-number").fill("4242")
+ browser_page.frame_main()
+
+ await browser_page._locator_scope.locator("#main-btn").click()
+ value = await browser_page._locator_scope.locator("#main-input").input_value()
+ assert value == "clicked"
+
+
+# ---------------------------------------------------------------------------
+# E2E: SkyvernPage interaction methods inside iframe
+# ---------------------------------------------------------------------------
+
+
+class TestSkyvernPageMethodsInIframe:
+ @pytest.mark.asyncio
+ async def test_click_method_scopes_to_iframe(self, browser_page: _TestPage) -> None:
+ """Test that SkyvernPage.click() with ai=None uses _locator_scope."""
+ await browser_page.frame_switch(selector="#payment-frame")
+ # Use click with ai=None and mode=direct to go through the direct path
+ await browser_page.click("#pay-btn", ai=None, mode="direct")
+ value = await browser_page._locator_scope.locator("#card-number").input_value()
+ assert value == "paid"
+
+ @pytest.mark.asyncio
+ async def test_fill_method_scopes_to_iframe(self, browser_page: _TestPage) -> None:
+ """Test that SkyvernPage.fill() with mode=direct uses _locator_scope."""
+ await browser_page.frame_switch(selector="#payment-frame")
+ await browser_page.fill("#card-name", "John Doe", ai=None, mode="direct")
+ value = await browser_page._locator_scope.locator("#card-name").input_value()
+ assert value == "John Doe"
+
+ @pytest.mark.asyncio
+ async def test_hover_method_scopes_to_iframe(self, browser_page: _TestPage) -> None:
+ """Test that SkyvernPage.hover() uses _locator_scope."""
+ await browser_page.frame_switch(selector="#payment-frame")
+ # hover shouldn't throw — just verifying it resolves within frame
+ await browser_page.hover("#pay-btn")
+
+
+# ---------------------------------------------------------------------------
+# E2E: CLI frame state persistence round-trip
+#
+# These tests exercise the actual _apply_cli_frame_state code path:
+# save frame identifiers to CLIState (file-backed), create a FRESH page
+# (simulating a new CLI invocation), call _apply_cli_frame_state, then
+# verify actions target the iframe — not the main page.
+# ---------------------------------------------------------------------------
+
+
+class TestCLIFrameStatePersistence:
+ @pytest.mark.asyncio
+ async def test_cli_frame_state_reapplied_by_selector(self, browser_page: _TestPage, tmp_path: Any) -> None:
+ """frame_switch by selector → save to CLIState → fresh page → _apply_cli_frame_state → in iframe."""
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, save_state
+ from skyvern.cli.commands.browser import _apply_cli_frame_state
+
+ # Patch STATE_FILE to a temp location so we don't touch the user's real state
+ orig_file = state_mod.STATE_FILE
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ # Simulate: user ran `skyvern browser frame switch --selector "#payment-frame"`
+ save_state(CLIState(session_id="test", mode="cloud", frame_selector="#payment-frame"))
+
+ # Simulate: new CLI invocation gets a FRESH page (no _working_frame)
+ assert browser_page._working_frame is None
+
+ # This is the code under test
+ await _apply_cli_frame_state(browser_page)
+
+ # Verify: page is now scoped to the iframe
+ assert browser_page._working_frame is not None
+ heading = await browser_page._locator_scope.locator("#iframe-heading").text_content()
+ assert heading == "Payment Form"
+
+ # Verify: main page elements are NOT visible from the iframe scope
+ count = await browser_page._locator_scope.locator("#main-heading").count()
+ assert count == 0
+ finally:
+ state_mod.STATE_FILE = orig_file
+
+ @pytest.mark.asyncio
+ async def test_cli_frame_state_reapplied_by_name(self, browser_page: _TestPage, tmp_path: Any) -> None:
+ """frame_switch by name → save to CLIState → fresh page → _apply_cli_frame_state → in iframe."""
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, save_state
+ from skyvern.cli.commands.browser import _apply_cli_frame_state
+
+ orig_file = state_mod.STATE_FILE
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ save_state(CLIState(session_id="test", mode="cloud", frame_name="payment"))
+
+ assert browser_page._working_frame is None
+ await _apply_cli_frame_state(browser_page)
+
+ assert browser_page._working_frame is not None
+ heading = await browser_page._locator_scope.locator("#iframe-heading").text_content()
+ assert heading == "Payment Form"
+ finally:
+ state_mod.STATE_FILE = orig_file
+
+ @pytest.mark.asyncio
+ async def test_cli_frame_state_reapplied_by_index(self, browser_page: _TestPage, tmp_path: Any) -> None:
+ """frame_switch by index → save to CLIState → fresh page → _apply_cli_frame_state → in iframe."""
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, save_state
+ from skyvern.cli.commands.browser import _apply_cli_frame_state
+
+ orig_file = state_mod.STATE_FILE
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ # Index 1 = payment iframe (0 = main frame)
+ save_state(CLIState(session_id="test", mode="cloud", frame_index=1))
+
+ assert browser_page._working_frame is None
+ await _apply_cli_frame_state(browser_page)
+
+ assert browser_page._working_frame is not None
+ heading = await browser_page._locator_scope.locator("#iframe-heading").text_content()
+ assert heading == "Payment Form"
+ finally:
+ state_mod.STATE_FILE = orig_file
+
+ @pytest.mark.asyncio
+ async def test_cli_frame_state_noop_when_no_frame(self, browser_page: _TestPage, tmp_path: Any) -> None:
+ """No frame state in CLIState → _apply_cli_frame_state is a no-op."""
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, save_state
+ from skyvern.cli.commands.browser import _apply_cli_frame_state
+
+ orig_file = state_mod.STATE_FILE
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ save_state(CLIState(session_id="test", mode="cloud"))
+
+ await _apply_cli_frame_state(browser_page)
+
+ assert browser_page._working_frame is None
+ heading = await browser_page._locator_scope.locator("#main-heading").text_content()
+ assert heading == "Main Page"
+ finally:
+ state_mod.STATE_FILE = orig_file
+
+ @pytest.mark.asyncio
+ async def test_cli_frame_state_clears_on_stale_selector(self, browser_page: _TestPage, tmp_path: Any) -> None:
+ """Stale selector in CLIState → _apply_cli_frame_state clears state and stays on main page."""
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, load_state, save_state
+ from skyvern.cli.commands.browser import _apply_cli_frame_state
+
+ orig_file = state_mod.STATE_FILE
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ save_state(CLIState(session_id="test", mode="cloud", frame_selector="#nonexistent-frame"))
+
+ await _apply_cli_frame_state(browser_page)
+
+ # Frame state should be cleared since the selector doesn't exist
+ assert browser_page._working_frame is None
+ reloaded = load_state()
+ assert reloaded is not None
+ assert reloaded.frame_selector is None
+ assert reloaded.frame_name is None
+ assert reloaded.frame_index is None
+ finally:
+ state_mod.STATE_FILE = orig_file
+
+ @pytest.mark.asyncio
+ async def test_cli_fill_inside_iframe_after_state_restore(self, browser_page: _TestPage, tmp_path: Any) -> None:
+ """Full round-trip: save frame state → fresh page → restore → fill inside iframe."""
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, save_state
+ from skyvern.cli.commands.browser import _apply_cli_frame_state
+
+ orig_file = state_mod.STATE_FILE
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ save_state(CLIState(session_id="test", mode="cloud", frame_selector="#payment-frame"))
+
+ await _apply_cli_frame_state(browser_page)
+
+ # Now do what a CLI `type` command would do after _apply_cli_frame_state
+ await browser_page._locator_scope.locator("#card-number").fill("4242424242424242")
+ value = await browser_page._locator_scope.locator("#card-number").input_value()
+ assert value == "4242424242424242"
+
+ # Main page input should be untouched
+ main_value = await browser_page.page.locator("#main-input").input_value()
+ assert main_value == ""
+ finally:
+ state_mod.STATE_FILE = orig_file
diff --git a/tests/unit/test_iframe_mcp_e2e.py b/tests/unit/test_iframe_mcp_e2e.py
new file mode 100644
index 000000000..2f319808e
--- /dev/null
+++ b/tests/unit/test_iframe_mcp_e2e.py
@@ -0,0 +1,230 @@
+"""E2E test for iframe MCP tools with a real browser.
+
+Exercises the MCP tool chain (frame_list, frame_switch, frame_main) through
+real Playwright + SessionState wiring, without requiring Skyvern's local
+browser launcher infrastructure.
+
+Skipped in CI when Playwright browsers are not installed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import pytest
+import pytest_asyncio
+from playwright.async_api import async_playwright
+
+from skyvern.cli.core.result import BrowserContext
+from skyvern.cli.core.session_manager import SessionState, get_current_session, set_current_session
+from skyvern.cli.mcp_tools.browser import skyvern_frame_list, skyvern_frame_main, skyvern_frame_switch
+
+
+def _has_playwright_browser() -> bool:
+ """Check that Playwright's chromium binary exists for the current installed version."""
+ try:
+ from playwright.sync_api import sync_playwright # noqa: PLC0415
+
+ with sync_playwright() as p:
+ return Path(p.chromium.executable_path).exists()
+ except Exception:
+ return False
+
+
+_skip_no_browser = pytest.mark.skipif(
+ not _has_playwright_browser(),
+ reason="Requires Playwright browsers installed (run: playwright install chromium)",
+)
+
+pytestmark = _skip_no_browser
+
+MAIN_HTML = """\
+<!DOCTYPE html>
+<html>
+<body>
+ <h1 id="main-heading">Main Page</h1>
+ <input id="main-input" type="text" value="" />
+ <iframe id="pay-frame" name="payment" srcdoc='
+ <!DOCTYPE html>
+ <html><body>
+ <h2 id="frame-heading">Payment</h2>
+ <input id="card" type="text" value="" placeholder="Card" />
+ </body></html>
+ '></iframe>
+</body>
+</html>
+"""
+
+
+class _FakeBrowserContext:
+ """Minimal browser context to satisfy get_page() hooks from tab management."""
+
+ def __init__(self, page: Any) -> None:
+ self.pages = [page]
+
+ def on(self, event: str, handler: Any) -> None:
+ pass # No-op for tests
+
+
+class _FakeBrowser:
+ """Minimal SkyvernBrowser substitute that wraps a real Playwright page."""
+
+ def __init__(self, page: Any) -> None:
+ self._page = page
+ self._browser_context = _FakeBrowserContext(page)
+
+ async def get_working_page(self) -> Any:
+ # Return a lightweight wrapper that has the frame methods
+ return _WrappedPage(self._page)
+
+
+class _WrappedPage:
+ """Thin wrapper around Playwright Page to add frame_switch/main/list."""
+
+ def __init__(self, page: Any) -> None:
+ self.page = page
+ self._working_frame = None
+
+ @property
+ def _locator_scope(self) -> Any:
+ if self._working_frame is not None:
+ return self._working_frame
+ return self.page
+
+ async def frame_switch(
+ self, *, selector: str | None = None, name: str | None = None, index: int | None = None
+ ) -> dict[str, Any]:
+ params = sum(p is not None for p in (selector, name, index))
+ if params != 1:
+ raise ValueError("Exactly one of selector, name, or index is required.")
+
+ frame = None
+ if selector is not None:
+ element = await self.page.query_selector(selector)
+ if element is None:
+ raise ValueError(f"Selector '{selector}' did not match any element.")
+ frame = await element.content_frame()
+ if frame is None:
+ raise ValueError(f"Selector '{selector}' did not resolve to an iframe.")
+ elif name is not None:
+ frame = self.page.frame(name=name)
+ if frame is None:
+ raise ValueError(f"No frame found with name '{name}'.")
+ elif index is not None:
+ frames = self.page.frames
+ if index < 0 or index >= len(frames):
+ raise ValueError(f"Frame index {index} out of range.")
+ frame = frames[index]
+
+ self._working_frame = frame
+ return {"name": frame.name if frame else None, "url": frame.url if frame else None}
+
+ def frame_main(self) -> dict[str, str]:
+ self._working_frame = None
+ return {"status": "switched_to_main_frame"}
+
+ async def frame_list(self) -> list[dict[str, Any]]:
+ return [
+ {"index": i, "name": f.name, "url": f.url, "is_main": f == self.page.main_frame}
+ for i, f in enumerate(self.page.frames)
+ ]
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self.page, name)
+
+
+@pytest_asyncio.fixture
+async def mcp_session():
+ """Set up a real Playwright browser and wire it into SessionState."""
+ async with async_playwright() as p:
+ try:
+ browser = await p.chromium.launch(headless=True)
+ except Exception:
+ pytest.skip("Playwright chromium binary not available")
+ context = await browser.new_context()
+ pw_page = await context.new_page()
+ await pw_page.set_content(MAIN_HTML)
+ await asyncio.sleep(0.3)
+
+ fake_browser = _FakeBrowser(pw_page)
+ ctx = BrowserContext(mode="local")
+ state = SessionState(browser=fake_browser, context=ctx) # type: ignore[arg-type]
+ set_current_session(state)
+
+ yield state
+
+ set_current_session(SessionState())
+ await context.close()
+ await browser.close()
+
+
+# ---------------------------------------------------------------------------
+# MCP tool e2e tests
+# ---------------------------------------------------------------------------
+
+
+async def test_mcp_frame_list_real_browser(mcp_session: SessionState) -> None:
+ result = await skyvern_frame_list()
+ assert result["ok"] is True
+ frames = result["data"]["frames"]
+ assert len(frames) >= 2
+ names = [f["name"] for f in frames]
+ assert "payment" in names
+ assert result["data"]["count"] >= 2
+
+
+async def test_mcp_frame_switch_by_selector(mcp_session: SessionState) -> None:
+ result = await skyvern_frame_switch(selector="#pay-frame")
+ assert result["ok"] is True
+ assert result["data"]["frame_name"] == "payment"
+ assert result["data"]["switched_by"] == "selector"
+
+ # Verify SessionState was updated
+ assert mcp_session._working_frame is not None
+
+
+async def test_mcp_frame_switch_by_name(mcp_session: SessionState) -> None:
+ result = await skyvern_frame_switch(name="payment")
+ assert result["ok"] is True
+ assert result["data"]["switched_by"] == "name"
+ assert mcp_session._working_frame is not None
+
+
+async def test_mcp_frame_main_clears_state(mcp_session: SessionState) -> None:
+ # Switch in first
+ await skyvern_frame_switch(selector="#pay-frame")
+ assert mcp_session._working_frame is not None
+
+ # Switch back
+ result = await skyvern_frame_main()
+ assert result["ok"] is True
+ assert mcp_session._working_frame is None
+
+
+async def test_mcp_frame_switch_invalid_selector(mcp_session: SessionState) -> None:
+ result = await skyvern_frame_switch(selector="#nonexistent")
+ assert result["ok"] is False
+
+
+async def test_mcp_frame_switch_persists_across_calls(mcp_session: SessionState) -> None:
+ """Frame state set by frame_switch persists across subsequent get_page() calls."""
+ # Switch into iframe
+ await skyvern_frame_switch(selector="#pay-frame")
+
+ # Simulate a subsequent MCP call — get_page() reads _working_frame from SessionState
+ state = get_current_session()
+ assert state._working_frame is not None
+
+ # The next get_page() call would set page._working_frame from state._working_frame
+ # Verify the state is there for the propagation
+ frame = state._working_frame
+ heading = await frame.locator("#frame-heading").text_content()
+ assert heading == "Payment"
diff --git a/tests/unit/test_iframe_support.py b/tests/unit/test_iframe_support.py
new file mode 100644
index 000000000..35c27b4f0
--- /dev/null
+++ b/tests/unit/test_iframe_support.py
@@ -0,0 +1,496 @@
+"""Unit tests for iframe support: _locator_scope, frame_switch, frame_main, frame_list."""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from skyvern.cli.core.browser_ops import do_frame_list, do_frame_main, do_frame_switch
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_fake_frame(*, name: str = "", url: str = "about:blank") -> MagicMock:
+ frame = MagicMock()
+ frame.name = name
+ frame.url = url
+ frame.locator = MagicMock(return_value=MagicMock())
+ return frame
+
+
+def _make_fake_page(frames: list[MagicMock] | None = None) -> MagicMock:
+ """Build a mock Playwright Page with .locator(), .frames, .main_frame, .frame()."""
+ page = MagicMock()
+ all_frames = frames or [_make_fake_frame(name="main", url="https://example.com")]
+ page.frames = all_frames
+ page.main_frame = all_frames[0]
+ page.locator = MagicMock(return_value=MagicMock())
+ page.frame = MagicMock(return_value=None)
+ return page
+
+
+class FakeSkyvernPage:
+ """Minimal stand-in for SkyvernPage to test _locator_scope without Playwright."""
+
+ def __init__(self, page: Any, working_frame: Any = None) -> None:
+ self.page = page
+ self._working_frame = working_frame
+
+ @property
+ def _locator_scope(self) -> Any:
+ frame = object.__getattribute__(self, "_working_frame")
+ if frame is not None:
+ return frame
+ return object.__getattribute__(self, "page")
+
+
+class FakeSkyvernBrowserPage(FakeSkyvernPage):
+ """Minimal stand-in for SkyvernBrowserPage to test frame methods."""
+
+ async def frame_switch(
+ self, *, selector: str | None = None, name: str | None = None, index: int | None = None
+ ) -> dict[str, Any]:
+ params = sum(p is not None for p in (selector, name, index))
+ if params != 1:
+ raise ValueError("Exactly one of selector, name, or index is required.")
+
+ frame = None
+
+ if selector is not None:
+ element = await self.page.query_selector(selector)
+ if element is None:
+ raise ValueError(f"Selector '{selector}' did not match any element.")
+ frame = await element.content_frame()
+ if frame is None:
+ raise ValueError(f"Selector '{selector}' did not resolve to an iframe.")
+ elif name is not None:
+ frame = self.page.frame(name=name)
+ if frame is None:
+ raise ValueError(f"No frame found with name '{name}'.")
+ elif index is not None:
+ frames = self.page.frames
+ if index < 0 or index >= len(frames):
+ raise ValueError(f"Frame index {index} out of range (0-{len(frames) - 1}).")
+ frame = frames[index]
+
+ self._working_frame = frame
+ return {
+ "name": frame.name if frame else None,
+ "url": frame.url if frame else None,
+ "selector": selector,
+ "frame_name": name,
+ "index": index,
+ }
+
+ def frame_main(self) -> dict[str, str]:
+ self._working_frame = None
+ return {"status": "switched_to_main_frame"}
+
+ async def frame_list(self) -> list[dict[str, Any]]:
+ frames = self.page.frames
+ return [
+ {"index": i, "name": f.name, "url": f.url, "is_main": f == self.page.main_frame}
+ for i, f in enumerate(frames)
+ ]
+
+
+# ---------------------------------------------------------------------------
+# _locator_scope tests
+# ---------------------------------------------------------------------------
+
+
+class TestLocatorScope:
+ def test_returns_page_when_no_frame(self) -> None:
+ page = _make_fake_page()
+ sp = FakeSkyvernPage(page)
+ assert sp._locator_scope is page
+
+ def test_returns_frame_when_set(self) -> None:
+ page = _make_fake_page()
+ frame = _make_fake_frame(name="iframe1")
+ sp = FakeSkyvernPage(page, working_frame=frame)
+ assert sp._locator_scope is frame
+
+ def test_returns_page_after_clearing_frame(self) -> None:
+ page = _make_fake_page()
+ frame = _make_fake_frame()
+ sp = FakeSkyvernPage(page, working_frame=frame)
+ assert sp._locator_scope is frame
+ sp._working_frame = None
+ assert sp._locator_scope is page
+
+ def test_locator_call_delegates_to_frame(self) -> None:
+ page = _make_fake_page()
+ frame = _make_fake_frame()
+ sp = FakeSkyvernPage(page, working_frame=frame)
+ sp._locator_scope.locator("#btn")
+ frame.locator.assert_called_once_with("#btn")
+ page.locator.assert_not_called()
+
+ def test_locator_call_delegates_to_page_when_no_frame(self) -> None:
+ page = _make_fake_page()
+ sp = FakeSkyvernPage(page)
+ sp._locator_scope.locator("#btn")
+ page.locator.assert_called_once_with("#btn")
+
+
+# ---------------------------------------------------------------------------
+# frame_switch tests
+# ---------------------------------------------------------------------------
+
+
+class TestFrameSwitch:
+ @pytest.mark.asyncio
+ async def test_switch_by_selector(self) -> None:
+ iframe = _make_fake_frame(name="payment", url="https://payment.example.com/v3")
+ element_mock = MagicMock()
+ element_mock.content_frame = AsyncMock(return_value=iframe)
+
+ page = _make_fake_page()
+ page.query_selector = AsyncMock(return_value=element_mock)
+
+ sp = FakeSkyvernBrowserPage(page)
+ result = await sp.frame_switch(selector="#payment-frame")
+
+ assert sp._working_frame is iframe
+ assert result["name"] == "payment"
+ assert result["url"] == "https://payment.example.com/v3"
+
+ @pytest.mark.asyncio
+ async def test_switch_by_name(self) -> None:
+ iframe = _make_fake_frame(name="checkout", url="https://checkout.com")
+ page = _make_fake_page()
+ page.frame = MagicMock(return_value=iframe)
+
+ sp = FakeSkyvernBrowserPage(page)
+ result = await sp.frame_switch(name="checkout")
+
+ assert sp._working_frame is iframe
+ assert result["frame_name"] == "checkout"
+
+ @pytest.mark.asyncio
+ async def test_switch_by_index(self) -> None:
+ main = _make_fake_frame(name="main", url="https://example.com")
+ iframe = _make_fake_frame(name="embed", url="https://embed.com")
+ page = _make_fake_page([main, iframe])
+
+ sp = FakeSkyvernBrowserPage(page)
+ result = await sp.frame_switch(index=1)
+
+ assert sp._working_frame is iframe
+ assert result["index"] == 1
+
+ @pytest.mark.asyncio
+ async def test_switch_no_params_raises(self) -> None:
+ page = _make_fake_page()
+ sp = FakeSkyvernBrowserPage(page)
+ with pytest.raises(ValueError, match="Exactly one"):
+ await sp.frame_switch()
+
+ @pytest.mark.asyncio
+ async def test_switch_multiple_params_raises(self) -> None:
+ page = _make_fake_page()
+ sp = FakeSkyvernBrowserPage(page)
+ with pytest.raises(ValueError, match="Exactly one"):
+ await sp.frame_switch(selector="#x", name="y")
+
+ @pytest.mark.asyncio
+ async def test_switch_selector_not_iframe_raises(self) -> None:
+ element_mock = MagicMock()
+ element_mock.content_frame = AsyncMock(return_value=None)
+
+ page = _make_fake_page()
+ page.query_selector = AsyncMock(return_value=element_mock)
+
+ sp = FakeSkyvernBrowserPage(page)
+ with pytest.raises(ValueError, match="did not resolve to an iframe"):
+ await sp.frame_switch(selector="#not-iframe")
+
+ @pytest.mark.asyncio
+ async def test_switch_name_not_found_raises(self) -> None:
+ page = _make_fake_page()
+ page.frame = MagicMock(return_value=None)
+
+ sp = FakeSkyvernBrowserPage(page)
+ with pytest.raises(ValueError, match="No frame found"):
+ await sp.frame_switch(name="nonexistent")
+
+ @pytest.mark.asyncio
+ async def test_switch_index_out_of_range_raises(self) -> None:
+ page = _make_fake_page([_make_fake_frame()])
+ sp = FakeSkyvernBrowserPage(page)
+ with pytest.raises(ValueError, match="out of range"):
+ await sp.frame_switch(index=5)
+
+
+# ---------------------------------------------------------------------------
+# frame_main tests
+# ---------------------------------------------------------------------------
+
+
+class TestFrameMain:
+ def test_clears_working_frame(self) -> None:
+ page = _make_fake_page()
+ frame = _make_fake_frame()
+ sp = FakeSkyvernBrowserPage(page, working_frame=frame)
+ assert sp._working_frame is frame
+ sp.frame_main()
+ assert sp._working_frame is None
+ assert sp._locator_scope is page
+
+
+# ---------------------------------------------------------------------------
+# frame_list tests
+# ---------------------------------------------------------------------------
+
+
+class TestFrameList:
+ @pytest.mark.asyncio
+ async def test_lists_all_frames(self) -> None:
+ main = _make_fake_frame(name="", url="https://example.com")
+ iframe1 = _make_fake_frame(name="ads", url="https://ads.com")
+ iframe2 = _make_fake_frame(name="payment", url="https://payment.example.com")
+ page = _make_fake_page([main, iframe1, iframe2])
+
+ sp = FakeSkyvernBrowserPage(page)
+ frames = await sp.frame_list()
+
+ assert len(frames) == 3
+ assert frames[0]["is_main"] is True
+ assert frames[1]["name"] == "ads"
+ assert frames[2]["name"] == "payment"
+
+
+# ---------------------------------------------------------------------------
+# MCP tool tests
+# ---------------------------------------------------------------------------
+
+
+class TestMCPFrameTools:
+ @pytest.mark.asyncio
+ async def test_frame_switch_invalid_params_preflight(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.cli.mcp_tools import browser as mcp_browser
+
+ get_page = AsyncMock(side_effect=AssertionError("get_page should not be called"))
+ monkeypatch.setattr(mcp_browser, "get_page", get_page)
+
+ result = await mcp_browser.skyvern_frame_switch()
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT
+ get_page.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_frame_switch_multiple_params_preflight(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.cli.mcp_tools import browser as mcp_browser
+
+ get_page = AsyncMock(side_effect=AssertionError("get_page should not be called"))
+ monkeypatch.setattr(mcp_browser, "get_page", get_page)
+
+ result = await mcp_browser.skyvern_frame_switch(selector="#x", name="y")
+ assert result["ok"] is False
+ get_page.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_frame_list_no_browser(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.cli.mcp_tools import browser as mcp_browser
+ from skyvern.cli.mcp_tools._session import BrowserNotAvailableError
+
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(side_effect=BrowserNotAvailableError()))
+
+ result = await mcp_browser.skyvern_frame_list()
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.NO_ACTIVE_BROWSER
+
+ @pytest.mark.asyncio
+ async def test_frame_main_no_browser(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.cli.mcp_tools import browser as mcp_browser
+ from skyvern.cli.mcp_tools._session import BrowserNotAvailableError
+
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(side_effect=BrowserNotAvailableError()))
+
+ result = await mcp_browser.skyvern_frame_main()
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.NO_ACTIVE_BROWSER
+
+ @pytest.mark.asyncio
+ async def test_navigate_clears_working_frame(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """skyvern_navigate must clear _working_frame to prevent stale frame references."""
+ from skyvern.cli.core.session_manager import SessionState
+ from skyvern.cli.mcp_tools import browser as mcp_browser
+
+ fake_page = MagicMock()
+ fake_page.goto = AsyncMock()
+ fake_page.url = "https://example.com/new"
+ fake_page.title = AsyncMock(return_value="New Page")
+ fake_ctx = MagicMock()
+ fake_ctx.mode = "local"
+
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(fake_page, fake_ctx)))
+
+ # Pre-set a working frame on the session state
+ state = SessionState()
+ state._working_frame = MagicMock() # simulates an active iframe
+ monkeypatch.setattr(mcp_browser, "get_current_session", lambda: state)
+
+ result = await mcp_browser.skyvern_navigate(url="https://example.com/new")
+ assert result["ok"] is True
+ assert state._working_frame is None
+
+ @pytest.mark.asyncio
+ async def test_navigate_clears_frame_on_failure(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Frame state must be cleared even when navigation fails (partial load may destroy iframes)."""
+ from skyvern.cli.core.session_manager import SessionState
+ from skyvern.cli.mcp_tools import browser as mcp_browser
+
+ fake_page = MagicMock()
+ fake_page.goto = AsyncMock(side_effect=TimeoutError("Navigation timeout"))
+ fake_ctx = MagicMock()
+ fake_ctx.mode = "local"
+
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(fake_page, fake_ctx)))
+
+ state = SessionState()
+ state._working_frame = MagicMock()
+ monkeypatch.setattr(mcp_browser, "get_current_session", lambda: state)
+
+ result = await mcp_browser.skyvern_navigate(url="https://example.com/timeout")
+ assert result["ok"] is False
+ assert state._working_frame is None # cleared despite failure
+
+ @pytest.mark.asyncio
+ async def test_tab_switch_clears_working_frame(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Switching tabs must clear _working_frame to prevent stale cross-tab frame references."""
+ import skyvern.cli.core.session_manager as sm_mod
+ from skyvern.cli.core.session_manager import SessionState
+ from skyvern.cli.mcp_tools import tabs as mcp_tabs
+
+ fake_page = MagicMock()
+ fake_page.is_closed = MagicMock(return_value=False)
+ fake_ctx = MagicMock()
+ fake_ctx.mode = "local"
+ monkeypatch.setattr(mcp_tabs, "get_page", AsyncMock(return_value=(fake_page, fake_ctx)))
+ monkeypatch.setattr(sm_mod, "is_stateless_http_mode", lambda: False)
+
+ target_page = MagicMock()
+ target_page.is_closed = MagicMock(return_value=False)
+ target_page.url = "https://other-tab.com"
+ target_page.title = AsyncMock(return_value="Other Tab")
+ target_page.bring_to_front = AsyncMock()
+
+ state = SessionState()
+ state.browser = MagicMock()
+ state.browser._browser_context.pages = [fake_page, target_page]
+ state._working_frame = MagicMock() # stale frame from previous tab
+ monkeypatch.setattr(mcp_tabs, "get_current_session", lambda: state)
+
+ result = await mcp_tabs.skyvern_tab_switch(index=1)
+ assert result["ok"] is True
+ assert state._working_frame is None
+
+ @pytest.mark.asyncio
+ async def test_tab_new_clears_working_frame(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Opening a new tab must clear _working_frame."""
+ from skyvern.cli.core.session_manager import SessionState
+ from skyvern.cli.mcp_tools import tabs as mcp_tabs
+
+ fake_page = MagicMock()
+ fake_ctx = MagicMock()
+ fake_ctx.mode = "local"
+ monkeypatch.setattr(mcp_tabs, "get_page", AsyncMock(return_value=(fake_page, fake_ctx)))
+
+ new_page = MagicMock()
+ new_page.url = "about:blank"
+ new_page.title = AsyncMock(return_value="")
+
+ state = SessionState()
+ state.browser = MagicMock()
+ state.browser._browser_context.new_page = AsyncMock(return_value=new_page)
+ state.browser._browser_context.pages = [fake_page, new_page]
+ state._working_frame = MagicMock() # stale frame
+ monkeypatch.setattr(mcp_tabs, "get_current_session", lambda: state)
+
+ result = await mcp_tabs.skyvern_tab_new()
+ assert result["ok"] is True
+ assert state._working_frame is None
+
+
+# ---------------------------------------------------------------------------
+# CLIState frame persistence tests
+# ---------------------------------------------------------------------------
+
+
+class TestCLIStateFrame:
+ def test_frame_fields_default_none(self) -> None:
+ from skyvern.cli.commands._state import CLIState
+
+ state = CLIState()
+ assert state.frame_selector is None
+ assert state.frame_name is None
+ assert state.frame_index is None
+
+ def test_frame_fields_roundtrip(self, tmp_path: Any) -> None:
+ import skyvern.cli.commands._state as state_mod
+ from skyvern.cli.commands._state import CLIState, load_state, save_state
+
+ # Point to temp dir to avoid polluting real state
+ original_dir = state_mod.STATE_DIR
+ original_file = state_mod.STATE_FILE
+ state_mod.STATE_DIR = tmp_path
+ state_mod.STATE_FILE = tmp_path / "state.json"
+ try:
+ state = CLIState(
+ session_id="pbs_123",
+ mode="cloud",
+ frame_selector="#payment-frame",
+ )
+ save_state(state)
+ loaded = load_state()
+ assert loaded is not None
+ assert loaded.frame_selector == "#payment-frame"
+ assert loaded.frame_name is None
+ assert loaded.frame_index is None
+ finally:
+ state_mod.STATE_DIR = original_dir
+ state_mod.STATE_FILE = original_file
+
+
+# ---------------------------------------------------------------------------
+# browser_ops tests
+# ---------------------------------------------------------------------------
+
+
+class TestBrowserOps:
+ @pytest.mark.asyncio
+ async def test_do_frame_switch_delegates(self) -> None:
+ page = MagicMock()
+ page.frame_switch = AsyncMock(return_value={"name": "pay", "url": "https://pay.com"})
+
+ result = await do_frame_switch(page, selector="#iframe")
+ page.frame_switch.assert_awaited_once_with(selector="#iframe", name=None, index=None)
+ assert result.name == "pay"
+
+ def test_do_frame_main_delegates(self) -> None:
+ page = MagicMock()
+ page.frame_main = MagicMock(return_value={"status": "switched_to_main_frame"})
+
+ do_frame_main(page)
+ page.frame_main.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_do_frame_list_delegates(self) -> None:
+ page = MagicMock()
+ page.frame_list = AsyncMock(
+ return_value=[
+ {"index": 0, "name": "", "url": "https://example.com", "is_main": True},
+ {"index": 1, "name": "embed", "url": "https://embed.com", "is_main": False},
+ ]
+ )
+
+ result = await do_frame_list(page)
+ assert len(result) == 2
+ assert result[0].is_main is True
+ assert result[1].name == "embed"