wavexis 2.3.0__tar.gz → 2.3.2__tar.gz

{wavexis-2.3.0 → wavexis-2.3.2}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to wavexis are documented in this file.
 
+## v2.3.2 — 2026-07-07
+
+### Added
+
+- iframe support: `iframe_click`, `iframe_fill`, `iframe_eval` in both CDP and BiDi backends
+- `wavexis iframe click/fill/eval` CLI command with `--iframe`, `--selector`, `--value`, `--expression` options
+- Auto-waiting inside iframes via `_wait_for_element_in_iframe` with polling and configurable timeout
+- `--no-wait` flag to skip auto-waiting for iframe interactions
+- Same-origin iframe support via `contentDocument` access
+
+## v2.3.1 — 2026-07-07
+
+### Added
+
+- `auto_wait: bool = True` parameter in `click`, `fill`, `hover` (both backends)
+- Pass `auto_wait=False` to skip element visibility polling for instant execution
+
 ## v2.3.0 — 2026-07-07
 
 ### Added

{wavexis-2.3.0 → wavexis-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavexis
-Version: 2.3.0
+Version: 2.3.2
 Summary: Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download
 Project-URL: Homepage, https://github.com/MathiasPaulenko/wavexis
 Project-URL: Repository, https://github.com/MathiasPaulenko/wavexis

{wavexis-2.3.0 → wavexis-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wavexis"
-version = "2.3.0"
+version = "2.3.2"
 description = "Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download"
 readme = "README.md"
 license = { text = "MIT" }

{wavexis-2.3.0 → wavexis-2.3.2}/tests/unit/test_auto_wait.py

@@ -68,6 +68,35 @@ class TestAutoWait:
         asyncio.run(backend.click("#btn"))
         assert call_order == ["wait", "scroll", "box"]
 
+    def test_cdp_click_auto_wait_false_skips_wait(self) -> None:
+        """Test that click with auto_wait=False skips _wait_for_element."""
+        from wavexis.backend.cdp import CDPBackend
+
+        backend = CDPBackend()
+        backend._session = MagicMock()
+        backend._session.input = MagicMock()
+        backend._session.input.dispatch_mouse_event = AsyncMock()
+
+        call_order: list[str] = []
+
+        async def _mock_wait(selector: str, timeout_ms: int = 30000) -> None:
+            call_order.append("wait")
+
+        async def _mock_scroll(selector: str) -> None:
+            call_order.append("scroll")
+
+        async def _mock_box(selector: str) -> tuple[float, float]:
+            call_order.append("box")
+            return 50.0, 25.0
+
+        backend._wait_for_element = _mock_wait  # type: ignore[assignment]
+        backend._scroll_into_view_if_needed = _mock_scroll  # type: ignore[assignment]
+        backend._get_box_center = _mock_box  # type: ignore[assignment]
+
+        asyncio.run(backend.click("#btn", auto_wait=False))
+        assert "wait" not in call_order
+        assert call_order == ["scroll", "box"]
+
     def test_bidi_wait_for_element_found(self) -> None:
         """Test BiDi _wait_for_element returns when element is visible."""
         from wavexis.backend.bidi import BiDiBackend

{wavexis-2.3.0 → wavexis-2.3.2}/tests/unit/test_backend_manager.py

@@ -206,7 +206,13 @@ class DummyBackend(AbstractBackend):
         """Set dark mode."""
         pass
 
-    async def click(self, selector: str, button: str = "left", click_count: int = 1) -> None:
+    async def click(
+        self,
+        selector: str,
+        button: str = "left",
+        click_count: int = 1,
+        auto_wait: bool = True,
+    ) -> None:
         """Click."""
         pass
 
@@ -214,7 +220,9 @@ class DummyBackend(AbstractBackend):
         """Type text."""
         pass
 
-    async def fill(self, selector: str, value: str) -> None:
+    async def fill(
+        self, selector: str, value: str, auto_wait: bool = True
+    ) -> None:
         """Fill."""
         pass
 
@@ -222,7 +230,7 @@ class DummyBackend(AbstractBackend):
         """Select option."""
         pass
 
-    async def hover(self, selector: str) -> None:
+    async def hover(self, selector: str, auto_wait: bool = True) -> None:
         """Hover."""
         pass
 
@@ -242,6 +250,24 @@ class DummyBackend(AbstractBackend):
         """Set files."""
         pass
 
+    async def iframe_eval(
+        self, iframe_selector: str, expression: str, await_promise: bool = False
+    ) -> object:
+        """Iframe eval."""
+        return None
+
+    async def iframe_click(
+        self, iframe_selector: str, selector: str, auto_wait: bool = True
+    ) -> None:
+        """Iframe click."""
+        pass
+
+    async def iframe_fill(
+        self, iframe_selector: str, selector: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """Iframe fill."""
+        pass
+
     async def throttle_network(self, params: object) -> None:
         """Throttle network."""
         pass

wavexis-2.3.2/tests/unit/test_iframe.py

@@ -0,0 +1,203 @@
+"""Unit tests for iframe support — iframe_eval, iframe_click, iframe_fill."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from wavexis.exceptions import ElementNotFoundError
+
+
+def _make_cdp_backend() -> Any:
+    """Create a CDPBackend with mocked session."""
+    from wavexis.backend.cdp import CDPBackend
+
+    backend = CDPBackend()
+    backend._session = MagicMock()
+    backend._session.runtime = MagicMock()
+    backend._session.runtime.evaluate = AsyncMock(
+        return_value={"result": {"value": True}}
+    )
+    return backend
+
+
+def _make_bidi_backend() -> Any:
+    """Create a BiDiBackend with mocked client."""
+    from wavexis.backend.bidi import BiDiBackend
+
+    backend = BiDiBackend()
+    backend._client = MagicMock()
+    backend._context = MagicMock()
+    backend._client.script = MagicMock()
+    result = MagicMock()
+    result.value = True
+    backend._client.script.evaluate = AsyncMock(return_value=result)
+    return backend
+
+
+@pytest.mark.unit
+class TestIframeEval:
+    """Tests for iframe_eval in both backends."""
+
+    def test_cdp_iframe_eval_returns_value(self) -> None:
+        """Test CDP iframe_eval returns the evaluated value."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": 42}}
+        )
+        result = asyncio.run(
+            backend.iframe_eval("#myframe", "1 + 1", await_promise=False)
+        )
+        assert result == 42
+
+    def test_cdp_iframe_eval_null_iframe_not_found(self) -> None:
+        """Test CDP iframe_eval returns None when iframe is not found."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": None}}
+        )
+        result = asyncio.run(
+            backend.iframe_eval("#missing", "document.title")
+        )
+        assert result is None
+
+    def test_bidi_iframe_eval_returns_value(self) -> None:
+        """Test BiDi iframe_eval returns the evaluated value."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = "hello"
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        result = asyncio.run(
+            backend.iframe_eval("#myframe", "document.title")
+        )
+        assert result == "hello"
+
+
+@pytest.mark.unit
+class TestIframeClick:
+    """Tests for iframe_click in both backends."""
+
+    def test_cdp_iframe_click_success(self) -> None:
+        """Test CDP iframe_click dispatches click inside iframe."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": True}}
+        )
+        asyncio.run(backend.iframe_click("#myframe", "#btn", auto_wait=False))
+        backend._session.runtime.evaluate.assert_called()
+
+    def test_cdp_iframe_click_element_not_found(self) -> None:
+        """Test CDP iframe_click raises ElementNotFoundError when element missing."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": False}}
+        )
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.iframe_click("#myframe", "#missing", auto_wait=False))
+
+    def test_bidi_iframe_click_success(self) -> None:
+        """Test BiDi iframe_click dispatches click inside iframe."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = True
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        asyncio.run(backend.iframe_click("#myframe", "#btn", auto_wait=False))
+        backend._client.script.evaluate.assert_called()
+
+    def test_bidi_iframe_click_element_not_found(self) -> None:
+        """Test BiDi iframe_click raises ElementNotFoundError when element missing."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = False
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.iframe_click("#myframe", "#missing", auto_wait=False))
+
+
+@pytest.mark.unit
+class TestIframeFill:
+    """Tests for iframe_fill in both backends."""
+
+    def test_cdp_iframe_fill_success(self) -> None:
+        """Test CDP iframe_fill sets value inside iframe."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": True}}
+        )
+        asyncio.run(
+            backend.iframe_fill("#myframe", "#input", "test value", auto_wait=False)
+        )
+        backend._session.runtime.evaluate.assert_called()
+
+    def test_cdp_iframe_fill_element_not_found(self) -> None:
+        """Test CDP iframe_fill raises ElementNotFoundError when element missing."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": False}}
+        )
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(
+                backend.iframe_fill("#myframe", "#missing", "val", auto_wait=False)
+            )
+
+    def test_bidi_iframe_fill_success(self) -> None:
+        """Test BiDi iframe_fill sets value inside iframe."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = True
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        asyncio.run(
+            backend.iframe_fill("#myframe", "#input", "test value", auto_wait=False)
+        )
+        backend._client.script.evaluate.assert_called()
+
+    def test_bidi_iframe_fill_element_not_found(self) -> None:
+        """Test BiDi iframe_fill raises ElementNotFoundError when element missing."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = False
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(
+                backend.iframe_fill("#myframe", "#missing", "val", auto_wait=False)
+            )
+
+
+@pytest.mark.unit
+class TestIframeAutoWait:
+    """Tests for auto_wait in iframe operations."""
+
+    def test_cdp_iframe_click_auto_wait_false_skips_wait(self) -> None:
+        """Test that iframe_click with auto_wait=False skips _wait_for_element_in_iframe."""
+        backend = _make_cdp_backend()
+        call_order: list[str] = []
+
+        async def _mock_wait(iframe_sel: str, sel: str, timeout_ms: int = 30000) -> None:
+            call_order.append("wait")
+
+        backend._wait_for_element_in_iframe = _mock_wait  # type: ignore[assignment]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": True}}
+        )
+
+        asyncio.run(backend.iframe_click("#myframe", "#btn", auto_wait=False))
+        assert "wait" not in call_order
+
+    def test_cdp_iframe_click_auto_wait_true_calls_wait(self) -> None:
+        """Test that iframe_click with auto_wait=True calls _wait_for_element_in_iframe."""
+        backend = _make_cdp_backend()
+        call_order: list[str] = []
+
+        async def _mock_wait(iframe_sel: str, sel: str, timeout_ms: int = 30000) -> None:
+            call_order.append("wait")
+
+        backend._wait_for_element_in_iframe = _mock_wait  # type: ignore[assignment]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": True}}
+        )
+
+        asyncio.run(backend.iframe_click("#myframe", "#btn", auto_wait=True))
+        assert "wait" in call_order

