@capagents/forgeqe 1.3.2 → 2.0.0

package/py/forgeqe_mobile/appium_driver.py

@@ -0,0 +1,342 @@
+"""
+The Appium driver: a small W3C WebDriver client over HTTP (no extra packages), implementing the replay ``Driver`` that
+the desktop engine's replay, healing, checks and visual checks already use.
+
+Targets use the same keys as desktop workflows, mapped to each platform's attributes:
+
+| target key     | Android (UiAutomator2)          | iOS (XCUITest)            |
+|----------------|---------------------------------|---------------------------|
+| automation_id  | resource-id (or its id after :id/) | name (accessibility id) |
+| name           | text or content-desc            | label, name or value      |
+| control_type   | class (android.widget.Button)   | type (XCUIElementTypeButton) |
+
+Every value goes into the XPath as a quoted literal, so a target cannot change the query. The Appium server is the
+team's own (default http://127.0.0.1:4723) or a device cloud; a cloud's user and key come from environment variables.
+TLS is verified as usual.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+from forgeqe_desktop.replay import ControlNotFound
+
+from .apps import MobileAppSpec
+
+ANDROID_KEYCODES = {"enter": 66, "back": 4, "tab": 61, "delete": 67, "search": 84}
+MAX_SOURCE = 20_000_000
+# How long a device cloud may take to start a session: its queue for a free device, then installing the app.
+REMOTE_SESSION_TIMEOUT = 900
+
+
+class AppiumError(RuntimeError):
+    """The Appium server refused a command or could not be reached; the message says which."""
+
+
+def xpath_literal(value: str) -> str:
+    """``value`` as an XPath 1.0 string literal, whatever quotes it holds."""
+    if "'" not in value:
+        return f"'{value}'"
+    if '"' not in value:
+        return f'"{value}"'
+    parts = value.split("'")
+    return "concat(" + ", \"'\", ".join(f"'{p}'" for p in parts) + ")"
+
+
+def target_xpath(target: Mapping[str, Any], platform: str) -> str:
+    """The XPath for a target's properties on ``platform``: every given property must match."""
+    conds: List[str] = []
+    aid = target.get("automation_id")
+    name = target.get("name")
+    kind = target.get("control_type") or target.get("class_name")
+    if platform == "android":
+        if aid:
+            lit, suffix = xpath_literal(str(aid)), xpath_literal(":id/" + str(aid))
+            conds.append(f"(@resource-id={lit} or substring(@resource-id, string-length(@resource-id) - string-length({suffix}) + 1) = {suffix})")
+        if name:
+            lit = xpath_literal(str(name))
+            conds.append(f"(@text={lit} or @content-desc={lit})")
+        if kind:
+            conds.append(f"@class={xpath_literal(str(kind))}")
+    else:
+        if aid:
+            conds.append(f"@name={xpath_literal(str(aid))}")
+        if name:
+            lit = xpath_literal(str(name))
+            conds.append(f"(@label={lit} or @name={lit} or @value={lit})")
+        if kind:
+            conds.append(f"@type={xpath_literal(str(kind))}")
+    return "//*" + (f"[{' and '.join(conds)}]" if conds else "")
+
+
+def element_props(node: ET.Element, platform: str) -> Dict[str, str]:
+    """A page-source node's properties as target keys, plus the text it shows."""
+    a = node.attrib
+    if platform == "android":
+        rid = a.get("resource-id", "")
+        props = {
+            "automation_id": rid.split(":id/", 1)[1] if ":id/" in rid else rid,
+            "name": a.get("text") or a.get("content-desc") or "",
+            "control_type": a.get("class") or node.tag,
+            "text": a.get("text") or a.get("content-desc") or "",
+            # The app the control belongs to: a system dialog (a permission prompt) is another package's.
+            "package": a.get("package") or "",
+        }
+    else:
+        props = {
+            "automation_id": a.get("name", ""),
+            "name": a.get("label") or a.get("name") or "",
+            "control_type": a.get("type") or node.tag,
+            "text": a.get("value") or a.get("label") or "",
+        }
+    return {k: v for k, v in props.items() if isinstance(v, str) and v}
+
+
+class AppiumDriver:
+    needs_desktop = False
+
+    def __init__(
+        self,
+        url: str = "http://127.0.0.1:4723",
+        capabilities: Optional[Mapping[str, Any]] = None,
+        username: Optional[str] = None,
+        access_key: Optional[str] = None,
+        command_timeout: float = 120.0,
+        poll: float = 0.4,
+        opener: Optional[Callable[..., Any]] = None,
+    ) -> None:
+        if not url.lower().startswith(("http://", "https://")):
+            raise AppiumError("mobile.appium.url must be an http(s) URL")
+        self.url = url.rstrip("/")
+        self.extra_caps = dict(capabilities or {})
+        self.auth = "Basic " + base64.b64encode(f"{username}:{access_key}".encode()).decode() if username and access_key else None
+        self.command_timeout = command_timeout
+        self.poll = poll
+        self.open = opener or urllib.request.urlopen
+        self.session: Optional[str] = None
+        self.platform = "android"
+        self.app: Optional[MobileAppSpec] = None
+
+    # -- WebDriver over HTTP --------------------------------------------------------------------------------------
+
+    def _call(self, method: str, path: str, body: Optional[Mapping[str, Any]] = None, timeout: Optional[float] = None) -> Any:
+        data = json.dumps(body).encode() if body is not None else (b"{}" if method == "POST" else None)
+        req = urllib.request.Request(self.url + path, data=data, method=method, headers={"Content-Type": "application/json; charset=utf-8"})
+        if self.auth:
+            req.add_header("Authorization", self.auth)
+        try:
+            with self.open(req, timeout=timeout or self.command_timeout) as resp:
+                raw = resp.read(MAX_SOURCE)
+        except urllib.error.HTTPError as e:
+            raw = e.read(100_000)
+            try:
+                value = json.loads(raw or b"{}").get("value") or {}
+            except ValueError:
+                value = {}
+            error = value.get("error") if isinstance(value, dict) else ""
+            message = value.get("message") if isinstance(value, dict) else ""
+            if error == "no such element":
+                raise ControlNotFound(str(message or "no such element")[:500])
+            raise AppiumError(f"Appium: {error or e.code}: {str(message or e.reason)[:500]}")
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, (TimeoutError, socket.timeout)):
+                raise AppiumError(self._timed_out(path, timeout or self.command_timeout))
+            raise AppiumError(f"cannot reach the Appium server at {self.url} ({e.reason}); start it with: appium")
+        except (TimeoutError, socket.timeout):
+            raise AppiumError(self._timed_out(path, timeout or self.command_timeout))
+        try:
+            return json.loads(raw or b"{}").get("value")
+        except ValueError:
+            raise AppiumError("Appium answered with something that is not JSON")
+
+    def _timed_out(self, path: str, seconds: float) -> str:
+        if path == "/session":
+            return (
+                f"the Appium server at {self.url} started no session within {int(seconds)} s"
+                + ("; a device cloud may have queued it behind other sessions: run fewer at once" if self.remote else "")
+            )
+        return f"the Appium server at {self.url} did not answer within {int(seconds)} s"
+
+    @property
+    def remote(self) -> bool:
+        """A device cloud or another machine, where a new session can wait in a queue for a free device."""
+        host = (urllib.parse.urlsplit(self.url).hostname or "").lower()
+        return host not in ("127.0.0.1", "localhost", "::1")
+
+    def _s(self, path: str = "") -> str:
+        if not self.session:
+            raise RuntimeError("the app is not running: the workflow needs a launch step first")
+        return f"/session/{self.session}{path}"
+
+    def _script(self, name: str, args: Mapping[str, Any]) -> Any:
+        return self._call("POST", self._s("/execute/sync"), {"script": name, "args": [dict(args)]})
+
+    # -- Driver ---------------------------------------------------------------------------------------------------
+
+    def launch(self, app: MobileAppSpec, timeout: Optional[float] = None) -> None:
+        self.app = app
+        self.platform = app.platform
+        if self.session:
+            self._script("mobile: activateApp", {"appId": app.app_id} if app.platform == "android" else {"bundleId": app.app_id})
+            return
+        caps = {**app.capabilities(), **self.extra_caps}
+        # TestMu AI (LambdaTest) reads the app from LT:Options: the app's own build, unless the config names one there.
+        lt = caps.get("LT:Options")
+        if isinstance(lt, dict) and app.app and "app" not in lt:
+            caps["LT:Options"] = {**lt, "app": app.app}
+        # A cloud queues a session until a device is free (TestMu up to 10 minutes) and then installs the app.
+        wait = max(timeout or 0, REMOTE_SESSION_TIMEOUT) if self.remote else (timeout or 300)
+        value = self._call("POST", "/session", {"capabilities": {"alwaysMatch": caps, "firstMatch": [{}]}}, timeout=wait)
+        session = value.get("sessionId") if isinstance(value, dict) else None
+        if not isinstance(session, str) or not session:
+            raise AppiumError("Appium started no session")
+        self.session = session
+
+    def find(self, target: Mapping[str, Any], timeout: float) -> Any:
+        xpath = target_xpath(target, self.platform)
+        index = int(target.get("index", 0) or 0)
+        deadline = time.time() + timeout
+        while True:
+            found = self._call("POST", self._s("/elements"), {"using": "xpath", "value": xpath}) or []
+            if isinstance(found, list) and len(found) > index:
+                el = found[index]
+                if isinstance(el, dict):
+                    ref = el.get("element-6066-11e4-a52e-4f735466cecf") or el.get("ELEMENT")
+                    if isinstance(ref, str):
+                        return ref
+            if time.time() >= deadline:
+                raise ControlNotFound(f"no control matches {dict(target)}")
+            time.sleep(self.poll)
+
+    def wait_ready(self, control: Any, timeout: float) -> None:
+        deadline = time.time() + timeout
+        while True:
+            try:
+                if self._call("GET", self._s(f"/element/{control}/displayed")) and self._call("GET", self._s(f"/element/{control}/enabled")):
+                    return
+            except AppiumError:
+                return
+            if time.time() >= deadline:
+                raise TimeoutError(f"the control is on screen but stayed disabled or hidden for {timeout:g} s")
+            time.sleep(self.poll)
+
+    def click(self, control: Any, double: bool = False) -> None:
+        if not double:
+            self._call("POST", self._s(f"/element/{control}/click"))
+        elif self.platform == "android":
+            self._script("mobile: doubleClickGesture", {"elementId": control})
+        else:
+            self._script("mobile: doubleTap", {"elementId": control})
+
+    def long_press(self, control: Any) -> None:
+        if self.platform == "android":
+            self._script("mobile: longClickGesture", {"elementId": control, "duration": 1000})
+        else:
+            self._script("mobile: touchAndHold", {"elementId": control, "duration": 1.0})
+
+    def type_text(self, control: Any, text: str) -> None:
+        self._call("POST", self._s(f"/element/{control}/clear"))
+        self._call("POST", self._s(f"/element/{control}/value"), {"text": text, "value": list(text)})
+
+    def select(self, control: Any, value: str) -> None:
+        self.click(control)
+        self.click(self.find({"name": value}, 10))
+
+    def text_of(self, control: Any) -> str:
+        texts = [str(self._call("GET", self._s(f"/element/{control}/text")) or "")]
+        for attr in (("content-desc",) if self.platform == "android" else ("label", "value")):
+            try:
+                v = self._call("GET", self._s(f"/element/{control}/attribute/{attr}"))
+                if isinstance(v, str) and v and v not in texts:
+                    texts.append(v)
+            except (AppiumError, ControlNotFound):
+                pass
+        return "\n".join(t for t in texts if t)
+
+    def press_key(self, key: str) -> None:
+        if self.platform == "android":
+            self._script("mobile: pressKey", {"keycode": ANDROID_KEYCODES[key]})
+        elif key == "enter":
+            self._call("POST", self._s("/actions"), {"actions": [{"type": "key", "id": "keyboard", "actions": [{"type": "keyDown", "value": ""}, {"type": "keyUp", "value": ""}]}]})
+        else:
+            raise AppiumError(f"the {key} key does not exist on iOS")
+
+    def back(self) -> None:
+        self._call("POST", self._s("/back"))
+
+    def hide_keyboard(self) -> None:
+        try:
+            self._call("POST", self._s("/appium/device/hide_keyboard"))
+        except AppiumError:
+            pass  # no keyboard was shown
+
+    def _screen(self) -> Dict[str, int]:
+        rect = self._call("GET", self._s("/window/rect")) or {}
+        return {"left": 0, "top": int(rect.get("height", 0) * 0.15), "width": int(rect.get("width", 0)), "height": int(rect.get("height", 0) * 0.7)}
+
+    def swipe(self, direction: str, control: Any = None) -> None:
+        """A finger swipe in ``direction`` (on the control, or across the screen)."""
+        if self.platform == "android":
+            area = {"elementId": control} if control else self._screen()
+            self._script("mobile: swipeGesture", {**area, "direction": direction, "percent": 0.75})
+        else:
+            self._script("mobile: swipe", {"direction": direction, **({"elementId": control} if control else {})})
+
+    def scroll(self, direction: str) -> None:
+        """Move the content so that what is further ``direction`` (down: further down the page) comes into view."""
+        if self.platform == "android":
+            self._script("mobile: scrollGesture", {**self._screen(), "direction": direction, "percent": 0.8})
+        else:
+            self._script("mobile: scroll", {"direction": direction})
+
+    def describe(self, limit: int = 400, texts: bool = False) -> List[Dict[str, str]]:
+        source = self._call("GET", self._s("/source")) or ""
+        try:
+            root = ET.fromstring(source.encode("utf-8") if isinstance(source, str) else source)
+        except ET.ParseError:
+            return []
+        out: List[Dict[str, str]] = []
+        for node in root.iter():
+            props = element_props(node, self.platform)
+            if not texts:
+                props.pop("text", None)
+            if props.get("automation_id") or props.get("name"):
+                out.append(props)
+            if len(out) >= limit:
+                break
+        return out
+
+    def screenshot_png(self) -> Optional[bytes]:
+        if not self.session:
+            return None
+        try:
+            return base64.b64decode(self._call("GET", self._s("/screenshot")) or "")
+        except Exception:
+            return None
+
+    def image_png(self, control: Any = None) -> Optional[bytes]:
+        try:
+            raw = self._call("GET", self._s(f"/element/{control}/screenshot" if control else "/screenshot"))
+            return base64.b64decode(raw or "") or None
+        except Exception:
+            return None
+
+    def close(self) -> None:
+        if self.session:
+            try:
+                if self.app is not None:
+                    self._script("mobile: terminateApp", {"appId": self.app.app_id} if self.platform == "android" else {"bundleId": self.app.app_id})
+            except Exception:
+                pass
+            try:
+                self._call("DELETE", self._s())
+            except Exception:
+                pass
+        self.session = None

