android-driver 0.0.1__py3-none-any.whl

android_driver/config.py

@@ -0,0 +1,211 @@
+"""Project configuration: `.android-driver.yaml` discovery, parsing, defaults.
+
+Everything app-specific lives in the *consumer's* repo, never in this package.
+The file is optional — with no config at all the server still exposes every
+generic tool; only `build_app` and the recipe tools need it.
+
+Discovery walks up from `$ANDROID_DRIVER_PROJECT` (or the process cwd) looking for
+`.android-driver.yaml` / `.android_driver.yml` / `android_driver.yaml`. The directory
+holding the file becomes `project_root`, and every relative path in the config
+resolves against it — so `apk_glob` and `command` behave the same no matter
+which directory the MCP client happened to launch us from.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .log import log
+
+CONFIG_NAMES = (".android-driver.yaml", ".android-driver.yml", "android-driver.yaml", "android-driver.yml")
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+@dataclass
+class AppConfig:
+    package: str | None = None
+    activity: str | None = None
+
+
+@dataclass
+class BuildConfig:
+    command: str | None = None
+    apk_glob: str | None = None
+    apk: str | None = None
+    timeout_s: int = 900
+
+
+@dataclass
+class InstallConfig:
+    # "uninstall-then-install" is the default for a reason: debug APKs built from
+    # different branches carry different signing keys, and `pm install -r` then
+    # fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE. Reinstall is offered for
+    # projects that deliberately want to preserve app data across installs.
+    strategy: str = "uninstall-then-install"
+    grant_runtime_perms: bool = True
+    appops: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        allowed = {"uninstall-then-install", "reinstall"}
+        if self.strategy not in allowed:
+            raise ConfigError(f"install.strategy must be one of {sorted(allowed)}, got {self.strategy!r}")
+
+
+@dataclass
+class TimingConfig:
+    # Cold-start settle before the first UI query. Compose recomposition after a
+    # long idle regularly takes seconds on slower hardware; undersleeping races
+    # the first tap and produces "element not found" on a screen that is fine.
+    cold_start_settle_s: float = 2.0
+    # Post-click settle. Many Compose buttons render as android.view.View with
+    # clickable=false in the accessibility tree, so a fast follow-up query hits
+    # pre-animation state and misses the screen that is currently transitioning in.
+    click_settle_s: float = 0.25
+    boot_timeout_s: int = 300
+    default_find_timeout_s: int = 10
+
+
+@dataclass
+class DriverConfig:
+    # "auto" prefers uiautomator2 and silently falls back to the pure-adb driver
+    # when u2 is unavailable (not installed, or the device-side agent is missing).
+    backend: str = "auto"
+
+    def __post_init__(self) -> None:
+        allowed = {"auto", "uiautomator2", "adb"}
+        if self.backend not in allowed:
+            raise ConfigError(f"driver.backend must be one of {sorted(allowed)}, got {self.backend!r}")
+
+
+@dataclass
+class Config:
+    project_root: Path
+    source: Path | None
+    app: AppConfig = field(default_factory=AppConfig)
+    build: BuildConfig = field(default_factory=BuildConfig)
+    install: InstallConfig = field(default_factory=InstallConfig)
+    timing: TimingConfig = field(default_factory=TimingConfig)
+    driver: DriverConfig = field(default_factory=DriverConfig)
+    markers: dict[str, str] = field(default_factory=dict)
+    recipes: dict[str, Any] = field(default_factory=dict)
+    selectors: dict[str, Any] = field(default_factory=dict)
+    runs_dir: Path = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.runs_dir = self.project_root / "runs"
+
+    @property
+    def package(self) -> str:
+        """The configured package, or raise a message that says how to fix it."""
+        if not self.app.package:
+            raise ConfigError(
+                "no app package configured. Either pass `pkg=` explicitly, or add to "
+                f"{self.source or (self.project_root / CONFIG_NAMES[0])}:\n"
+                "  app:\n    package: com.example.myapp"
+            )
+        return self.app.package
+
+
+# Directories never worth descending into when looking for a config.
+_SKIP_DIRS = {"build", ".git", ".gradle", ".idea", "node_modules", "venv", ".venv", "__pycache__"}
+
+
+def find_config_file(start: Path | None = None) -> Path | None:
+    """Find the project config: walk up from `start`, then look a short way down.
+
+    Walking up is the normal case. The downward pass exists because the app under
+    test is often *not* at the directory the client was opened in — a repo whose
+    Android app lives in `app/` or `test_app/` is completely ordinary, and without
+    it every tool fails with "no app package configured" while a perfectly good
+    config sits one level below. Ambiguity is refused rather than guessed at.
+    """
+    here = (start or Path(os.environ.get("ANDROID_DRIVER_PROJECT", "."))).expanduser().resolve()
+    if here.is_file():
+        here = here.parent
+    for candidate in [here, *here.parents]:
+        for name in CONFIG_NAMES:
+            path = candidate / name
+            if path.is_file():
+                return path
+    return find_config_below(here)
+
+
+def find_config_below(root: Path, max_depth: int = 3) -> Path | None:
+    """The single config beneath `root`, or None when there is no single answer."""
+    found: list[Path] = []
+    for depth in range(1, max_depth + 1):
+        for name in CONFIG_NAMES:
+            for path in root.glob("/".join(["*"] * depth + [name])):
+                if path.is_file() and not any(part in _SKIP_DIRS for part in path.parts):
+                    found.append(path)
+        if found:
+            break
+    if len(found) == 1:
+        log("config", f"no config at {root}; using the one below it: {found[0]}")
+        return found[0]
+    if found:
+        log(
+            "config",
+            f"{len(found)} configs below {root} and none at it: {[str(p) for p in sorted(found)]}. "
+            "Set ANDROID_DRIVER_PROJECT to the one you mean.",
+        )
+    return None
+
+
+def _section(raw: dict[str, Any], key: str) -> dict[str, Any]:
+    value = raw.get(key) or {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"config section {key!r} must be a mapping, got {type(value).__name__}")
+    return value
+
+
+def _build_dataclass(cls: type, raw: dict[str, Any], section: str):
+    known = {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore[attr-defined]
+    unknown = set(raw) - known
+    if unknown:
+        raise ConfigError(f"unknown key(s) in config section {section!r}: {sorted(unknown)}")
+    return cls(**raw)
+
+
+def load(path: Path | None = None) -> Config:
+    """Load the project config, falling back to an all-defaults config when absent."""
+    source = path or find_config_file()
+    if source is None:
+        root = Path(os.environ.get("ANDROID_DRIVER_PROJECT", ".")).expanduser().resolve()
+        log("config", f"no config file found; using defaults with project_root={root}")
+        return Config(project_root=root, source=None)
+
+    try:
+        raw = yaml.safe_load(source.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{source}: invalid YAML: {e}") from e
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{source}: top level must be a mapping, got {type(raw).__name__}")
+
+    known_top = {"app", "build", "install", "timing", "driver", "markers", "recipes", "selectors"}
+    unknown_top = set(raw) - known_top
+    if unknown_top:
+        raise ConfigError(f"{source}: unknown top-level key(s): {sorted(unknown_top)}")
+
+    cfg = Config(
+        project_root=source.parent,
+        source=source,
+        app=_build_dataclass(AppConfig, _section(raw, "app"), "app"),
+        build=_build_dataclass(BuildConfig, _section(raw, "build"), "build"),
+        install=_build_dataclass(InstallConfig, _section(raw, "install"), "install"),
+        timing=_build_dataclass(TimingConfig, _section(raw, "timing"), "timing"),
+        driver=_build_dataclass(DriverConfig, _section(raw, "driver"), "driver"),
+        markers=_section(raw, "markers"),
+        recipes=_section(raw, "recipes"),
+        selectors=_section(raw, "selectors"),
+    )
+    log("config", f"loaded {source} (package={cfg.app.package}, recipes={len(cfg.recipes)})")
+    return cfg

android_driver/drivers/__init__.py

@@ -0,0 +1,22 @@
+"""UI driver backends.
+
+Two implementations behind one interface:
+
+  * `uiautomator2` — fast, and its accessibility SET_TEXT path is the only
+    reliable way to fill a Jetpack Compose TextField. Needs a one-time
+    per-device `python -m uiautomator2 init`, which installs a helper APK.
+  * `adb` — pure `uiautomator dump` + `input`. Slower and weaker at text entry,
+    but needs nothing on the device, so it works in CI containers and on locked
+    down hardware where you cannot install a helper.
+
+`create()` picks between them; `driver.backend: auto` in the project config
+prefers uiautomator2 and falls back silently.
+"""
+
+from __future__ import annotations
+
+from .adb_driver import AdbDriver
+from .base import Driver, DriverError
+from .factory import create
+
+__all__ = ["AdbDriver", "Driver", "DriverError", "create"]

android_driver/drivers/adb_driver.py

@@ -0,0 +1,104 @@
+"""Zero-setup backend: `uiautomator dump` + `input`, nothing installed on device.
+
+Slower than uiautomator2 (a hierarchy dump costs roughly a second) and weaker at
+text entry, but it runs anywhere adb runs — CI containers, corporate-managed
+devices, anywhere you cannot or will not install a helper APK.
+"""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+import time
+from pathlib import Path
+
+from .. import adb
+from ..ui import Element
+from .base import Driver, DriverError
+
+REMOTE_DUMP = "/sdcard/android-driver-dump.xml"
+
+
+class AdbDriver(Driver):
+    name = "adb"
+
+    def dump_hierarchy(self, retries: int = 3) -> str:
+        """Dump the window hierarchy.
+
+        `uiautomator dump` refuses to run while the window is animating, reporting
+        "could not get idle state". That is a transient condition right after a tap,
+        so we retry rather than surfacing it — an agent cannot do anything useful
+        with it anyway.
+        """
+        last = ""
+        for attempt in range(retries):
+            result = adb.shell_result(self.serial, f"uiautomator dump {REMOTE_DUMP}", timeout=60)
+            combined = result["stdout"] + result["stderr"]
+            if "dumped to" in combined or "UI hierchary dumped" in combined:
+                xml = adb.shell_result(self.serial, f"cat {REMOTE_DUMP}", timeout=60)["stdout"]
+                if xml.lstrip().startswith("<"):
+                    return xml
+                last = "dump file was empty or not XML"
+            else:
+                last = combined.strip()
+            if attempt < retries - 1:
+                self._log(f"hierarchy dump retry {attempt + 1}/{retries}: {last}")
+                time.sleep(1.0)
+        raise DriverError(f"uiautomator dump failed after {retries} attempts: {last}")
+
+    def screenshot(self, path: Path) -> Path:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # exec-out keeps the PNG binary-clean; `adb shell screencap -p` mangles
+        # newlines on some hosts.
+        with path.open("wb") as fh:
+            result = subprocess.run(
+                ["adb", "-s", self.serial, "exec-out", "screencap", "-p"],
+                stdout=fh,
+                stderr=subprocess.PIPE,
+                check=False,
+                timeout=120,
+            )
+        if result.returncode != 0 or path.stat().st_size == 0:
+            raise DriverError(f"screencap failed: {result.stderr.decode(errors='replace').strip()}")
+        return path
+
+    def _click(self, x: int, y: int) -> None:
+        adb.shell(self.serial, "input", "tap", str(x), str(y))
+
+    def long_click(self, x: int, y: int, duration_s: float = 1.0) -> None:
+        ms = int(duration_s * 1000)
+        adb.shell(self.serial, "input", "swipe", str(x), str(y), str(x), str(y), str(ms))
+
+    def swipe(self, x1: int, y1: int, x2: int, y2: int, duration_s: float = 0.3) -> None:
+        ms = int(duration_s * 1000)
+        adb.shell(self.serial, "input", "swipe", str(x1), str(y1), str(x2), str(y2), str(ms))
+
+    def press(self, key: str) -> None:
+        adb.shell(self.serial, "input", "keyevent", self._keycode(key))
+
+    def set_text(self, element: Element, text: str) -> None:
+        """Tap the field, clear it, then type.
+
+        This is the fragile path — on Jetpack Compose the tap does not always move
+        focus, and the text can land in a sibling field. The uiautomator2 backend
+        writes to the node directly and does not have this problem; prefer it when
+        the app under test uses Compose.
+        """
+        x, y = element.center
+        self.click(x, y)
+        # Move the caret to the end, then backspace over whatever was there. The
+        # field's current text gives us the count; the margin covers content that
+        # scrolled out of the accessibility snapshot.
+        self.press("KEYCODE_MOVE_END")
+        deletions = len(element.text) + 8
+        adb.shell(self.serial, "input", "keyevent", *(["KEYCODE_DEL"] * deletions), check=False)
+        if text:
+            adb.shell(self.serial, "input", "text", shlex.quote(self._escape(text)))
+        time.sleep(0.2)
+        self.dismiss_keyboard()
+
+    @staticmethod
+    def _escape(text: str) -> str:
+        """`input text` treats a space as an argument separator and %s literally."""
+        return text.replace("%", "%%").replace(" ", "%s")

android_driver/drivers/base.py

@@ -0,0 +1,146 @@
+"""The driver interface, plus the behaviour both backends share."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .. import adb
+from ..log import log
+from ..ui import Element
+
+
+class DriverError(RuntimeError):
+    pass
+
+
+# Friendly key names → Android keycodes. The names match what an agent would
+# guess; unknown names fall through as-is so raw KEYCODE_* still works.
+KEYCODES = {
+    "home": "KEYCODE_HOME",
+    "back": "KEYCODE_BACK",
+    "menu": "KEYCODE_MENU",
+    "enter": "KEYCODE_ENTER",
+    "search": "KEYCODE_SEARCH",
+    "delete": "KEYCODE_DEL",
+    "backspace": "KEYCODE_DEL",
+    "tab": "KEYCODE_TAB",
+    "space": "KEYCODE_SPACE",
+    "power": "KEYCODE_POWER",
+    "volume_up": "KEYCODE_VOLUME_UP",
+    "volume_down": "KEYCODE_VOLUME_DOWN",
+    "camera": "KEYCODE_CAMERA",
+    "app_switch": "KEYCODE_APP_SWITCH",
+    "recent": "KEYCODE_APP_SWITCH",
+    "wake": "KEYCODE_WAKEUP",
+    "sleep": "KEYCODE_SLEEP",
+    "up": "KEYCODE_DPAD_UP",
+    "down": "KEYCODE_DPAD_DOWN",
+    "left": "KEYCODE_DPAD_LEFT",
+    "right": "KEYCODE_DPAD_RIGHT",
+    "center": "KEYCODE_DPAD_CENTER",
+}
+
+
+class Driver(ABC):
+    """One device, one driver. Coordinates are always device pixels."""
+
+    name = "base"
+
+    def __init__(self, serial: str, click_settle_s: float = 0.25) -> None:
+        self.serial = serial
+        self.click_settle_s = click_settle_s
+
+    # ── required of every backend ────────────────────────────────────────────
+
+    @abstractmethod
+    def dump_hierarchy(self) -> str: ...
+
+    @abstractmethod
+    def screenshot(self, path: Path) -> Path: ...
+
+    @abstractmethod
+    def _click(self, x: int, y: int) -> None: ...
+
+    @abstractmethod
+    def long_click(self, x: int, y: int, duration_s: float = 1.0) -> None: ...
+
+    @abstractmethod
+    def swipe(self, x1: int, y1: int, x2: int, y2: int, duration_s: float = 0.3) -> None: ...
+
+    @abstractmethod
+    def press(self, key: str) -> None: ...
+
+    @abstractmethod
+    def set_text(self, element: Element, text: str) -> None:
+        """Replace the contents of a text field with `text`."""
+
+    # ── shared ───────────────────────────────────────────────────────────────
+
+    def click(self, x: int, y: int) -> None:
+        """Tap, then let the UI settle.
+
+        The settle is not cosmetic. Many Compose buttons surface as
+        `android.view.View` with `clickable=false` in the accessibility tree, so a
+        hierarchy query issued immediately after a tap reads pre-animation state
+        and reports the *old* screen — which looks exactly like a missed tap.
+        """
+        self._click(x, y)
+        time.sleep(self.click_settle_s)
+
+    def screen_size(self) -> tuple[int, int]:
+        raw = adb.shell(self.serial, "wm", "size", check=False).strip()
+        for part in reversed(raw.split()):
+            if "x" in part:
+                w, _, h = part.partition("x")
+                if w.isdigit() and h.isdigit():
+                    return int(w), int(h)
+        raise DriverError(f"could not parse screen size from {raw!r}")
+
+    def current_app(self) -> dict[str, str]:
+        """Package and activity currently in the foreground."""
+        out = adb.shell(
+            self.serial, "dumpsys activity activities | grep -E 'mResumedActivity|topResumedActivity'",
+            check=False,
+        )
+        for line in out.splitlines():
+            for raw in line.split():
+                # The component sits inside an ActivityRecord{...} blob, so the
+                # token can carry a trailing brace or comma.
+                token = raw.strip("{},")
+                if "/" in token and "." in token:
+                    pkg, _, activity = token.partition("/")
+                    return {"package": pkg, "activity": activity}
+        return {"package": "", "activity": ""}
+
+    def keyboard_is_shown(self) -> bool:
+        """Authoritative across OEMs: `mInputShown=true` in the IME dump."""
+        try:
+            out = adb.shell(
+                self.serial, "dumpsys input_method | grep mInputShown", check=False, timeout=20
+            )
+        except Exception:
+            return False
+        return "mInputShown=true" in out
+
+    def dismiss_keyboard(self) -> None:
+        """Close the soft keyboard — but only when it is actually open.
+
+        Pressing Back unconditionally is a classic way to lose an hour: with no
+        keyboard up, Back dismisses whatever dialog or screen owns focus instead,
+        and the failure surfaces three steps later as a missing element.
+        """
+        if not self.keyboard_is_shown():
+            return
+        self.press("back")
+        time.sleep(0.3)
+
+    def close(self) -> None:
+        return None
+
+    def _keycode(self, key: str) -> str:
+        return KEYCODES.get(key.lower(), key if key.startswith("KEYCODE_") else f"KEYCODE_{key.upper()}")
+
+    def _log(self, msg: str) -> None:
+        log(f"driver:{self.name}", msg)