{wavexis-2.3.0 → wavexis-2.3.2}/tests/unit/test_manager.py

@@ -102,15 +102,15 @@ class FakeBackend(AbstractBackend):
         """Set timezone."""
     async def set_dark_mode(self, enabled):
         """Set dark mode."""
-    async def click(self, selector, button="left", click_count=1):
+    async def click(self, selector, button="left", click_count=1, auto_wait=True):
         """Click."""
     async def type_text(self, selector, text, delay=0):
         """Type text."""
-    async def fill(self, selector, value):
+    async def fill(self, selector, value, auto_wait=True):
         """Fill."""
     async def select_option(self, selector, value):
         """Select option."""
-    async def hover(self, selector):
+    async def hover(self, selector, auto_wait=True):
         """Hover."""
     async def key_press(self, key):
         """Key press."""
@@ -262,6 +262,13 @@ class FakeBackend(AbstractBackend):
         """Bluetooth stop."""
     async def set_files(self, selector, files):
         """Set files."""
+    async def iframe_eval(self, iframe_selector, expression, await_promise=False):
+        """Iframe eval."""
+        return None
+    async def iframe_click(self, iframe_selector, selector, auto_wait=True):
+        """Iframe click."""
+    async def iframe_fill(self, iframe_selector, selector, value, auto_wait=True):
+        """Iframe fill."""
 
 
 class TestBackendManager:

{wavexis-2.3.0 → wavexis-2.3.2}/wavexis/__init__.py

@@ -1,3 +1,3 @@
 """wavexis — CLI de automatización de navegador."""
 
-__version__ = "2.3.0"
+__version__ = "2.3.2"

{wavexis-2.3.0 → wavexis-2.3.2}/wavexis/backend/base.py

@@ -237,7 +237,11 @@ class AbstractBackend(ABC):
 
     @abstractmethod
     async def click(
-        self, selector: str, button: str = "left", click_count: int = 1
+        self,
+        selector: str,
+        button: str = "left",
+        click_count: int = 1,
+        auto_wait: bool = True,
     ) -> None:
         """Click an element matching a CSS selector."""
 
@@ -246,7 +250,9 @@ class AbstractBackend(ABC):
         """Type text into an element, optionally with delay between keystrokes."""
 
     @abstractmethod
-    async def fill(self, selector: str, value: str) -> None:
+    async def fill(
+        self, selector: str, value: str, auto_wait: bool = True
+    ) -> None:
         """Fill an input element with a value (replaces existing content)."""
 
     @abstractmethod
@@ -254,7 +260,7 @@ class AbstractBackend(ABC):
         """Select an option in a <select> element by value."""
 
     @abstractmethod
-    async def hover(self, selector: str) -> None:
+    async def hover(self, selector: str, auto_wait: bool = True) -> None:
         """Hover over an element matching a CSS selector."""
 
     @abstractmethod
