android-driver 0.0.1__py3-none-any.whl

android_driver/run.py

@@ -0,0 +1,292 @@
+"""Run bundles: every artifact from one test attempt, in one directory.
+
+An agent that finds a bug and then cannot show you *why* it believes that has
+done half the work. A run collects the evidence as it goes — a timeline of every
+action with its timing, a screenshot and hierarchy dump at each failure, and the
+logcat slice for exactly that window — and writes a report a human can read
+without replaying anything.
+
+Artifacts are captured even with no run open: they land under
+`runs/failures/<timestamp>/` instead. A failure you have to reproduce in order
+to collect evidence for is a failure you have already half lost.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import adb
+from .config import Config
+from .log import log
+from .session import Session
+
+_SLUG_OK = "abcdefghijklmnopqrstuvwxyz0123456789-_"
+
+
+def _slug(value: str, limit: int = 40) -> str:
+    cleaned = "".join(c if c in _SLUG_OK else "-" for c in value.strip().lower())
+    while "--" in cleaned:
+        cleaned = cleaned.replace("--", "-")
+    return cleaned.strip("-")[:limit] or "run"
+
+
+@dataclass
+class Event:
+    t: float
+    tool: str
+    status: str
+    duration_s: float
+    detail: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "t": round(self.t, 3),
+            "tool": self.tool,
+            "status": self.status,
+            "duration_s": self.duration_s,
+            **({"detail": self.detail} if self.detail else {}),
+        }
+
+
+class Run:
+    """One test attempt and the directory holding its evidence."""
+
+    def __init__(self, root: Path, name: str, note: str = "") -> None:
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        self.name = name
+        self.note = note
+        self.id = f"{stamp}-{_slug(name)}"
+        self.dir = root / self.id
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.started_at = time.time()
+        self.started_mono = time.monotonic()
+        self.events: list[Event] = []
+        self.device: dict[str, str] = {}
+        self.recording: dict[str, Any] | None = None
+        self.finished = False
+
+    # ── recording events ─────────────────────────────────────────────────────
+
+    def event(self, tool: str, status: str, duration_s: float, detail: dict[str, Any] | None = None) -> Event:
+        ev = Event(
+            t=time.monotonic() - self.started_mono,
+            tool=tool,
+            status=status,
+            duration_s=round(duration_s, 3),
+            detail=detail or {},
+        )
+        self.events.append(ev)
+        return ev
+
+    def artifact(self, name: str) -> Path:
+        path = self.dir / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @property
+    def failures(self) -> list[Event]:
+        return [e for e in self.events if e.status != "ok"]
+
+    # ── output ───────────────────────────────────────────────────────────────
+
+    def write_timeline(self) -> Path:
+        payload = {
+            "id": self.id,
+            "name": self.name,
+            "note": self.note,
+            "started_at": self.started_at,
+            "duration_s": round(time.monotonic() - self.started_mono, 2),
+            "device": self.device,
+            "recording": self.recording,
+            "events": [e.to_dict() for e in self.events],
+        }
+        path = self.dir / "timeline.json"
+        path.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")
+        return path
+
+    def write_report(self) -> Path:
+        total = time.monotonic() - self.started_mono
+        failures = self.failures
+        lines = [
+            f"# Run {self.id}",
+            "",
+            f"- **name**: {self.name}",
+            f"- **started**: {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(self.started_at))}",
+            f"- **duration**: {total:.1f}s",
+            f"- **steps**: {len(self.events)} ({len(failures)} failed)",
+        ]
+        if self.note:
+            lines.append(f"- **note**: {self.note}")
+        for key in ("serial", "model", "android_version", "sdk", "screen"):
+            if self.device.get(key):
+                lines.append(f"- **{key}**: {self.device[key]}")
+        if self.recording:
+            lines.append(f"- **recording**: `{self.recording.get('path', '?')}`")
+
+        lines += ["", "## Timeline", "", "| t | step | status | took |", "|---:|---|---|---:|"]
+        for e in self.events:
+            lines.append(f"| {e.t:6.1f}s | `{e.tool}` | {e.status} | {e.duration_s:.2f}s |")
+
+        if failures:
+            lines += ["", "## Failures", ""]
+            for e in failures:
+                lines.append(f"### `{e.tool}` at {e.t:.1f}s")
+                lines.append("")
+                error = e.detail.get("error")
+                if error:
+                    lines += ["```", str(error), "```", ""]
+                for key in ("screenshot", "hierarchy"):
+                    if e.detail.get(key):
+                        lines.append(f"- {key}: `{e.detail[key]}`")
+                lines.append("")
+
+        lines += ["", "## Artifacts", ""]
+        for path in sorted(self.dir.rglob("*")):
+            if path.is_file() and path.name != "report.md":
+                lines.append(f"- `{path.relative_to(self.dir)}`")
+
+        path = self.dir / "report.md"
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        return path
+
+    def write_logcat(self, serial: str, pkg: str | None) -> Path | None:
+        """The log for this run's window. Assumes the buffer was cleared at the start."""
+        try:
+            lines = adb.logcat_dump(serial, lines=20000, buffers="main,crash")
+        except Exception as e:
+            log("run", f"could not capture logcat: {e}")
+            return None
+        path = self.dir / "logcat.txt"
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        if pkg:
+            app_lines = [line for line in lines if pkg in line]
+            if app_lines:
+                (self.dir / "logcat-app.txt").write_text("\n".join(app_lines) + "\n", encoding="utf-8")
+        return path
+
+
+class Runs:
+    """Owns the current run and the fallback artifact directory."""
+
+    def __init__(self, cfg: Config) -> None:
+        self.cfg = cfg
+        self.current: Run | None = None
+
+    @property
+    def root(self) -> Path:
+        return self.cfg.runs_dir
+
+    def start(self, session: Session, name: str, note: str = "", clear_log: bool = True) -> dict[str, Any]:
+        if self.current is not None and not self.current.finished:
+            previous = self.current.id
+            self.end(session)
+            log("run", f"auto-closed the previous run {previous}")
+        run = Run(self.root, name, note)
+        try:
+            run.device = adb.device_info(session.serial)
+        except Exception as e:
+            log("run", f"could not read device info: {e}")
+        if clear_log:
+            try:
+                adb.logcat_clear(session.serial)
+            except Exception as e:
+                log("run", f"could not clear logcat: {e}")
+        self.current = run
+        log("run", f"started {run.id} → {run.dir}")
+        return {"run_id": run.id, "dir": str(run.dir)}
+
+    def end(self, session: Session) -> dict[str, Any]:
+        run = self.current
+        if run is None or run.finished:
+            raise RuntimeError("no run is open — call `run_start` first")
+        pkg = self.cfg.app.package
+        serial = run.device.get("serial") or (session.current_serial or "")
+        if serial:
+            run.write_logcat(serial, pkg)
+        timeline = run.write_timeline()
+        report = run.write_report()
+        run.finished = True
+        self.current = None
+        failures = [e.tool for e in run.failures]
+        log("run", f"finished {run.id} ({len(run.events)} steps, {len(failures)} failed)")
+        return {
+            "run_id": run.id,
+            "dir": str(run.dir),
+            "steps": len(run.events),
+            "failed": failures,
+            "passed": not failures,
+            "report": str(report),
+            "timeline": str(timeline),
+        }
+
+    # ── artifacts ────────────────────────────────────────────────────────────
+
+    def artifact_dir(self, kind: str = "failures") -> Path:
+        if self.current is not None and not self.current.finished:
+            return self.current.dir
+        path = self.root / kind / time.strftime("%Y%m%d-%H%M%S")
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def capture(self, session: Session, tag: str) -> dict[str, str]:
+        """Screenshot + hierarchy for post-hoc triage. Never raises."""
+        out = self.artifact_dir()
+        stamp = f"{tag}-{int(time.time() * 1000) % 100000}"
+        captured: dict[str, str] = {}
+        png = out / f"{stamp}.png"
+        try:
+            session.driver.screenshot(png)
+            captured["screenshot"] = str(png)
+        except Exception as e:
+            log("run", f"screenshot capture failed for {tag}: {e}")
+        xml = out / f"{stamp}.xml"
+        try:
+            xml.write_text(session.driver.dump_hierarchy(), encoding="utf-8")
+            captured["hierarchy"] = str(xml)
+        except Exception as e:
+            log("run", f"hierarchy capture failed for {tag}: {e}")
+        if not captured:
+            # An unreachable device fails both captures; don't leave the empty
+            # directory behind to look like evidence that exists.
+            for path in (png, xml):
+                path.unlink(missing_ok=True)
+            if out != getattr(self.current, "dir", None) and not any(out.iterdir()):
+                out.rmdir()
+        return captured
+
+    def record_event(
+        self, tool: str, status: str, duration_s: float, detail: dict[str, Any] | None = None
+    ) -> None:
+        if self.current is not None and not self.current.finished:
+            self.current.event(tool, status, duration_s, detail)
+
+    def list_runs(self, limit: int = 20) -> list[dict[str, Any]]:
+        if not self.root.is_dir():
+            return []
+        out: list[dict[str, Any]] = []
+        for path in sorted(self.root.iterdir(), reverse=True):
+            timeline = path / "timeline.json"
+            if not timeline.is_file():
+                continue
+            try:
+                data = json.loads(timeline.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            failed = [e["tool"] for e in data.get("events", []) if e.get("status") != "ok"]
+            out.append(
+                {
+                    "run_id": data.get("id", path.name),
+                    "name": data.get("name", ""),
+                    "duration_s": data.get("duration_s"),
+                    "steps": len(data.get("events", [])),
+                    "failed": failed,
+                    "dir": str(path),
+                }
+            )
+            if len(out) >= limit:
+                break
+        return out

android_driver/scan.py

@@ -0,0 +1,155 @@
+"""Selector scanning — what names actually exist in the app under test.
+
+A recipe written against `desc: login_buton` fails at step four with "element not
+found", and the agent then spends three tool calls proving the typo. Scanning the
+project's own sources for the literals it declares turns that into a load-time
+warning, and gives an agent a list of real names to write recipes against in the
+first place.
+
+The default patterns cover the two things Android apps actually label elements
+with — Compose `testTag`/`contentDescription` and View-system `android:id` — plus
+string resources, since visible copy is what `text:` selectors match. Projects
+with their own convention add regexes under `selectors.patterns`.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config
+from .log import log
+
+# Default globs, tried when the config does not name any.
+DEFAULT_SOURCES = (
+    "**/src/**/*.kt",
+    "**/src/**/*.java",
+    "**/src/main/res/layout*/*.xml",
+    "**/src/main/res/values/strings.xml",
+)
+
+# Directories never worth walking — build outputs dwarf the sources.
+SKIP_DIRS = {"build", ".git", ".gradle", ".idea", "node_modules", "venv", ".venv", "__pycache__"}
+
+# kind → regex with one capturing group holding the literal.
+PATTERNS: dict[str, re.Pattern[str]] = {
+    # testTag("x"), testSemanticsTag("x"), fooTestTag = "x"
+    "tag": re.compile(r'[A-Za-z_]*[Tt]est(?:Semantics)?[Tt]ag\b\s*[=(]\s*"([^"\n]+)"'),
+    # contentDescription = "x" / contentDescription("x")
+    "desc": re.compile(r'contentDescription\s*[=(]\s*"([^"\n]+)"'),
+    # android:id="@+id/x" and R.id.x
+    "id": re.compile(r'android:id\s*=\s*"@\+?id/([\w.]+)"'),
+    "id_ref": re.compile(r"\bR\.id\.(\w+)"),
+    # <string name="x">visible copy</string>
+    "text": re.compile(r'<string\s+name="[^"]+"\s*>([^<]{1,80})</string>'),
+}
+
+# Literals that resolve at runtime (`testTag = "demo_${item.name}_button"`) can
+# never match a live element as written, so they are reported separately rather
+# than presented as names a recipe can use.
+TEMPLATE_RE = re.compile(r"\$\{|\$[A-Za-z_]|%[sd]|\{\d*\}")
+
+
+@dataclass
+class Selectors:
+    by_kind: dict[str, set[str]]
+    templates: set[str]
+    files_scanned: int
+
+    @property
+    def all(self) -> set[str]:
+        return {value for values in self.by_kind.values() for value in values}
+
+    def to_dict(self, limit: int | None = None) -> dict[str, list[str]]:
+        out = {kind: sorted(values) for kind, values in sorted(self.by_kind.items()) if values}
+        if limit:
+            out = {kind: values[:limit] for kind, values in out.items()}
+        return out
+
+
+def _iter_files(root: Path, globs: list[str]) -> list[Path]:
+    seen: dict[Path, None] = {}
+    for pattern in globs:
+        for path in root.glob(pattern):
+            if not path.is_file():
+                continue
+            if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
+                continue
+            seen[path] = None
+    return list(seen)
+
+
+def scan(cfg: Config) -> Selectors:
+    """Collect every selector literal the project declares."""
+    spec = cfg.selectors or {}
+    globs = list(spec.get("sources") or DEFAULT_SOURCES)
+    extra = spec.get("patterns") or []
+
+    patterns = dict(PATTERNS)
+    for i, raw in enumerate(extra):
+        try:
+            patterns[f"custom{i + 1}"] = re.compile(raw)
+        except re.error as e:
+            log("scan", f"ignoring selectors.patterns[{i}] {raw!r}: {e}")
+
+    by_kind: dict[str, set[str]] = {kind: set() for kind in patterns}
+    templates: set[str] = set()
+    files = _iter_files(cfg.project_root, globs)
+
+    for path in files:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as e:
+            log("scan", f"could not read {path}: {e}")
+            continue
+        for kind, rx in patterns.items():
+            for match in rx.finditer(text):
+                literal = (match.group(1) if rx.groups else match.group(0)).strip()
+                if not literal:
+                    continue
+                if TEMPLATE_RE.search(literal):
+                    templates.add(literal)
+                else:
+                    by_kind[kind].add(literal)
+
+    # id and id_ref are the same namespace seen from XML and from Kotlin.
+    by_kind["id"] |= by_kind.pop("id_ref", set())
+    log("scan", f"scanned {len(files)} file(s); found {sum(len(v) for v in by_kind.values())} selectors")
+    return Selectors(by_kind=by_kind, templates=templates, files_scanned=len(files))
+
+
+def check_recipes(recipes: dict, known: Selectors) -> list[str]:
+    """Warn about recipe selectors the project's sources do not declare.
+
+    Only `desc` and `id` are checked. `text` selectors match visible copy that may
+    come from a translation, a server response or a formatted string, so absence
+    from the scanned set means nothing — flagging it would produce noise an
+    operator learns to ignore, which is worse than not checking.
+    """
+    if not known.all:
+        return []
+    warnings: list[str] = []
+    tags = known.by_kind.get("tag", set()) | known.by_kind.get("desc", set())
+    ids = known.by_kind.get("id", set())
+    for name, recipe in recipes.items():
+        for index, step in enumerate(recipe.steps, start=1):
+            for key, pool, label in (("desc", tags, "testTag/contentDescription"), ("id", ids, "id")):
+                value = step.args.get(key) if isinstance(step.args, dict) else None
+                if not isinstance(value, str) or "{{" in value or not pool:
+                    continue
+                if value not in pool:
+                    near = _closest(value, pool)
+                    hint = f" Did you mean {near!r}?" if near else ""
+                    warnings.append(
+                        f"{name} step {index} (`{step.verb}`) uses {key}={value!r}, "
+                        f"which is not among the project's {label} literals.{hint}"
+                    )
+    return warnings
+
+
+def _closest(value: str, pool: set[str]) -> str | None:
+    import difflib
+
+    matches = difflib.get_close_matches(value, pool, n=1, cutoff=0.75)
+    return matches[0] if matches else None