android_driver/drivers/factory.py

@@ -0,0 +1,29 @@
+"""Backend selection."""
+
+from __future__ import annotations
+
+from ..log import log
+from .adb_driver import AdbDriver
+from .base import Driver, DriverError
+
+
+def create(serial: str, backend: str = "auto", click_settle_s: float = 0.25) -> Driver:
+    """Build a driver for `serial`.
+
+    `auto` prefers uiautomator2 and falls back to the pure-adb backend, logging
+    which one won so a confused operator can see it in the server's stderr.
+    """
+    if backend == "adb":
+        return AdbDriver(serial, click_settle_s)
+
+    try:
+        from .u2_driver import U2Driver
+
+        driver = U2Driver(serial, click_settle_s)
+        log("driver", f"{serial}: using uiautomator2")
+        return driver
+    except Exception as e:
+        if backend == "uiautomator2":
+            raise DriverError(str(e)) from e
+        log("driver", f"{serial}: uiautomator2 unavailable ({e}); falling back to the adb backend")
+        return AdbDriver(serial, click_settle_s)

android_driver/drivers/u2_driver.py

@@ -0,0 +1,100 @@
+"""uiautomator2 backend — the default when the device-side agent is available."""
+
+from __future__ import annotations
+
+import time
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from ..ui import Element
+from .base import Driver, DriverError
+
+
+class U2Driver(Driver):
+    name = "uiautomator2"
+
+    def __init__(self, serial: str, click_settle_s: float = 0.25, find_timeout_s: int = 10) -> None:
+        super().__init__(serial, click_settle_s)
+        try:
+            import uiautomator2 as u2
+        except ImportError as e:  # pragma: no cover - dependency is declared
+            raise DriverError("uiautomator2 is not installed") from e
+        try:
+            self.d = u2.connect(serial)
+            self.d.implicitly_wait(find_timeout_s)
+        except Exception as e:
+            raise DriverError(
+                f"could not connect uiautomator2 to {serial}: {e}. "
+                f"Run `python -m uiautomator2 init` against the device, or set "
+                "`driver.backend: adb` in your config to use the zero-setup backend."
+            ) from e
+
+    def dump_hierarchy(self) -> str:
+        return self.d.dump_hierarchy()
+
+    def screenshot(self, path: Path) -> Path:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.d.screenshot(str(path))
+        return path
+
+    def _click(self, x: int, y: int) -> None:
+        self.d.click(x, y)
+
+    def long_click(self, x: int, y: int, duration_s: float = 1.0) -> None:
+        self.d.long_click(x, y, duration_s)
+
+    def swipe(self, x1: int, y1: int, x2: int, y2: int, duration_s: float = 0.3) -> None:
+        self.d.swipe(x1, y1, x2, y2, duration=duration_s)
+
+    def press(self, key: str) -> None:
+        friendly = key.lower()
+        if friendly in {"home", "back", "menu", "enter", "search", "delete", "recent", "power",
+                        "volume_up", "volume_down", "camera", "left", "right", "up", "down", "center"}:
+            self.d.press(friendly)
+        else:
+            self.d.shell(f"input keyevent {self._keycode(key)}")
+
+    def set_text(self, element: Element, text: str) -> None:
+        """Write directly to the target node via the accessibility SET_TEXT action.
+
+        Tap-then-type is unreliable on Compose: focus does not always follow the
+        tap and the text lands in a sibling TextField. Addressing the EditText by
+        its document-order index and calling set_text bypasses focus dispatch
+        entirely, which is why this indirection exists.
+        """
+        index = self._edittext_index(element)
+        self.d(className="android.widget.EditText", instance=index).set_text(text)
+        time.sleep(0.2)
+        self.dismiss_keyboard()
+
+    def _edittext_index(self, element: Element) -> int:
+        """Position of `element` among all EditTexts in the current hierarchy.
+
+        Uses a single snapshot so we do not race recomposition between locating the
+        target and enumerating its siblings.
+        """
+        root = ET.fromstring(self.dump_hierarchy())
+        edittexts = [n for n in root.iter("node") if n.attrib.get("class") == "android.widget.EditText"]
+        for i, node in enumerate(edittexts):
+            bounds = node.attrib.get("bounds", "")
+            if bounds and _bounds_match(bounds, element.bounds):
+                return i
+            # Compose renders the label as a descendant View of the EditText, so the
+            # content-desc we matched on may sit one level down.
+            for child in node.iter("node"):
+                if element.desc and child.attrib.get("content-desc") == element.desc:
+                    return i
+                if element.rid and child.attrib.get("resource-id") == element.rid:
+                    return i
+        raise DriverError(
+            f"could not locate an EditText for {element.label()!r}. "
+            "Call `screen` to re-read the current layout."
+        )
+
+
+def _bounds_match(raw: str, bounds: tuple[int, int, int, int]) -> bool:
+    from ..ui import BOUNDS_RE
+
+    m = BOUNDS_RE.match(raw)
+    return bool(m) and tuple(int(g) for g in m.groups()) == bounds