@@ -278,6 +284,45 @@ class AbstractBackend(ABC):
             files: List of absolute file paths to upload.
         """
 
+    # ── iframe ─────────────────────────────────────────────
+
+    @abstractmethod
+    async def iframe_eval(
+        self, iframe_selector: str, expression: str, await_promise: bool = False
+    ) -> Any:
+        """Evaluate a JavaScript expression inside an iframe.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            expression: JavaScript expression to evaluate in the iframe context.
+            await_promise: Whether to await a returned Promise.
+        """
+
+    @abstractmethod
+    async def iframe_click(
+        self, iframe_selector: str, selector: str, auto_wait: bool = True
+    ) -> None:
+        """Click an element inside an iframe.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            selector: CSS selector inside the iframe for the target element.
+            auto_wait: If True, wait for element to be visible before clicking.
+        """
+
+    @abstractmethod
+    async def iframe_fill(
+        self, iframe_selector: str, selector: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """Fill an input element inside an iframe.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            selector: CSS selector inside the iframe for the target element.
+            value: Value to set in the input field.
+            auto_wait: If True, wait for element to be visible before filling.
+        """
+
     # ── Network advanced ───────────────────────────────────
 
     @abstractmethod

{wavexis-2.3.0 → wavexis-2.3.2}/wavexis/backend/bidi.py

@@ -26,7 +26,11 @@ from wavexis.config import (
     ThrottleParams,
     WaitStrategy,
 )
-from wavexis.exceptions import SessionNotInitializedError, WaitTimeoutError
+from wavexis.exceptions import (
+    ElementNotFoundError,
+    SessionNotInitializedError,
+    WaitTimeoutError,
+)
 
 try:
     from bidiwave import BiDiClient
@@ -853,11 +857,23 @@ class BiDiBackend(AbstractBackend):
         await client.script.evaluate(self._context, js)
 
     async def click(
-        self, selector: str, button: str = "left", click_count: int = 1
+        self,
+        selector: str,
+        button: str = "left",
+        click_count: int = 1,
+        auto_wait: bool = True,
     ) -> None:
-        """Click an element via BiDi script.evaluate."""
+        """Click an element via BiDi script.evaluate.
+
+        Args:
+            selector: CSS selector for the target element.
+            button: Mouse button (unused in BiDi, for API compatibility).
+            click_count: Number of clicks to dispatch.
+            auto_wait: If True, wait for element to be visible before clicking.
+        """
         client = self._require_client()
-        await self._wait_for_element(selector)
+        if auto_wait:
+            await self._wait_for_element(selector)
         await self._scroll_into_view_if_needed(selector)
         escaped = selector.replace("'", "\\'")
         js = (
@@ -887,10 +903,19 @@ class BiDiBackend(AbstractBackend):
             if delay > 0:
                 await _asyncio.sleep(delay / 1000)
 
-    async def fill(self, selector: str, value: str) -> None:
-        """Fill an input element with a value via BiDi."""
+    async def fill(
+        self, selector: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """Fill an input element with a value via BiDi.
+
+        Args:
+            selector: CSS selector for the target element.
+            value: Value to set in the input field.
+            auto_wait: If True, wait for element to be visible before filling.
+        """
         client = self._require_client()
-        await self._wait_for_element(selector)
+        if auto_wait:
+            await self._wait_for_element(selector)
         await self._scroll_into_view_if_needed(selector)
         escaped = selector.replace("'", "\\'")
         escaped_val = value.replace("\\", "\\\\").replace("'", "\\'")
@@ -906,10 +931,16 @@ class BiDiBackend(AbstractBackend):
         js = f"document.querySelector('{escaped}').value = '{escaped_val}'"
         await self._client.script.evaluate(self._context, js)
 
-    async def hover(self, selector: str) -> None:
-        """Hover over an element via BiDi script.evaluate."""
+    async def hover(self, selector: str, auto_wait: bool = True) -> None:
+        """Hover over an element via BiDi script.evaluate.
+
+        Args:
+            selector: CSS selector for the target element.
+            auto_wait: If True, wait for element to be visible before hovering.
+        """
         client = self._require_client()
-        await self._wait_for_element(selector)
+        if auto_wait:
+            await self._wait_for_element(selector)
         await self._scroll_into_view_if_needed(selector)
         escaped = selector.replace("'", "\\'")
         js = (
@@ -970,7 +1001,132 @@ class BiDiBackend(AbstractBackend):
         )
         await self._client.script.evaluate(self._context, js)
 
-    # ── Network advanced ───────────────────────────────────
+    # ── iframe ─────────────────────────────────────────────
+
+    async def iframe_eval(
+        self, iframe_selector: str, expression: str, await_promise: bool = False
+    ) -> Any:
+        """Evaluate a JavaScript expression inside an iframe.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            expression: JavaScript expression to evaluate in the iframe context.
+            await_promise: Whether to await a returned Promise.
+
+        Returns:
+            The evaluation result value.
+        """
+        client = self._require_client()
+        escaped_iframe = iframe_selector.replace("'", "\\'")
+        escaped_expr = expression.replace("\\", "\\\\").replace("'", "\\'")
+        js = (
+            f"(function(){{var f=document.querySelector('{escaped_iframe}');"
+            f"if(!f||!f.contentDocument)return null;"
+            f"return (function(){{{escaped_expr}}}).call(f.contentDocument);}})()"
+        )
+        result = await client.script.evaluate(
+            self._context, js, await_promise=await_promise
+        )
+        if hasattr(result, "value"):
+            return result.value
+        return result
+
+    async def _wait_for_element_in_iframe(
+        self, iframe_selector: str, selector: str, timeout_ms: int = 30000
+    ) -> None:
+        """Wait for an element inside an iframe to exist and be visible.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            selector: CSS selector inside the iframe.
+            timeout_ms: Maximum wait time in milliseconds.
+
+        Raises:
+            WaitTimeoutError: If the element is not found within the timeout.
+        """
+        import asyncio as _asyncio
+        import time as _time
+
+        client = self._require_client()
+        escaped_iframe = iframe_selector.replace("'", "\\'")
+        escaped_sel = selector.replace("'", "\\'")
+        js = (
+            f"(function(){{var f=document.querySelector('{escaped_iframe}');"
+            f"if(!f||!f.contentDocument)return false;"
+            f"var el=f.contentDocument.querySelector('{escaped_sel}');"
+            f"if(!el)return false;"
+            f"var rect=el.getBoundingClientRect();"
+            f"return rect.width>0&&rect.height>0;}})()"
+        )
+        deadline = _time.monotonic() + timeout_ms / 1000
+        while _time.monotonic() < deadline:
+            result = await client.script.evaluate(self._context, js)
+            value = getattr(result, "value", None)
+            if value is True or value == "true":
+                return
+            await _asyncio.sleep(0.1)
+        raise WaitTimeoutError("selector", timeout_ms)
+
+    async def iframe_click(
+        self, iframe_selector: str, selector: str, auto_wait: bool = True
+    ) -> None:
+        """Click an element inside an iframe.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            selector: CSS selector inside the iframe for the target element.
+            auto_wait: If True, wait for element to be visible before clicking.
+        """
+        client = self._require_client()
+        if auto_wait:
+            await self._wait_for_element_in_iframe(iframe_selector, selector)
+        escaped_iframe = iframe_selector.replace("'", "\\'")
+        escaped_sel = selector.replace("'", "\\'")
+        js = (
+            f"(function(){{var f=document.querySelector('{escaped_iframe}');"
+            f"if(!f||!f.contentDocument)return false;"
+            f"var el=f.contentDocument.querySelector('{escaped_sel}');"
+            f"if(!el)return false;"
+            f"el.scrollIntoView({{block:'center',behavior:'instant'}});"
+            f"el.dispatchEvent(new MouseEvent('click',{{bubbles:true}}));"
+            f"return true;}})()"
+        )
+        result = await client.script.evaluate(self._context, js)
+        value = getattr(result, "value", None)
+        if not value:
+            raise ElementNotFoundError(selector)
+
+    async def iframe_fill(
+        self, iframe_selector: str, selector: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """Fill an input element inside an iframe.
+
+        Args:
+            iframe_selector: CSS selector for the <iframe> element.
+            selector: CSS selector inside the iframe for the target element.
+            value: Value to set in the input field.
+            auto_wait: If True, wait for element to be visible before filling.
+        """
+        client = self._require_client()
+        if auto_wait:
+            await self._wait_for_element_in_iframe(iframe_selector, selector)
+        escaped_iframe = iframe_selector.replace("'", "\\'")
+        escaped_sel = selector.replace("'", "\\'")
+        escaped_val = value.replace("\\", "\\\\").replace("'", "\\'")
+        js = (
+            f"(function(){{var f=document.querySelector('{escaped_iframe}');"
+            f"if(!f||!f.contentDocument)return false;"
+            f"var el=f.contentDocument.querySelector('{escaped_sel}');"
+            f"if(!el)return false;"
+            f"el.focus();el.value='{escaped_val}';"
+            f"el.dispatchEvent(new Event('input',{{bubbles:true}}));"
+            f"el.dispatchEvent(new Event('change',{{bubbles:true}}));"
+            f"return true;}})()"
+        )
+        result = await client.script.evaluate(self._context, js)
+        result_value = getattr(result, "value", None)
+        if not result_value:
+            raise ElementNotFoundError(selector)
 
     async def block_requests(self, patterns: list[str]) -> None:
         """Block requests matching URL patterns (partial BiDi support)."""