appium-pilot 0.1.0__py3-none-any.whl

appium_pilot/__init__.py

@@ -0,0 +1,3 @@
+"""appium-pilot — agent-first, session-based CLI for driving mobile apps via Appium."""
+
+__version__ = "0.1.0"

appium_pilot/__main__.py

@@ -0,0 +1,4 @@
+from appium_pilot.cli import main
+
+if __name__ == "__main__":
+    main()

appium_pilot/cli.py

@@ -0,0 +1,96 @@
+"""appium-pilot front-end: global flags, subcommand dispatch, error mapping.
+
+Supports `-s=<name>` session selection (default "default") placed anywhere
+before the subcommand.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from selenium.common.exceptions import WebDriverException
+
+from appium_pilot import __version__
+from appium_pilot.commands import (
+    app_cmd,
+    capture_cmd,
+    devices_cmd,
+    doctor_cmd,
+    gesture_cmd,
+    open_cmd,
+    session_cmd,
+    skills_cmd,
+    snapshot_cmd,
+    tap_cmd,
+    type_cmd,
+    video_cmd,
+    wait_cmd,
+)
+from appium_pilot.output import CommandError, fail, set_json_mode
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="appium-pilot",
+        description="Agent-first, session-based CLI for driving mobile apps via Appium.",
+    )
+    parser.add_argument("-s", "--session", default="default", help="session name (default: default)")
+    parser.add_argument("--json", action="store_true", help="emit structured JSON output")
+    parser.add_argument("--version", action="version", version=f"appium-pilot {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True, metavar="<command>")
+    for module in (
+        open_cmd,
+        snapshot_cmd,
+        capture_cmd,
+        tap_cmd,
+        type_cmd,
+        gesture_cmd,
+        wait_cmd,
+        video_cmd,
+        app_cmd,
+        devices_cmd,
+        session_cmd,
+        skills_cmd,
+        doctor_cmd,
+    ):
+        module.add_parser(sub)
+    return parser
+
+
+def _normalize_session_flag(argv: list[str]) -> list[str]:
+    """Allow `-s=name` in addition to argparse's `-s name`."""
+    out: list[str] = []
+    for arg in argv:
+        if arg.startswith("-s=") or arg.startswith("--session="):
+            out.append("--session")
+            out.append(arg.split("=", 1)[1])
+        else:
+            out.append(arg)
+    return out
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = _normalize_session_flag(list(argv if argv is not None else sys.argv[1:]))
+    args = build_parser().parse_args(argv)
+    set_json_mode(args.json)
+
+    try:
+        args.func(args)
+    except CommandError as exc:
+        fail(str(exc), code=exc.code, **exc.data)
+    except WebDriverException as exc:
+        # Driver-level failures (e.g. an action the app/platform rejects) become a
+        # clean one-line error, not a traceback. Set APPIUM_PILOT_DEBUG=1 to see it.
+        if os.environ.get("APPIUM_PILOT_DEBUG"):
+            raise
+        msg = (getattr(exc, "msg", None) or str(exc)).strip().splitlines()[0]
+        fail(f"driver error: {msg}")
+    except KeyboardInterrupt:
+        fail("interrupted", code=130)
+
+
+if __name__ == "__main__":
+    main()

appium_pilot/commands/__init__.py

@@ -0,0 +1 @@
+"""Command handlers."""

appium_pilot/commands/app_cmd.py