package/py/forgeqe_mobile/apps.py

@@ -0,0 +1,84 @@
+"""
+The mobile apps a workflow may start: ``mobile.apps`` in forgeqe.yaml and the active environment's mobile apps, never
+an app named by the workflow itself. Each is a platform and a package (Android) or bundle id (iOS), with an optional
+Android activity and an optional app file or cloud upload to install.
+"""
+from __future__ import annotations
+
+import ntpath
+import posixpath
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional
+
+from forgeqe_desktop.workflow import APP_NAME, WorkflowError
+
+APP_ID = re.compile(r"^[A-Za-z0-9_.-]{1,200}$")
+ACTIVITY = re.compile(r"^[A-Za-z0-9_.$]{1,200}$")
+APP_FILE = re.compile(r"\.(apk|aab|ipa|app|zip)$", re.I)
+# Uploads on device clouds, by their own schemes only: bs://<id> (BrowserStack), lt://<id> (LambdaTest),
+# storage:filename=… (Sauce Labs). Never file:// or any other scheme.
+CLOUD_APP = re.compile(r"^((bs|lt)://[A-Za-z0-9._-]{1,200}|storage:filename=[A-Za-z0-9._-]{1,200})$")
+
+
+@dataclass(frozen=True)
+class MobileAppSpec:
+    name: str
+    platform: str
+    app_id: str
+    activity: Optional[str] = None
+    app: Optional[str] = None
+    # replay's resolve_app checks `path` exists for desktop apps; a mobile app has no local program to check.
+    path: str = ""
+
+    def capabilities(self) -> Dict[str, Any]:
+        """The W3C capabilities that start this app through Appium."""
+        if self.platform == "android":
+            caps: Dict[str, Any] = {"platformName": "Android", "appium:automationName": "UiAutomator2", "appium:appPackage": self.app_id}
+            if self.activity:
+                caps["appium:appActivity"] = self.activity
+        else:
+            caps = {"platformName": "iOS", "appium:automationName": "XCUITest", "appium:bundleId": self.app_id}
+        if self.app:
+            caps["appium:app"] = self.app
+        return caps
+
+
+def _check_app_file(where: str, value: Any) -> Optional[str]:
+    if value is None or value == "":
+        return None
+    if not isinstance(value, str) or any(ord(c) < 32 for c in value):
+        raise WorkflowError(f"{where}.app must be text")
+    v = value.strip()
+    if v.lower().startswith("https://") or CLOUD_APP.match(v):
+        return v
+    if (ntpath.isabs(v) or posixpath.isabs(v)) and APP_FILE.search(v):
+        return v
+    raise WorkflowError(f"{where}.app must be an absolute path to an .apk, .aab, .ipa, .app or .zip, an https URL, or a device cloud upload (bs://…)")
+
+
+def mobile_app_spec(name: str, raw: Any) -> MobileAppSpec:
+    where = f"mobile.apps.{name}"
+    if not isinstance(name, str) or not APP_NAME.match(name):
+        raise WorkflowError(f"{where}: app names are letters, digits and _ . -")
+    if not isinstance(raw, Mapping):
+        raise WorkflowError(f"{where} must be a mapping with platform and app_id")
+    platform = raw.get("platform")
+    if platform not in ("android", "ios"):
+        raise WorkflowError(f"{where}.platform must be android or ios")
+    app_id = raw.get("app_id", raw.get("appId"))
+    if not isinstance(app_id, str) or not APP_ID.match(app_id):
+        raise WorkflowError(f"{where}.app_id must be the app's package (Android) or bundle id (iOS)")
+    activity = raw.get("activity")
+    if activity is not None and (not isinstance(activity, str) or not ACTIVITY.match(activity) or platform != "android"):
+        raise WorkflowError(f"{where}.activity must be an Android activity name such as .MainActivity")
+    return MobileAppSpec(name=name, platform=platform, app_id=app_id, activity=activity or None, app=_check_app_file(where, raw.get("app")))
+
+
+def load_mobile_apps(mobile: Mapping[str, Any]) -> Dict[str, MobileAppSpec]:
+    apps = mobile.get("apps") if isinstance(mobile, Mapping) else None
+    if apps is None:
+        return {}
+    if not isinstance(apps, Mapping):
+        raise WorkflowError("mobile.apps must be a mapping of app name to {platform, app_id}")
+    return {name: mobile_app_spec(name, raw) for name, raw in apps.items()}

