android-driver 0.0.1__py3-none-any.whl

android_driver/emulator.py

@@ -0,0 +1,277 @@
+"""AVD lifecycle and snapshots — the determinism layer.
+
+Snapshots are the reason this package exists. Reinstalling an app and walking it
+back to a known screen costs 30-90 seconds; loading a snapshot costs 2-5. For an
+agent doing bug-repro-by-variation, that difference is the difference between
+exploring three hypotheses and exploring thirty.
+
+The emulator console is reached through `adb emu <cmd>`, which handles the
+console auth token for us — no ~/.emulator_console_auth_token juggling.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from pathlib import Path
+
+from .adb import AdbError, list_devices, shell
+from .adb import _adb as _adb_raw
+from .log import log
+
+
+class EmulatorError(RuntimeError):
+    pass
+
+
+def sdk_root() -> Path:
+    """Locate the Android SDK. Honours ANDROID_HOME / ANDROID_SDK_ROOT, then guesses."""
+    for var in ("ANDROID_HOME", "ANDROID_SDK_ROOT"):
+        value = os.environ.get(var)
+        if value and Path(value).is_dir():
+            return Path(value)
+    for guess in (
+        Path.home() / "Library/Android/sdk",  # macOS
+        Path.home() / "Android/Sdk",  # Linux
+        Path.home() / "AppData/Local/Android/Sdk",  # Windows
+    ):
+        if guess.is_dir():
+            return guess
+    raise EmulatorError(
+        "Android SDK not found. Set ANDROID_HOME to your SDK directory "
+        "(e.g. ~/Library/Android/sdk on macOS)."
+    )
+
+
+def emulator_binary() -> Path:
+    path = sdk_root() / "emulator" / "emulator"
+    if not path.is_file():
+        raise EmulatorError(
+            f"emulator binary not found at {path}. Install it via Android Studio's "
+            "SDK Manager, or `sdkmanager emulator`."
+        )
+    return path
+
+
+def list_avds() -> list[str]:
+    result = subprocess.run(
+        [str(emulator_binary()), "-list-avds"], text=True, capture_output=True, check=False, timeout=60
+    )
+    if result.returncode != 0:
+        raise EmulatorError(f"emulator -list-avds failed: {result.stderr.strip()}")
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def avd_name_of(serial: str) -> str | None:
+    """Ask a running emulator which AVD it is. Returns None for physical devices."""
+    if not serial.startswith("emulator-"):
+        return None
+    result = _adb_raw(["-s", serial, "emu", "avd", "name"], check=False, timeout=15)
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if line and line != "OK":
+            return line
+    return None
+
+
+def running_emulators() -> dict[str, str | None]:
+    """Map serial → AVD name for every attached emulator."""
+    return {
+        d["serial"]: avd_name_of(d["serial"])
+        for d in list_devices()
+        if d["serial"].startswith("emulator-")
+    }
+
+
+def is_booted(serial: str) -> bool:
+    """True once the framework is up AND the boot animation has finished.
+
+    `sys.boot_completed` alone is not enough: it flips while the boot animation is
+    still playing, and UI automation against that window fails in ways that look
+    like flaky selectors rather than "the device is not ready yet".
+    """
+    try:
+        completed = shell(serial, "getprop", "sys.boot_completed", check=False, timeout=15).strip()
+        bootanim = shell(serial, "getprop", "init.svc.bootanim", check=False, timeout=15).strip()
+    except AdbError:
+        return False
+    return completed == "1" and bootanim == "stopped"
+
+
+def wait_for_boot(serial: str, timeout_s: int = 300, poll_s: float = 2.0) -> dict:
+    """Block until `serial` has fully booted."""
+    deadline = time.monotonic() + timeout_s
+    started = time.monotonic()
+    while time.monotonic() < deadline:
+        if is_booted(serial):
+            elapsed = round(time.monotonic() - started, 1)
+            log("emulator", f"{serial} booted in {elapsed}s")
+            return {"ok": True, "serial": serial, "boot_seconds": elapsed}
+        time.sleep(poll_s)
+    return {"ok": False, "serial": serial, "error": f"boot timeout after {timeout_s}s"}
+
+
+def start(
+    avd: str,
+    *,
+    headless: bool = False,
+    cold_boot: bool = False,
+    wipe_data: bool = False,
+    snapshot: str | None = None,
+    writable_system: bool = False,
+    extra_args: list[str] | None = None,
+    boot_timeout_s: int = 300,
+) -> dict:
+    """Boot an AVD and wait for it to be usable. Returns its serial.
+
+    If the AVD is already running, returns the existing serial instead of booting a
+    second copy — an agent that calls `start_emulator` defensively at the top of
+    every run should not end up with four emulators fighting over the same ports.
+    """
+    available = list_avds()
+    if avd not in available:
+        raise EmulatorError(f"unknown AVD {avd!r}. Available: {available}")
+
+    already = {name: serial for serial, name in running_emulators().items() if name}
+    if avd in already:
+        serial = already[avd]
+        log("emulator", f"{avd} already running as {serial}; reusing")
+        return {"ok": True, "serial": serial, "avd": avd, "reused": True}
+
+    before = {d["serial"] for d in list_devices()}
+    cmd = [str(emulator_binary()), "-avd", avd]
+    if headless:
+        cmd += ["-no-window", "-no-audio"]
+    if cold_boot:
+        cmd += ["-no-snapshot-load"]
+    if wipe_data:
+        cmd += ["-wipe-data"]
+    if snapshot:
+        cmd += ["-snapshot", snapshot]
+    if writable_system:
+        cmd += ["-writable-system"]
+    cmd += extra_args or []
+
+    log("emulator", f"launching: {' '.join(cmd)}")
+    # Detached: the emulator outlives this call and must not die with the MCP
+    # server's process group, nor block on a pipe nobody reads.
+    subprocess.Popen(
+        cmd,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+    deadline = time.monotonic() + boot_timeout_s
+    serial: str | None = None
+    while time.monotonic() < deadline and serial is None:
+        time.sleep(2.0)
+        for candidate in {d["serial"] for d in list_devices()} - before:
+            if candidate.startswith("emulator-"):
+                serial = candidate
+                break
+    if serial is None:
+        raise EmulatorError(
+            f"{avd} did not appear in `adb devices` within {boot_timeout_s}s. "
+            f"Try launching it by hand to see the error: {' '.join(cmd)}"
+        )
+
+    remaining = max(30, int(deadline - time.monotonic()))
+    boot = wait_for_boot(serial, timeout_s=remaining)
+    return {**boot, "avd": avd, "serial": serial, "reused": False}
+
+
+def stop(serial: str) -> dict:
+    """Shut down a running emulator via its console."""
+    result = _adb_raw(["-s", serial, "emu", "kill"], check=False, timeout=30)
+    combined = result.stdout + result.stderr
+    if result.returncode != 0 and "OK" not in combined:
+        raise EmulatorError(f"could not stop {serial}: {combined.strip()}")
+    for _ in range(15):
+        if serial not in {d["serial"] for d in list_devices()}:
+            return {"ok": True, "serial": serial}
+        time.sleep(1.0)
+    return {"ok": False, "serial": serial, "error": "still attached 15s after `emu kill`"}
+
+
+# ── snapshots ─────────────────────────────────────────────────────────────────
+
+
+def _snapshot_cmd(serial: str, *args: str) -> str:
+    if not serial.startswith("emulator-"):
+        raise EmulatorError(f"{serial} is not an emulator — snapshots are emulator-only.")
+    result = _adb_raw(["-s", serial, "emu", "avd", "snapshot", *args], check=False, timeout=180)
+    combined = (result.stdout + result.stderr).strip()
+    # The console answers "KO: <reason>" on its own line. Substring-matching "KO"
+    # against the whole blob would also fire on a snapshot named e.g. "OKO".
+    failed = any(line.strip().startswith("KO") for line in combined.splitlines())
+    if result.returncode != 0 or failed:
+        raise EmulatorError(f"snapshot {' '.join(args)} on {serial} failed: {combined}")
+    return combined
+
+
+def snapshot_save(serial: str, name: str) -> dict:
+    """Freeze the device's exact current state under `name`.
+
+    Save right after your app is installed, permissions granted, and you are on the
+    screen a test starts from. Every later `snapshot_load(name)` returns to exactly
+    that point, so a repro attempt starts from identical state every time.
+    """
+    started = time.monotonic()
+    _snapshot_cmd(serial, "save", name)
+    return {"ok": True, "serial": serial, "snapshot": name, "seconds": round(time.monotonic() - started, 1)}
+
+
+def snapshot_load(serial: str, name: str, settle_timeout_s: int = 120) -> dict:
+    """Restore `name`, then wait until the device can actually be driven again.
+
+    The restore swaps the running system out wholesale. For a second or two after
+    the console returns, `adb` reports the device `offline` and the uiautomator
+    server is a process from the restored image rather than the one we were
+    talking to. Returning at that point hands the caller a device whose next call
+    dies with `RemoteDisconnected` or `device offline` — which reads as a broken
+    app, three steps into a flow, and sends you debugging the wrong thing.
+    """
+    started = time.monotonic()
+    _snapshot_cmd(serial, "load", name)
+    # Let the restore drop the device before asking whether it is back: polling
+    # immediately can still observe the pre-restore connection and pass at once.
+    time.sleep(1.0)
+    ready = wait_for_boot(serial, timeout_s=settle_timeout_s)
+    seconds = round(time.monotonic() - started, 1)
+    if not ready.get("ok"):
+        raise EmulatorError(
+            f"{serial} did not come back within {settle_timeout_s}s after loading snapshot {name!r}"
+        )
+    return {"ok": True, "serial": serial, "snapshot": name, "seconds": seconds}
+
+
+def snapshot_delete(serial: str, name: str) -> dict:
+    _snapshot_cmd(serial, "delete", name)
+    return {"ok": True, "serial": serial, "snapshot": name}
+
+
+def snapshot_list(serial: str) -> list[str]:
+    """Snapshot names known to the running emulator.
+
+    The console prints a table whose ID column is `--` on current emulator builds
+    and an integer on older ones, so both are accepted:
+
+        ID        TAG                 VM SIZE                DATE     VM CLOCK
+        --        default_boot           458M 2026-08-26 20:26:32  211:41:03.770
+    """
+    raw = _snapshot_cmd(serial, "list")
+    names: list[str] = []
+    for raw_line in raw.splitlines():
+        line = raw_line.strip()
+        if not line or line == "OK" or line.startswith(("ID", "List of snapshots", "There are no")):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        is_row = parts[0].isdigit() or set(parts[0]) == {"-"}
+        if is_row and set(parts[1]) != {"-"}:
+            names.append(parts[1])
+    return names

android_driver/expect.py

@@ -0,0 +1,190 @@
+"""Assertions — the verbs that turn *driving* an app into *testing* it.
+
+Everything here returns `{"ok": bool, "passed": bool, ...}`. `ok` mirrors
+`passed`, so an agent can branch on the same field it uses everywhere else, and
+a failing assertion is a normal result rather than an exception.
+
+Every failure carries enough context to act on without a follow-up call: a
+missing element comes back with the screen index that *was* there, a log
+assertion with the tail it searched. That is deliberate — the round trip an
+agent would otherwise make is the expensive part.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any
+
+from . import adb
+from .config import Config
+from .session import Session
+
+# Patterns that mean "the app died", in the order we report them.
+CRASH_PATTERNS = (
+    ("fatal_exception", re.compile(r"FATAL EXCEPTION")),
+    ("anr", re.compile(r"\bANR in ([\w.]+)")),
+    ("native_crash", re.compile(r"signal \d+ \(SIG\w+\)")),
+    ("tombstone", re.compile(r"Tombstone written to:")),
+)
+
+# How many lines around a crash marker we keep as the excerpt. The lookback
+# matters for native crashes: `signal 11 (SIGSEGV)` says nothing about which
+# process died — the `pid: ..., name: <pkg>` line above it does.
+CRASH_CONTEXT_LINES = 25
+CRASH_LOOKBACK_LINES = 6
+
+
+def _active(selector: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in selector.items() if v is not None and k != "index"}
+
+
+def _fail(reason: str, **fields: Any) -> dict[str, Any]:
+    return {"ok": False, "passed": False, "error": reason, **fields}
+
+
+def _pass(**fields: Any) -> dict[str, Any]:
+    return {"ok": True, "passed": True, **fields}
+
+
+def visible(session: Session, timeout_s: float = 10.0, **selector: Any) -> dict[str, Any]:
+    """Poll until an element matching `selector` is on screen."""
+    active = _active(selector)
+    if not active:
+        raise ValueError("expect_visible needs a selector: ref / text / contains / desc / id / cls")
+    started = time.monotonic()
+    try:
+        element = session.wait_for(timeout_s, **selector)
+    except LookupError:
+        return _fail(
+            f"nothing matching {active} appeared within {timeout_s}s",
+            selector=active,
+            waited_s=round(time.monotonic() - started, 2),
+            screen=session.screen_text(),
+        )
+    return _pass(
+        selector=active,
+        found=element.to_dict(),
+        waited_s=round(time.monotonic() - started, 2),
+    )
+
+
+def gone(session: Session, timeout_s: float = 10.0, **selector: Any) -> dict[str, Any]:
+    """Poll until nothing matches `selector` — for dismissals and loading spinners."""
+    active = _active(selector)
+    if not active:
+        raise ValueError("expect_gone needs a selector: ref / text / contains / desc / id / cls")
+    started = time.monotonic()
+    try:
+        session.wait_until_gone(timeout_s, **selector)
+    except TimeoutError as e:
+        return _fail(
+            str(e),
+            selector=active,
+            waited_s=round(time.monotonic() - started, 2),
+            screen=session.screen_text(),
+        )
+    return _pass(selector=active, waited_s=round(time.monotonic() - started, 2))
+
+
+def log_matches(
+    session: Session,
+    cfg: Config,
+    pattern: str,
+    timeout_s: float = 30.0,
+    poll_s: float = 1.0,
+    only_app: bool = True,
+    level: str | None = None,
+    lines: int = 4000,
+) -> dict[str, Any]:
+    """Poll logcat until `pattern` (a regex) shows up.
+
+    Clear the buffer first — `logcat_clear`, or just start a run, which does it
+    for you — or a match left over from a previous attempt will pass this.
+    """
+    try:
+        re.compile(pattern)
+    except re.error as e:
+        raise ValueError(f"{pattern!r} is not a valid regex: {e}") from e
+
+    pkg = cfg.app.package if (only_app and cfg.app.package) else None
+    started = time.monotonic()
+    deadline = started + timeout_s
+    found: list[str] = []
+    while True:
+        found = adb.logcat_dump(session.serial, lines=lines, pkg=pkg, pattern=pattern, level=level)
+        if found:
+            return _pass(
+                pattern=pattern,
+                count=len(found),
+                matches=found[-10:],
+                waited_s=round(time.monotonic() - started, 2),
+            )
+        if time.monotonic() >= deadline:
+            break
+        time.sleep(poll_s)
+
+    tail = adb.logcat_dump(session.serial, lines=40, pkg=pkg, level=level)
+    return _fail(
+        f"no logcat line matched {pattern!r} within {timeout_s}s",
+        pattern=pattern,
+        waited_s=round(time.monotonic() - started, 2),
+        tail=tail[-25:],
+    )
+
+
+def scan_crashes(lines: list[str], pkg: str | None = None) -> list[dict[str, Any]]:
+    """Pull crash records out of raw logcat lines.
+
+    When `pkg` is given, a Java crash is only reported if its `Process:` line
+    names that package — otherwise every unrelated system crash on the device
+    would fail the assertion, which trains an agent to ignore it.
+    """
+    crashes: list[dict[str, Any]] = []
+    last_index = -CRASH_CONTEXT_LINES
+    for i, line in enumerate(lines):
+        for kind, rx in CRASH_PATTERNS:
+            match = rx.search(line)
+            if not match:
+                continue
+            excerpt = lines[max(0, i - CRASH_LOOKBACK_LINES) : i + CRASH_CONTEXT_LINES]
+            if pkg:
+                named = pkg in "\n".join(excerpt)
+                if kind == "anr" and match.lastindex:
+                    named = match.group(1) == pkg
+                if not named:
+                    continue
+            # One dying process writes several markers (signal, then tombstone);
+            # reporting them as separate crashes would overstate what happened.
+            if i - last_index < CRASH_CONTEXT_LINES and crashes:
+                break
+            last_index = i
+            crashes.append({"kind": kind, "line": line.strip(), "excerpt": excerpt})
+            break
+    return crashes
+
+
+def no_crash(
+    session: Session,
+    cfg: Config,
+    pkg: str | None = None,
+    lines: int = 4000,
+) -> dict[str, Any]:
+    """Assert nothing in the log says the app died.
+
+    Reads the dedicated `crash` buffer as well as `main`: a native abort or a
+    tombstone never reaches `main` at all, so a check that only reads `main`
+    quietly passes on the worst class of failure there is.
+    """
+    target = pkg or cfg.app.package
+    log_lines = adb.logcat_dump(session.serial, lines=lines, buffers="main,crash")
+    crashes = scan_crashes(log_lines, target)
+    if crashes:
+        first = crashes[0]
+        return _fail(
+            f"{len(crashes)} crash record(s) in the log; first is {first['kind']}",
+            pkg=target,
+            crashes=[{"kind": c["kind"], "line": c["line"]} for c in crashes],
+            excerpt=first["excerpt"],
+        )
+    return _pass(pkg=target, scanned_lines=len(log_lines))

android_driver/log.py

@@ -0,0 +1,16 @@
+"""Diagnostic logging.
+
+stdout is reserved for the MCP JSON-RPC frame under the stdio transport, so
+EVERY diagnostic write in this package goes to stderr. Corrupting stdout with a
+stray print() breaks the protocol in a way that is very hard to debug from the
+client side.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+
+def log(component: str, msg: str) -> None:
+    print(f"[{time.strftime('%H:%M:%S')}] [{component}] {msg}", file=sys.stderr, flush=True)