@@ -0,0 +1,106 @@
+"""App lifecycle (`launch`/`terminate`/`activate`/`background`/`install`/`remove`/`reset`)
+and `orientation`."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from appium_pilot.output import CommandError, emit
+from appium_pilot.session import Session
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    for name, help_text in [
+        ("launch", "activate (foreground) the app under test"),
+        ("activate", "activate (foreground) the app under test"),
+        ("terminate", "terminate the app under test"),
+    ]:
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("app_id", nargs="?", help="app id (default: the session's app)")
+        p.set_defaults(func=_make_lifecycle(name))
+
+    bg = sub.add_parser("background", help="background the app for N seconds (-1 = indefinitely)")
+    bg.add_argument("seconds", nargs="?", type=int, default=-1)
+    bg.set_defaults(func=run_background)
+
+    inst = sub.add_parser("install", help="install an app artifact on the device")
+    inst.add_argument("path", help="path to .apk/.app/.ipa")
+    inst.set_defaults(func=run_install)
+
+    rm = sub.add_parser("remove", help="uninstall an app from the device")
+    rm.add_argument("app_id", nargs="?", help="app id (default: the session's app)")
+    rm.set_defaults(func=run_remove)
+
+    rs = sub.add_parser("reset", help="terminate then re-activate the app under test")
+    rs.set_defaults(func=run_reset)
+
+    o = sub.add_parser("orientation", help="get or set screen orientation")
+    o.add_argument("value", nargs="?", choices=["portrait", "landscape"],
+                   help="omit to read the current orientation")
+    o.set_defaults(func=run_orientation)
+
+
+def _app_id(session: Session, explicit: str | None) -> str:
+    app_id = explicit or session.app_id
+    if not app_id:
+        raise CommandError("no app id known for this session; pass one explicitly")
+    return app_id
+
+
+def _make_lifecycle(action: str):
+    def run(args) -> None:
+        session = Session.load(args.session)
+        driver = session.attach()
+        app_id = _app_id(session, args.app_id)
+        if action in ("launch", "activate"):
+            driver.activate_app(app_id)
+            emit(f"activated {app_id}", app=app_id)
+        elif action == "terminate":
+            driver.terminate_app(app_id)
+            emit(f"terminated {app_id}", app=app_id)
+
+    return run
+
+
+def run_background(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    driver.background_app(args.seconds)
+    emit(f"backgrounded app for {args.seconds}s")
+
+
+def run_install(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    path = str(Path(args.path).expanduser().resolve())
+    driver.install_app(path)
+    emit(f"installed {path}", path=path)
+
+
+def run_remove(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    app_id = _app_id(session, args.app_id)
+    driver.remove_app(app_id)
+    emit(f"removed {app_id}", app=app_id)
+
+
+def run_reset(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    app_id = _app_id(session, None)
+    driver.terminate_app(app_id)
+    driver.activate_app(app_id)
+    emit(f"reset {app_id}", app=app_id)
+
+
+def run_orientation(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    if args.value:
+        driver.orientation = args.value.upper()
+        emit(f"orientation set to {args.value}", orientation=args.value.upper())
+    else:
+        current = driver.orientation
+        emit(current, orientation=current)

appium_pilot/commands/capture_cmd.py

@@ -0,0 +1,48 @@
+"""`screenshot` and `source` — pull pixels / raw page source off the device."""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+from appium_pilot import config
+from appium_pilot.output import emit, raw
+from appium_pilot.resolve import find_ref
+from appium_pilot.session import Session
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    sh = sub.add_parser("screenshot", help="save a PNG of the screen (or an element) and print its path")
+    sh.add_argument("ref", nargs="?", help="optional element ref to screenshot instead of the screen")
+    sh.add_argument("-o", "--out", help="output path (default: session screenshots dir)")
+    sh.set_defaults(func=run_screenshot)
+
+    src = sub.add_parser("source", help="print the full raw page source")
+    src.set_defaults(func=run_source)
+
+
+def run_screenshot(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+
+    if args.out:
+        path = args.out
+    else:
+        shots = config.screenshots_dir()
+        shots.mkdir(parents=True, exist_ok=True)
+        path = str(shots / f"shot-{time.strftime('%Y%m%d-%H%M%S')}.png")
+
+    if args.ref:
+        locator = session.locator_for(args.ref)
+        element = find_ref(driver, locator, args.ref)
+        element.screenshot(path)
+    else:
+        driver.get_screenshot_as_file(path)
+
+    emit(path, path=path)
+
+
+def run_source(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    raw(driver.page_source)

appium_pilot/commands/devices_cmd.py

@@ -0,0 +1,30 @@
+"""`devices` — list available simulators/emulators."""
+
+from __future__ import annotations
+
+import argparse
+
+from appium_pilot import devices
+from appium_pilot.output import emit, json_mode
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("devices", help="list available iOS simulators / Android emulators")
+    p.set_defaults(func=run)
+
+
+def run(args) -> None:
+    found = devices.list_all()
+    payload = [
+        {"platform": d.platform, "udid": d.udid, "name": d.name, "booted": d.booted}
+        for d in found
+    ]
+    if json_mode():
+        emit(f"{len(found)} devices", devices=payload)
+        return
+    if not found:
+        emit("no devices found (no booted simulators/emulators or AVDs)")
+        return
+    for d in found:
+        state = "booted" if d.booted else "available"
+        print(f"{d.platform:8} {state:10} {d.name}  ({d.udid})")

appium_pilot/commands/doctor_cmd.py

@@ -0,0 +1,103 @@
+"""`doctor` — diagnose the environment. Never installs anything."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+
+from appium_pilot import config, proc
+from appium_pilot.output import emit, json_mode
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("doctor", help="diagnose Appium/iOS/Android setup (does not install)")
+    p.set_defaults(func=run)
+
+
+def _version(name: str, *args: str) -> str | None:
+    argv = proc.tool(name, *args)
+    if argv is None:
+        return None
+    try:
+        out = subprocess.run(argv, capture_output=True, text=True, timeout=15)
+        return (out.stdout or out.stderr).strip().splitlines()[0] if out.returncode == 0 else None
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _appium_drivers() -> set[str]:
+    argv = proc.tool("appium", "driver", "list", "--installed", "--json")
+    if argv is None:
+        return set()
+    try:
+        out = subprocess.run(argv, capture_output=True, text=True, timeout=30)
+        data = json.loads(out.stdout or out.stderr or "{}")
+        return set(data.keys())
+    except (OSError, subprocess.SubprocessError, json.JSONDecodeError):
+        return set()
+
+
+def run(args) -> None:
+    checks: list[dict] = []
+
+    def check(name: str, ok: bool, detail: str, hint: str = "") -> None:
+        checks.append({"name": name, "ok": ok, "detail": detail, "hint": hint})
+
+    # Core toolchain.
+    node = _version("node", "--version")
+    check("node", node is not None, node or "not found", "install Node.js")
+    npm = _version("npm", "--version")
+    check("npm", npm is not None, npm or "not found", "install Node.js (bundles npm)")
+    appium = _version("appium", "--version")
+    check("appium server", appium is not None, appium or "not found", "npm i -g appium")
+
+    drivers = _appium_drivers() if appium else set()
+    check("uiautomator2 driver", "uiautomator2" in drivers,
+          "installed" if "uiautomator2" in drivers else "missing",
+          "appium driver install uiautomator2")
+    check("xcuitest driver", "xcuitest" in drivers,
+          "installed" if "xcuitest" in drivers else "missing",
+          "appium driver install xcuitest")
+
+    # iOS.
+    xcrun = shutil.which("xcrun")
+    check("xcode command line tools (xcrun)", xcrun is not None,
+          xcrun or "not found", "xcode-select --install")
+
+    # Android.
+    android_home = os.environ.get("ANDROID_HOME") or os.environ.get("ANDROID_SDK_ROOT")
+    check("ANDROID_HOME / ANDROID_SDK_ROOT", bool(android_home),
+          android_home or "not set", "export ANDROID_HOME=~/Library/Android/sdk")
+    from appium_pilot import devices
+
+    adb = devices.android_tool("adb")
+    check("adb", adb is not None, adb or "not found", "install Android platform-tools")
+    emulator = devices.android_tool("emulator")
+    check("emulator", emulator is not None, emulator or "not found", "install Android emulator package")
+
+    # Stale state.
+    server_running = config.SERVER_FILE.exists()
+    session_count = len(list(config.SESSIONS_DIR.glob("*.json"))) if config.SESSIONS_DIR.exists() else 0
+    check("managed appium server record", True,
+          "present" if server_running else "none",
+          "`appium-pilot kill-all` clears stale server/session state")
+    check("persisted sessions", True, f"{session_count} on disk",
+          "`appium-pilot list` to inspect, `close-all` to clear")
+
+    if json_mode():
+        ok = all(c["ok"] for c in checks)
+        emit("doctor complete", ok=ok, checks=checks)
+        return
+
+    for c in checks:
+        mark = "✓" if c["ok"] else "✗"
+        line = f"  {mark} {c['name']}: {c['detail']}"
+        if not c["ok"] and c["hint"]:
+            line += f"\n      → {c['hint']}"
+        print(line)
+    missing = [c for c in checks if not c["ok"]]
+    print()
+    print("doctor: all good" if not missing else f"doctor: {len(missing)} item(s) need attention")