package/py/forgeqe_mobile/cli.py

@@ -0,0 +1,70 @@
+"""
+``python -m forgeqe_mobile``: ``serve`` is what ``forgeqe mobile`` runs; ``flow`` prints a mobile workflow as a Maestro
+flow, ``check-flow`` checks a team's Maestro flow against the allowlist, ``doctor`` says whether Appium and Maestro
+answer.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+import urllib.request
+from typing import List, Optional
+
+from forgeqe_desktop.workflow import WorkflowError, load
+
+
+def doctor(appium_url: str, maestro: str) -> dict:
+    out: dict = {"appium_url": appium_url}
+    try:
+        req = urllib.request.Request(appium_url.rstrip("/") + "/status", method="GET")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            value = json.loads(resp.read(100_000) or b"{}").get("value") or {}
+        out["appium"] = True
+        out["appium_version"] = str((value.get("build") or {}).get("version") or "")
+    except Exception as e:
+        out["appium"] = False
+        out["appium_error"] = str(getattr(e, "reason", e))[:200]
+    found = shutil.which(maestro)
+    out["maestro"] = bool(found)
+    if found:
+        out["maestro_path"] = found
+    return out
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="forgeqe_mobile")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("serve", help="one JSON request on stdin, JSON events on stdout (what the forgeqe CLI runs)")
+    f = sub.add_parser("flow", help="a mobile workflow as a Maestro flow")
+    f.add_argument("workflow")
+    f.add_argument("--app-id", required=True)
+    c = sub.add_parser("check-flow", help="check a Maestro flow (and the flows it runs) against the allowlist")
+    c.add_argument("flow")
+    c.add_argument("--root", required=True)
+    d = sub.add_parser("doctor", help="whether the Appium server and maestro answer, as JSON")
+    d.add_argument("--appium-url", default="http://127.0.0.1:4723")
+    d.add_argument("--maestro", default="maestro")
+    args = parser.parse_args(argv)
+    if args.command == "serve":
+        from .service import serve
+
+        return serve()
+    try:
+        if args.command == "flow":
+            from .maestro import to_flow
+
+            flow, _ = to_flow(load(args.workflow), args.app_id)
+            sys.stdout.write(flow)
+            return 0
+        if args.command == "check-flow":
+            from .maestro import check_flow
+
+            print(f"ok: {len(check_flow(args.flow, args.root))} flow files checked")
+            return 0
+        print(json.dumps(doctor(args.appium_url, args.maestro)))
+        return 0
+    except (WorkflowError, ValueError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2