playwright-browserstack 1.62.0__py3-none-win_amd64.whl

playwright/_impl/_android.py

@@ -0,0 +1,704 @@
+# Copyright (c) 2025 BrowserStack. All rights reserved.
+#
+# This software is the confidential and proprietary information of BrowserStack.
+# You shall not disclose such Confidential Information and shall use it only in
+# accordance with the terms of the license agreement you entered into with BrowserStack.
+
+import asyncio
+import base64
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union, cast
+
+from pyee import EventEmitter
+
+from playwright._impl._browser_context import BrowserContext
+from playwright._impl._connection import ChannelOwner, Connection, from_channel
+from playwright._impl._errors import Error, TargetClosedError, is_target_closed_error
+from playwright._impl._helper import (
+    PLAYWRIGHT_MAX_DEADLINE,
+    TimeoutSettings,
+    async_writefile,
+    make_dirs_for_file,
+)
+from playwright._impl._json_pipe import JsonPipeTransport
+from playwright._impl._waiter import Waiter, throw_on_timeout
+
+if TYPE_CHECKING:
+    from playwright._impl._playwright import Playwright
+
+
+class Android(ChannelOwner):
+    """Root Android object — entry point for all Android device interactions."""
+
+    _playwright: "Playwright"
+
+    def __init__(
+        self, parent: ChannelOwner, type: str, guid: str, initializer: Dict
+    ) -> None:
+        super().__init__(parent, type, guid, initializer)
+        self._timeout_settings = TimeoutSettings(None)
+
+    def set_default_timeout(self, timeout: float) -> None:
+        self._timeout_settings.set_default_timeout(timeout)
+
+    async def devices(self, port: int = None) -> List["AndroidDevice"]:
+        params: Dict = {}
+        if port is not None:
+            params["port"] = port
+        result = await self._channel.send_return_as_dict("devices", None, params)
+        return [from_channel(d) for d in result["devices"]]
+
+    async def connect(
+        self,
+        wsEndpoint: str,
+        headers: Dict[str, str] = None,
+        slowMo: float = None,
+        timeout: float = None,
+    ) -> "AndroidDevice":
+        # Mirror Node.js: x-playwright-browser: 'android' header, pipe via LocalUtils.
+        if slowMo is None:
+            slowMo = 0
+        if timeout is None:
+            timeout = 0
+        # Marker FIRST, matching client/android.ts:
+        #   { 'x-playwright-browser': 'android', ...options.headers }
+        # Note this is the opposite precedence from browserType.connect, which
+        # spreads the caller's headers first. That inconsistency is upstream's;
+        # we mirror the Android path deliberately.
+        req_headers = {"x-playwright-browser": "android", **(headers or {})}
+        local_utils = self._connection.local_utils
+        # Wire params must match the bundled driver's LocalUtilsConnectParams
+        # scheme. Upstream renamed `wsEndpoint` -> `endpoint` after 1.56, so
+        # this key is version-sensitive; see
+        # tests/test_android.py::test_connect_wire_params_match_bundled_driver.
+        pipe_channel = (
+            await local_utils._channel.send_return_as_dict(
+                "connect",
+                lambda t: t or 0,
+                {
+                    "endpoint": wsEndpoint,
+                    "headers": req_headers,
+                    "slowMo": slowMo,
+                    "timeout": timeout,
+                },
+            )
+        )["pipe"]
+        transport = JsonPipeTransport(self._connection._loop, pipe_channel)
+
+        connection = Connection(
+            self._connection._dispatcher_fiber,
+            self._connection._object_factory,
+            transport,
+            self._connection._loop,
+            local_utils=self._connection.local_utils,
+        )
+        connection.mark_as_remote()
+
+        device: Optional["AndroidDevice"] = None
+
+        # Registered before create_task(connection.run()) — as
+        # _browser_type.connect does — so a pipe that closes *during* the
+        # handshake still runs cleanup(). Registering after the handshake
+        # leaked a connection on every failed connect: _init_task stayed
+        # pending forever and _closed_error was never set.
+        def handle_transport_close(reason: Optional[str]) -> None:
+            if device:
+                device._notify_remote_closed()
+            connection.cleanup(reason)
+
+        transport.once("close", handle_transport_close)
+
+        connection._is_sync = self._connection._is_sync
+        connection._loop.create_task(connection.run())
+
+        playwright_future = connection.playwright_future
+        # Truthiness, not "is not None": 0 means no timeout, and
+        # throw_on_timeout has no zero-guard (unlike Waiter.reject_on_timeout),
+        # so throw_on_timeout(0) would fire on the next loop tick.
+        timeout_future = throw_on_timeout(
+            timeout if timeout else PLAYWRIGHT_MAX_DEADLINE,
+            Error("Android.connect: timed out"),
+        )
+        done, _ = await asyncio.wait(
+            {transport.on_error_future, playwright_future, timeout_future},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        if not playwright_future.done():
+            playwright_future.cancel()
+        if not timeout_future.done():
+            timeout_future.cancel()
+
+        playwright: "Playwright" = next(iter(done)).result()
+        # NB: no playwright._set_selectors(...) here. browserType.connect does
+        # that, but client/android.ts deliberately does not, so the child
+        # connection keeps its own Selectors — see the review notes on #16.
+        self._connection._child_ws_connections.append(connection)
+
+        pre_connected = playwright._initializer.get("preConnectedAndroidDevice")
+        if not pre_connected:
+            connection._transport.dispose()
+            raise Error("Malformed endpoint. Did you use Android.launchServer method?")
+        device = cast("AndroidDevice", from_channel(pre_connected))
+        device._should_close_connection_on_close = True
+
+        # android.ts closes the pipe with
+        #   device.on(Events.AndroidDevice.Close, () => connection.close())
+        # because in JS Connection.close() also closes the transport. Python's
+        # Connection.cleanup() does not, so the equivalent has to hang off the
+        # connection's close event: AndroidDevice.close() calls
+        # self._connection.cleanup(), and without this bridge the pipe is never
+        # closed — BrowserStack then ends the session ABRUPT_CLOSE instead of
+        # CLIENT_STOPPED_SESSION.
+        def _on_connection_close() -> None:
+            try:
+                transport.request_stop()
+            except Exception:
+                pass  # pipe already gone (e.g. server-initiated close)
+
+        connection.on("close", lambda *_: _on_connection_close())
+
+        return device
+
+
+class AndroidDevice(ChannelOwner):
+    """Represents a connected Android device."""
+
+    class Events:
+        Close = "close"
+        WebView = "webview"
+
+    def __init__(
+        self, parent: ChannelOwner, type: str, guid: str, initializer: Dict
+    ) -> None:
+        super().__init__(parent, type, guid, initializer)
+        self._android: Android = parent  # type: ignore
+        self._timeout_settings = TimeoutSettings(
+            getattr(parent, "_timeout_settings", None)
+        )
+        self._webviews: Dict[str, "AndroidWebView"] = {}
+        self._should_close_connection_on_close = False
+        self._contexts: List[BrowserContext] = []
+        self._is_closed: bool = False
+
+        self.input = AndroidInput(self)
+
+        self._channel.on(
+            "webViewAdded",
+            lambda params: self._on_web_view_added(params["webView"]),
+        )
+        self._channel.on(
+            "webViewRemoved",
+            lambda params: self._on_web_view_removed(params["socketName"]),
+        )
+        self._channel.on("close", lambda _: self._did_close())
+
+    def _on_web_view_added(self, web_view_data: Dict) -> None:
+        view = AndroidWebView(self, web_view_data)
+        self._webviews[web_view_data["socketName"]] = view
+        self.emit(AndroidDevice.Events.WebView, view)
+
+    def _on_web_view_removed(self, socket_name: str) -> None:
+        view = self._webviews.pop(socket_name, None)
+        if view:
+            view.emit(AndroidWebView.Events.Close)
+
+    def _did_close(self) -> None:
+        if self._is_closed:
+            return
+        self._is_closed = True
+        self.emit(AndroidDevice.Events.Close, self)
+
+    def _notify_remote_closed(self) -> None:
+        for context in list(self._contexts):
+            for page in list(context.pages):
+                page._on_close()
+            context._on_close()
+        self._did_close()
+
+    def set_default_timeout(self, timeout: float) -> None:
+        self._timeout_settings.set_default_timeout(timeout)
+
+    def _timeout(self, timeout: Optional[float]) -> float:
+        """Timeout calculator for channel calls, mirroring Frame._timeout.
+
+        Channel.send() pops "timeout" out of params and converts it into the
+        protocol message's own timeout field *via this calculator*. Passing None
+        there discards the value and sends timeout=0, which the driver treats as
+        "no timeout" (Node's kNoTimeout is literally {timeout: 0}). Every
+        timeout-bearing call must therefore pass this.
+        """
+        return self._timeout_settings.timeout(timeout)
+
+    @property
+    def serial(self) -> str:
+        return self._initializer["serial"]
+
+    @property
+    def model(self) -> str:
+        return self._initializer["model"]
+
+    def web_views(self) -> List["AndroidWebView"]:
+        return list(self._webviews.values())
+
+    async def web_view(
+        self,
+        selector: Dict,
+        timeout: float = None,
+    ) -> "AndroidWebView":
+        def _match(v: "AndroidWebView") -> bool:
+            if "pkg" in selector:
+                return v.pkg == selector["pkg"]
+            if "socketName" in selector:
+                return v._socket_name() == selector["socketName"]
+            return False
+
+        existing = next((v for v in self._webviews.values() if _match(v)), None)
+        if existing:
+            return existing
+        return await self.wait_for_event(
+            AndroidDevice.Events.WebView,
+            predicate=_match,
+            timeout=timeout,
+        )
+
+    async def wait(
+        self,
+        selector: Dict,
+        state: str = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if state is not None:
+            params["state"] = state
+        await self._channel.send("wait", self._timeout, params)
+
+    async def fill(self, selector: Dict, text: str, timeout: float = None) -> None:
+        await self._channel.send(
+            "fill",
+            self._timeout,
+            {
+                "androidSelector": _to_selector_channel(selector),
+                "text": text,
+                "timeout": self._timeout_settings.timeout(timeout),
+            },
+        )
+
+    async def tap(
+        self, selector: Dict, duration: float = None, timeout: float = None
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if duration is not None:
+            params["duration"] = duration
+        await self._channel.send("tap", self._timeout, params)
+
+    async def long_tap(self, selector: Dict, timeout: float = None) -> None:
+        await self._channel.send(
+            "longTap",
+            self._timeout,
+            {
+                "androidSelector": _to_selector_channel(selector),
+                "timeout": self._timeout_settings.timeout(timeout),
+            },
+        )
+
+    async def drag(
+        self,
+        selector: Dict,
+        dest: Dict,
+        speed: float = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "dest": dest,
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if speed is not None:
+            params["speed"] = speed
+        await self._channel.send("drag", self._timeout, params)
+
+    async def fling(
+        self,
+        selector: Dict,
+        direction: str,
+        speed: float = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "direction": direction,
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if speed is not None:
+            params["speed"] = speed
+        await self._channel.send("fling", self._timeout, params)
+
+    async def pinch_close(
+        self,
+        selector: Dict,
+        percent: float,
+        speed: float = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "percent": percent,
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if speed is not None:
+            params["speed"] = speed
+        await self._channel.send("pinchClose", self._timeout, params)
+
+    async def pinch_open(
+        self,
+        selector: Dict,
+        percent: float,
+        speed: float = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "percent": percent,
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if speed is not None:
+            params["speed"] = speed
+        await self._channel.send("pinchOpen", self._timeout, params)
+
+    async def scroll(
+        self,
+        selector: Dict,
+        direction: str,
+        percent: float,
+        speed: float = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "direction": direction,
+            "percent": percent,
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if speed is not None:
+            params["speed"] = speed
+        await self._channel.send("scroll", self._timeout, params)
+
+    async def swipe(
+        self,
+        selector: Dict,
+        direction: str,
+        percent: float,
+        speed: float = None,
+        timeout: float = None,
+    ) -> None:
+        params: Dict = {
+            "androidSelector": _to_selector_channel(selector),
+            "direction": direction,
+            "percent": percent,
+            "timeout": self._timeout_settings.timeout(timeout),
+        }
+        if speed is not None:
+            params["speed"] = speed
+        await self._channel.send("swipe", self._timeout, params)
+
+    async def press(self, selector: Dict, key: str, timeout: float = None) -> None:
+        await self.tap(selector, timeout=timeout)
+        await self.input.press(key)
+
+    async def info(self, selector: Dict) -> Dict:
+        result = await self._channel.send_return_as_dict(
+            "info", None, {"androidSelector": _to_selector_channel(selector)}
+        )
+        return result["info"]
+
+    async def screenshot(self, path: Union[str, Path] = None) -> bytes:
+        result = await self._channel.send_return_as_dict("screenshot", None, {})
+        data: bytes = base64.b64decode(result["binary"])
+        if path:
+            make_dirs_for_file(path)
+            await async_writefile(path, data)
+        return data
+
+    async def shell(self, command: str) -> bytes:
+        result = await self._channel.send_return_as_dict(
+            "shell", None, {"command": command}
+        )
+        return base64.b64decode(result["result"])
+
+    async def open(self, command: str) -> "AndroidSocket":
+        result = await self._channel.send_return_as_dict(
+            "open", None, {"command": command}
+        )
+        return from_channel(result["socket"])
+
+    async def install_apk(
+        self, file: Union[str, Path, bytes], args: List[str] = None
+    ) -> None:
+        params: Dict = {"file": base64.b64encode(await _load_file(file)).decode()}
+        if args is not None:
+            params["args"] = args
+        await self._channel.send("installApk", None, params)
+
+    async def push(
+        self,
+        file: Union[str, Path, bytes],
+        path: str,
+        mode: int = None,
+    ) -> None:
+        params: Dict = {
+            "file": base64.b64encode(await _load_file(file)).decode(),
+            "path": path,
+        }
+        if mode is not None:
+            params["mode"] = mode
+        await self._channel.send("push", None, params)
+
+    async def launch_browser(self, pkg: str = None, **kwargs: Any) -> BrowserContext:
+        params: Dict = {k: v for k, v in kwargs.items() if v is not None}
+        if pkg is not None:
+            params["pkg"] = pkg
+        await self._android._playwright.chromium._prepare_browser_context_params(params)
+        result = await self._channel.send_return_as_dict("launchBrowser", None, params)
+        context = from_channel(result["context"])
+        assert isinstance(context, BrowserContext)
+        self._contexts.append(context)
+
+        # android.ts:
+        #   selectors._contextsForSelectors.add(context)
+        #   context.once(Close, () => selectors._contextsForSelectors.delete(context))
+        # BrowserContext._on_close only deregisters contexts that have a
+        # ._browser, which Android contexts do not, so we must remove it here
+        # or the set leaks a closed context.
+        selectors = self._android._playwright.selectors
+        selectors._contexts_for_selectors.add(context)
+
+        def _on_context_close(_: Any = None) -> None:
+            if context in self._contexts:
+                self._contexts.remove(context)
+            selectors._contexts_for_selectors.discard(context)
+
+        context.on(BrowserContext.Events.Close, _on_context_close)
+
+        # android.ts: await context._initializeHarFromOptions(options.recordHar)
+        # HAR capture is started client-side via tracing; without this the
+        # record_har option is silently a no-op.
+        record_har = kwargs.get("recordHar") or kwargs.get("record_har")
+        if record_har:
+            await context._initialize_har_from_options(
+                record_har_path=record_har.get("path"),
+                record_har_content=record_har.get("content"),
+                record_har_omit_content=record_har.get("omitContent"),
+                record_har_url_filter=record_har.get("urlFilter"),
+                record_har_mode=record_har.get("mode"),
+            )
+        return context
+
+    async def wait_for_event(
+        self,
+        event: str,
+        predicate: Callable = None,
+        timeout: float = None,
+    ) -> Any:
+        t = self._timeout_settings.timeout(timeout)
+        waiter = Waiter(self, event)
+        waiter.reject_on_timeout(
+            t, f'Timeout {t}ms exceeded while waiting for event "{event}"'
+        )
+        if event != AndroidDevice.Events.Close:
+            waiter.reject_on_event(
+                self,
+                AndroidDevice.Events.Close,
+                lambda: TargetClosedError(),
+            )
+        waiter.wait_for_event(self, event, predicate)
+        return await waiter.result()
+
+    async def close(self) -> None:
+        try:
+            if self._should_close_connection_on_close:
+                # Aligned with Node.js: this._connection.close().
+                # Cleanup rejects pending callbacks, emits 'close', and the
+                # _on_connection_close listener then tears down pages/contexts
+                # and calls transport.request_stop() to close the pipe to BrowserStack.
+                self._connection.cleanup()
+            else:
+                await self._channel.send("close", None, {})
+        except Exception as e:
+            if is_target_closed_error(e):
+                return
+            raise
+
+
+class AndroidSocket(ChannelOwner):
+    """Represents an open socket connection to an Android process."""
+
+    class Events:
+        Close = "close"
+        Data = "data"
+
+    def __init__(
+        self, parent: ChannelOwner, type: str, guid: str, initializer: Dict
+    ) -> None:
+        super().__init__(parent, type, guid, initializer)
+        # `data` is protocol `binary`, i.e. base64 text on the wire. JS gets
+        # bytes because its transport converts Binary -> Buffer before the
+        # handler runs; Python has no such step, so decode here (same as
+        # _network.py does for WebSocket frames).
+        self._channel.on(
+            "data",
+            lambda params: self.emit(
+                AndroidSocket.Events.Data, base64.b64decode(params["data"])
+            ),
+        )
+        self._channel.on("close", lambda _: self.emit(AndroidSocket.Events.Close))
+
+    async def write(self, data: bytes) -> None:
+        await self._channel.send(
+            "write", None, {"data": base64.b64encode(data).decode()}
+        )
+
+    async def close(self) -> None:
+        try:
+            await self._channel.send("close", None, {})
+        except Exception as e:
+            if is_target_closed_error(e):
+                return
+            raise
+
+
+class AndroidWebView(EventEmitter):
+    """Represents a WebView running inside an Android app."""
+
+    class Events:
+        Close = "close"
+
+    def __init__(self, device: AndroidDevice, data: Dict) -> None:
+        super().__init__()
+        self._device = device
+        self._data = data
+        self._page_promise: Optional[Any] = None
+
+    @property
+    def pid(self) -> int:
+        return self._data["pid"]
+
+    @property
+    def pkg(self) -> str:
+        return self._data["pkg"]
+
+    def _socket_name(self) -> str:
+        return self._data["socketName"]
+
+    async def page(self) -> Any:
+        if self._page_promise is None:
+            self._page_promise = asyncio.ensure_future(self._fetch_page())
+        return await self._page_promise
+
+    async def _fetch_page(self) -> Any:
+        result = await self._device._channel.send_return_as_dict(
+            "connectToWebView", None, {"socketName": self._data["socketName"]}
+        )
+        context = from_channel(result["context"])
+        return context.pages[0]
+
+
+class AndroidInput:
+    """Low-level input controls for an Android device (touch, keyboard)."""
+
+    def __init__(self, device: AndroidDevice) -> None:
+        self._device = device
+
+    async def type(self, text: str) -> None:
+        await self._device._channel.send("inputType", None, {"text": text})
+
+    async def press(self, key: str) -> None:
+        await self._device._channel.send("inputPress", None, {"key": key})
+
+    async def tap(self, point: Dict) -> None:
+        await self._device._channel.send("inputTap", None, {"point": point})
+
+    async def swipe(self, start: Dict, segments: List[Dict], steps: int) -> None:
+        # Node accepts `from` for signature parity but does not send it, and
+        # AndroidInputSwipeParams lists only segments + steps.
+        await self._device._channel.send(
+            "inputSwipe", None, {"segments": segments, "steps": steps}
+        )
+
+    async def drag(self, start: Dict, end: Dict, steps: int) -> None:
+        await self._device._channel.send(
+            "inputDrag", None, {"from": start, "to": end, "steps": steps}
+        )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _to_selector_channel(selector: Dict) -> Dict:
+    """Convert a Python AndroidSelector dict to the wire protocol format.
+
+    Mirrors Node.js toSelectorChannel() in android.ts — string fields are
+    wrapped in a full-match regex; boolean/int fields pass through unchanged.
+    """
+
+    def _to_regex(value: Optional[Union[str, "re.Pattern[str]"]]) -> Optional[str]:
+        if value is None:
+            return None
+        if isinstance(value, re.Pattern):  # compiled regex — use source directly
+            return value.pattern
+        # Match Node's toSelectorChannel() escaping exactly rather than using
+        # re.escape(): the driver compiles these with java.util.regex, whose
+        # escape rules differ from Python's, and re.escape() additionally
+        # escapes space, #, &, ~ and whitespace characters. The output is
+        # semantically equivalent but not textually identical, so mirror Node
+        # to keep one regex dialect across all language bindings.
+        #   '^' + v.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&').replace(/-/g, '\\x2d') + '$'
+        escaped = re.sub(r"([|\\{}()\[\]^$+*?.])", r"\\\1", str(value))
+        escaped = escaped.replace("-", r"\x2d")
+        return f"^{escaped}$"
+
+    result: Dict = {}
+    for key in (
+        "checkable",
+        "checked",
+        "clickable",
+        "depth",
+        "enabled",
+        "focusable",
+        "focused",
+        "longClickable",
+        "scrollable",
+        "selected",
+    ):
+        if key in selector:
+            result[key] = selector[key]
+    for key in ("clazz", "pkg", "desc", "res", "text"):
+        if key in selector:
+            result[key] = _to_regex(selector[key])
+    if "hasChild" in selector:
+        result["hasChild"] = {
+            "androidSelector": _to_selector_channel(selector["hasChild"]["selector"])
+        }
+    if "hasDescendant" in selector:
+        d = selector["hasDescendant"]
+        entry: Dict = {"androidSelector": _to_selector_channel(d["selector"])}
+        if "maxDepth" in d:
+            entry["maxDepth"] = d["maxDepth"]
+        result["hasDescendant"] = entry
+    return result
+
+
+async def _load_file(file: Union[str, Path, bytes]) -> bytes:
+    """Read a file path into bytes, or return the bytes as-is."""
+    if isinstance(file, bytes):
+        return file
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, lambda: Path(file).read_bytes())