appium_pilot/commands/gesture_cmd.py

@@ -0,0 +1,89 @@
+"""`swipe`, `scroll`, `press`, `hide-keyboard` — gestures and keys."""
+
+from __future__ import annotations
+
+import argparse
+
+from appium_pilot.output import CommandError, emit
+from appium_pilot.resolve import find_ref
+from appium_pilot.session import Session
+from appium_pilot.snapshot import build_snapshot
+from appium_pilot.strategies.base import DIRECTIONS
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    s = sub.add_parser("swipe", help="swipe the screen in a direction")
+    s.add_argument("direction", choices=list(DIRECTIONS) + ["coords"],
+                   help="direction, or 'coords' for explicit x1 y1 x2 y2")
+    s.add_argument("coords", nargs="*", type=int, help="x1 y1 x2 y2 when direction=coords")
+    s.add_argument("--amount", type=float, default=1.0,
+                   help="fraction of screen to swipe (default 1.0); ignored for coords")
+    s.set_defaults(func=run_swipe)
+
+    sc = sub.add_parser("scroll", help="scroll a ref into view, or scroll to text")
+    sc.add_argument("ref", nargs="?", help="ref to scroll into view")
+    sc.add_argument("--to", dest="to_text", help="scroll until text is visible")
+    sc.set_defaults(func=run_scroll)
+
+    pr = sub.add_parser("press", help="press a hardware/system key (back/home/enter/...)")
+    pr.add_argument("key", help="back | home | enter | <android keycode>")
+    pr.set_defaults(func=run_press)
+
+    hk = sub.add_parser("hide-keyboard", help="dismiss the on-screen keyboard")
+    hk.set_defaults(func=run_hide_keyboard)
+
+
+def run_swipe(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    if args.direction == "coords":
+        if len(args.coords) != 4:
+            raise CommandError("coords swipe needs exactly: x1 y1 x2 y2")
+        x1, y1, x2, y2 = args.coords
+        driver.swipe(x1, y1, x2, y2, 400)
+        emit(f"swiped ({x1},{y1})->({x2},{y2})")
+        return
+    session.strategy.swipe(driver, args.direction, args.amount)
+    emit(f"swiped {args.direction}")
+
+
+def run_scroll(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    strategy = session.strategy
+
+    if args.to_text:
+        element = strategy.scroll_to_text(driver, args.to_text)
+        if element is None:
+            raise CommandError(f"could not find text {args.to_text!r} by scrolling", code=2)
+        # Refresh refs so the now-visible element is addressable.
+        _refresh_refs(session, driver)
+        emit(f"scrolled to text {args.to_text!r}; refs refreshed")
+        return
+
+    if not args.ref:
+        raise CommandError("scroll needs a ref or --to <text>")
+    locator = session.locator_for(args.ref)
+    element = find_ref(driver, locator, args.ref)
+    strategy.scroll_to_element(driver, element)
+    emit(f"scrolled {args.ref} into view", ref=args.ref)
+
+
+def run_press(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    session.strategy.press_key(driver, args.key)
+    emit(f"pressed {args.key}")
+
+
+def run_hide_keyboard(args) -> None:
+    session = Session.load(args.session)
+    driver = session.attach()
+    session.strategy.hide_keyboard(driver)
+    emit("keyboard dismissed")
+
+
+def _refresh_refs(session: Session, driver) -> None:  # noqa: ANN001
+    _, refmap = build_snapshot(driver.page_source, session.strategy)
+    session.set_refmap(refmap)
+    session.save()

appium_pilot/commands/open_cmd.py

@@ -0,0 +1,114 @@
+"""`open` — create a session and persist its handle."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Optional
+
+from appium_pilot import config, devices, server
+from appium_pilot.output import CommandError, emit
+from appium_pilot.session import Session, new_driver
+
+AUTOMATION = {"android": "UiAutomator2", "ios": "XCUITest"}
+APP_EXT_PLATFORM = {".apk": "android", ".aab": "android", ".app": "ios", ".ipa": "ios"}
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("open", help="open a session against a device/app")
+    p.add_argument("app", nargs="?", help="path to an app artifact (.app/.apk/.ipa)")
+    p.add_argument("--platform", choices=["android", "ios"], help="target platform")
+    p.add_argument("--device", help="device udid or name (else auto-pick/boot)")
+    p.add_argument("--app", dest="app_flag", help="app artifact path (alternative to positional)")
+    p.add_argument("--app-package", help="Android appPackage of an installed app to launch")
+    p.add_argument("--app-activity", help="Android appActivity (optional)")
+    p.add_argument("--bundle-id", help="iOS bundleId of an installed app to launch")
+    p.add_argument("--cap", action="append", default=[], metavar="k=v",
+                   help="extra capability (repeatable); appium: prefix added if missing")
+    p.add_argument("--caps-file", help="JSON file of capabilities to merge")
+    p.set_defaults(func=run)
+
+
+def _infer_platform(args, app: Optional[str]) -> str:
+    if args.platform:
+        return args.platform
+    if args.bundle_id:
+        return "ios"
+    if args.app_package or args.app_activity:
+        return "android"
+    if app:
+        ext = Path(app).suffix.lower()
+        if ext in APP_EXT_PLATFORM:
+            return APP_EXT_PLATFORM[ext]
+    raise CommandError("could not infer platform; pass --platform android|ios")
+
+
+def _parse_caps(pairs: list[str]) -> dict:
+    caps: dict = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise CommandError(f"bad --cap {pair!r}; expected key=value")
+        key, value = pair.split("=", 1)
+        if ":" not in key and key not in ("platformName",):
+            key = f"appium:{key}"
+        caps[key] = _coerce(value)
+    return caps
+
+
+def _coerce(value: str):
+    low = value.lower()
+    if low in ("true", "false"):
+        return low == "true"
+    if value.isdigit():
+        return int(value)
+    return value
+
+
+def run(args) -> None:
+    app = args.app_flag or args.app
+    platform = _infer_platform(args, app)
+    strategy_automation = AUTOMATION[platform]
+
+    device = devices.resolve(platform, args.device)
+
+    caps: dict = {
+        "platformName": "Android" if platform == "android" else "iOS",
+        "appium:automationName": strategy_automation,
+        "appium:udid": device.udid,
+        "appium:deviceName": device.name,
+        "appium:newCommandTimeout": config.NEW_COMMAND_TIMEOUT,
+    }
+    if app:
+        caps["appium:app"] = str(Path(app).expanduser().resolve())
+    if args.app_package:
+        caps["appium:appPackage"] = args.app_package
+    if args.app_activity:
+        caps["appium:appActivity"] = args.app_activity
+    if args.bundle_id:
+        caps["appium:bundleId"] = args.bundle_id
+
+    if args.caps_file:
+        caps.update(json.loads(Path(args.caps_file).read_text()))
+    caps.update(_parse_caps(args.cap))  # explicit --cap wins
+
+    base_url = server.ensure_server()
+    driver = new_driver(base_url, caps)
+
+    session = Session(
+        name=args.session,
+        server_url=base_url,
+        session_id=driver.session_id,
+        platform=platform,
+        device=device.udid,
+        caps=caps,
+    )
+    session.save()
+
+    emit(
+        f"opened session '{args.session}' on {platform} ({device.name}). Run `snapshot` next.",
+        session=args.session,
+        platform=platform,
+        device=device.udid,
+        session_id=driver.session_id,
+    )