mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/testkit/recent.py

@@ -0,0 +1,166 @@
+"""The suites `mobster test` ran on this Mac, newest first, for the Mac app's Test results page."""
+
+import json
+import re
+import threading
+from pathlib import Path
+
+from ..paths import dev_data_dir, write_text_atomic
+
+INDEX = "test-results.json"
+KEEP = 20
+STEPS = 60
+EXPECTATIONS = 20
+FRAME = re.compile(r"^frames/[0-9A-Za-z._-]{1,80}\.(?:jpg|jpeg|png)$")
+SUITE_ID = re.compile(r"^[0-9]{8}-[0-9]{6}-[0-9a-f]{4}$")
+RUN_ID = re.compile(r"^[0-9]{8}-[0-9]{6}-[0-9a-f]{4}$")
+_lock = threading.Lock()
+
+
+def _index(folder=None):
+    return Path(folder or dev_data_dir()) / INDEX
+
+
+def _read(path):
+    try:
+        value = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return value
+
+
+def remember(doc, folder, root, *, data_dir=None):
+    # Never raises: the page is a convenience, the reports are the record.
+    try:
+        folder = Path(folder).resolve()
+        entry = {"suite": doc.get("suite"), "folder": str(folder), "root": str(Path(root).resolve()),
+                 "startedAt": doc.get("startedAt"), "exitCode": doc.get("exitCode")}
+        with _lock:
+            path = _index(data_dir)
+            known = _read(path)
+            known = [item for item in known if isinstance(item, dict) and item.get("folder") != entry["folder"]] \
+                if isinstance(known, list) else []
+            write_text_atomic(path, json.dumps([entry] + known[:KEEP - 1], indent=1) + "\n")
+    except Exception:
+        pass
+
+
+def _run(run_dir):
+    """What the run that didn't pass left in its result.json: its steps (index, text, at_ms), each expectation with
+    whether it held and what the screen showed instead (ICP-3: "1 of 5 expectations failed" named none), and the frame
+    the verdict was read from, as {run, path} under .mobster/runs (GET /api/projects/{id}/frame serves it). Empty when
+    the file can't be read."""
+    empty = {"steps": [], "expectations": [], "frame": None}
+    if not run_dir or not RUN_ID.match(Path(run_dir).name):
+        return empty
+    result = _read(Path(run_dir) / "result.json")
+    if not isinstance(result, dict):
+        return empty
+    steps = []
+    for step in result.get("steps") if isinstance(result.get("steps"), list) else ():
+        if isinstance(step, dict) and isinstance(step.get("index"), int):
+            steps.append({"index": step["index"], "text": str(step.get("text") or step.get("op") or "")[:300],
+                          "atMs": step.get("at_ms") if isinstance(step.get("at_ms"), (int, float)) else None})
+    expectations, frame = [], None
+    for item in result.get("assertions") if isinstance(result.get("assertions"), list) else ():
+        if not isinstance(item, dict) or not isinstance(item.get("ok"), bool):
+            continue
+        name = (item.get("assertion") or {}).get("name") if isinstance(item.get("assertion"), dict) else None
+        observed = None if item["ok"] else str(item.get("observed") or "")[:300]
+        expectations.append({"text": str(item.get("text") or "")[:200], "name": str(name)[:120] if name else None,
+                             "ok": item["ok"], "observed": observed})
+        shot = item.get("frame")
+        if isinstance(shot, str) and FRAME.match(shot) and (frame is None or not item["ok"]):
+            frame = {"run": Path(run_dir).name, "path": shot}
+    return {"steps": steps[:STEPS], "expectations": expectations[:EXPECTATIONS], "frame": frame}
+
+
+def _suite(entry):
+    folder = Path(str(entry.get("folder") or ""))
+    if (not SUITE_ID.match(folder.name) or folder.parent.name != "test-results"
+            or folder.parent.parent.name != ".mobster"):
+        return None
+    doc = _read(folder / "results.json")
+    if not isinstance(doc, dict) or doc.get("schema") != "mobster.test/1":
+        return None
+    unpassed = []
+    checks = [check for check in doc.get("checks") or () if isinstance(check, dict)]
+    for check in checks:
+        for result in check.get("results") or ():
+            if not isinstance(result, dict) or (result.get("status") == "passed" and not result.get("flaky")):
+                continue
+            runs = [run for run in result.get("runs") or () if isinstance(run, dict)]
+            failing = next((run for run in reversed(runs) if run.get("verdict") != "passed"), runs[-1] if runs else {})
+            unpassed.append({"check": check.get("name"), "file": check.get("file"), "device": result.get("device"),
+                             "status": result.get("status"), "flaky": bool(result.get("flaky")),
+                             "quarantined": bool(check.get("quarantined")),
+                             "reason": result["reason"] if isinstance(result.get("reason"), dict) else None,
+                             "evidence": result.get("evidence"), **_run(failing.get("runDir")),
+                             "video": bool(result.get("video"))})
+    # The devices the suite ran on, so the page's row says what ran where (DR-74), not only the suite's id.
+    listed = [str(d.get("name") or d.get("key")) for d in doc.get("devices") or () if isinstance(d, dict)
+              and (d.get("name") or d.get("key"))]
+    seen = [r.get("device") for c in checks for r in c.get("results") or ()
+            if isinstance(r, dict) and isinstance(r.get("device"), str)]
+    devices = list(dict.fromkeys(listed or seen))[:8]
+    return {"suite": doc.get("suite"), "devices": devices, "checks": len(checks),
+            "project": Path(str(entry.get("root") or folder.parent.parent.parent)).name,
+            "folder": str(folder), "startedAt": doc.get("startedAt"), "durationMs": doc.get("durationMs"),
+            "exitCode": doc.get("exitCode"), "summary": doc.get("summary") or {}, "unpassed": unpassed,
+            "git": _git(doc.get("git"))}
+
+
+def _git(value):
+    """results.json's git, as it was written; None for a suite from before it was, or one outside git."""
+    if not isinstance(value, dict):
+        return None
+    out = {key: value[key] for key in ("branch", "head") if isinstance(value.get(key), str)}
+    return out or None
+
+
+def known_roots(*, data_dir=None):
+    """The projects `mobster test` ran in on this Mac that still have a `.mobster/`, newest first."""
+    known = _read(_index(data_dir))
+    roots = []
+    for entry in known if isinstance(known, list) else ():
+        root = Path(str(entry.get("root") or "")) if isinstance(entry, dict) else None
+        if root and root.is_absolute() and (root / ".mobster").is_dir() and root not in roots:
+            roots.append(root)
+    return roots
+
+
+def recent(limit=5, *, data_dir=None, root=None):
+    """The last ``limit`` suites that can still be read, newest first; with ``root``, only the suites run in that
+    project folder."""
+    known = _read(_index(data_dir))
+    wanted = str(Path(root).resolve()) if root is not None else None
+    out = []
+    for entry in known if isinstance(known, list) else ():
+        if len(out) >= limit:
+            break
+        if wanted is not None and (not isinstance(entry, dict) or entry.get("root") != wanted):
+            continue
+        suite = _suite(entry) if isinstance(entry, dict) else None
+        if suite is not None:
+            out.append(suite)
+    return out
+
+
+def by_root(*, data_dir=None):
+    known = _read(_index(data_dir))
+    out = {}
+    for entry in known if isinstance(known, list) else ():
+        root = entry.get("root") if isinstance(entry, dict) else None
+        if not isinstance(root, str) or root in out:
+            continue
+        folder = Path(str(entry.get("folder") or ""))
+        if not SUITE_ID.match(folder.name) or folder.parent.name != "test-results":
+            continue
+        doc = _read(folder / "results.json")
+        if isinstance(doc, dict) and doc.get("schema") == "mobster.test/1":
+            out[root] = {"suite": doc.get("suite"), "startedAt": doc.get("startedAt"), "exitCode": doc.get("exitCode"),
+                         "summary": doc.get("summary") if isinstance(doc.get("summary"), dict) else {}}
+    return out
+
+
+__all__ = ["remember", "recent", "known_roots", "by_root", "INDEX"]

mobile_agent/testkit/recipes.py

@@ -0,0 +1,146 @@
+"""Built-in check recipes: `mobster test add <recipe>` writes one as a normal check in .mobster/checks."""
+
+import re
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+__all__ = ["Param", "Recipe", "RecipeError", "BUILTIN", "get", "names", "build", "SHARED"]
+
+PLACEHOLDER = re.compile(r"\$\{([a-z][a-z0-9_]*)\}")
+SHARED = ("bundle", "app", "name")
+
+
+class RecipeError(Exception):
+    """A usage problem with a recipe: an unknown recipe or param, or a missing required one."""
+
+
+@dataclass(frozen=True)
+class Param:
+    name: str
+    help: str
+    required: bool = False
+    default: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Recipe:
+    name: str
+    summary: str                       # one line, lowercase start, no final period
+    template: dict
+    params: tuple = ()
+    finish: Optional[Callable] = None
+    notes: str = ""                    # printed after the file is written: what to do next
+
+
+_DROP = object()
+
+
+def _fill(value, params):
+    """``value`` with every ${param} replaced; _DROP when it names an unset param or empties."""
+    if isinstance(value, str):
+        missing = False
+
+        def sub(match):
+            nonlocal missing
+            got = params.get(match.group(1))
+            if got is None:
+                missing = True
+                return ""
+            return got
+        text = PLACEHOLDER.sub(sub, value)
+        return _DROP if missing else text
+    if isinstance(value, list):
+        items = [_fill(item, params) for item in value]
+        items = [item for item in items if item is not _DROP]
+        return items if items or not value else _DROP
+    if isinstance(value, dict):
+        out = {}
+        for key, item in value.items():
+            filled = _fill(item, params)
+            if filled is not _DROP:
+                out[key] = filled
+        return out if out or not value else _DROP
+    return value
+
+
+def get(name):
+    for recipe in BUILTIN:
+        if recipe.name == name:
+            return recipe
+    raise RecipeError(f"there is no recipe {name!r}; the recipes are {', '.join(names())} "
+                      f"(mobster test add --list)")
+
+
+def names():
+    return [recipe.name for recipe in BUILTIN]
+
+
+def build(name, given):
+    """(recipe, check data) for recipe ``name`` and the params in ``given`` (a dict of text). Raises RecipeError."""
+    recipe = get(name)
+    known = {param.name for param in recipe.params} | set(SHARED)
+    for key in given:
+        if key not in known:
+            raise RecipeError(f"recipe {recipe.name} has no param {key!r}; it takes "
+                              f"{', '.join(sorted(known))}")
+    params = {param.name: param.default for param in recipe.params}
+    params.update({key: value for key, value in given.items() if value not in (None, "")})
+    for param in recipe.params:
+        if param.required and params.get(param.name) is None:
+            raise RecipeError(f"recipe {recipe.name} needs {param.name}: {param.help} "
+                              f"(--set {param.name}=VALUE)")
+    data = _fill(recipe.template, params)
+    if recipe.finish is not None:
+        data = recipe.finish(params, data)
+    if params.get("name"):
+        data["name"] = params["name"]
+    app = data.setdefault("app", {})
+    if params.get("bundle"):
+        app["bundle"] = params["bundle"]
+    if params.get("app"):
+        app["path"] = params["app"]
+    if not app.get("bundle") and not app.get("path"):
+        raise RecipeError(f"recipe {recipe.name} needs the app: --bundle com.example.app")
+    from ..verify.checks import CheckError, check_from_dict
+    try:
+        check_from_dict(data)
+    except CheckError as error:
+        raise RecipeError(f"recipe {recipe.name} wrote a check that doesn't load ({error}); "
+                          "fix the params") from None
+    return recipe, data
+
+
+def _numbers(*keys):
+    """A finish that turns the text of these keys into numbers (a template can only hold text)."""
+    def finish(params, data):
+        for item in data.get("expect", ()):
+            for key in keys:
+                if isinstance(item.get(key), str) and item[key].isdigit():
+                    item[key] = int(item[key])
+        return data
+    return finish
+
+
+BUILTIN = (
+    Recipe(
+        name="smoke",
+        summary="the app launches and shows the text you name",
+        template={"version": 1, "name": "The app launches and shows ${text}", "tags": ["smoke"], "app": {},
+                  "launch": {"url": "${url}"}, "expect": [{"text": "${text}"}]},
+        params=(Param("text", "text your first screen shows", required=True),
+                Param("url", "a link to open after launch, such as yourapp://home")),
+        notes="A launch-only check needs no key."),
+    Recipe(
+        name="paywall",
+        summary="the paywall shows its plans and a restore button",
+        template={"version": 1, "name": "The paywall shows ${plans} plans", "tags": ["smoke", "paywall"],
+                  "app": {}, "launch": {"url": "${url}", "args": ["${launch_arg}"]},
+                  "expect": [{"count": {"id": "/^plan_/"}, "equals": "${plans}"},
+                             {"visible": {"label": "${restore}", "role": "button"}}]},
+        params=(Param("url", "the link to your paywall, such as yourapp://paywall", required=True),
+                Param("plans", "how many plans the paywall shows", default="3"),
+                Param("restore", "the restore button's label", default="Restore Purchases"),
+                Param("launch_arg", "a launch argument that makes your app show its local product list")),
+        finish=_numbers("equals"),
+        notes="Mobster checks everything up to the purchase. Edit expect to add each plan's price."),
+)

mobile_agent/testkit/record.py

@@ -0,0 +1,204 @@
+"""A finished Mobster task as a check file; every string goes through secret_filter.redact."""
+
+import json
+import re
+import sqlite3
+import time
+from pathlib import Path
+
+from ..verify.checks import LIMITS
+
+RUN_ID = re.compile(r"[a-f0-9]{12}")
+STEP_LIMIT, STEP_TEXT_LIMIT, EXPECT_LIMIT, QUOTE_LIMIT = 20, 500, 8, 120
+ANY_APP = "any"
+FAST = "fast"         # a run on Quick mode, before 13 Oct 2026
+BREADCRUMB = " › "    # how a Quick mode proof joined its screen path
+HEADER = ("# A Mobster check, recorded from the task “{goal}” on {date}.\n"
+          "# Run it with: mobster test {path}\n")
+NO_EXPECT = ("# The task proved nothing Mobster can check, so add expect: what must be true at the end, such as\n"
+             "# - text: Choose your plan\n")
+MASKED = "# A step types text Mobster masked (••••••): replace it with the text to type, or a test account's.\n"
+IMPERATIVE = (("Pressed and held ", "Press and hold "), ("Pressed Return", "Press Return"),
+              ("Opened ", "Open "), ("Tapped ", "Tap "), ("Typed ", "Type "), ("Entered ", "Enter "),
+              ("Cleared ", "Clear "), ("Searched for ", "Search for "), ("Rewrote ", "Rewrite "),
+              ("Wrote ", "Write "), ("Scrolled ", "Scroll "), ("Swiped ", "Swipe "),
+              ("Closed a pop-up", "Close the pop-up"), ("Went to ", "Go to "), ("Sent ", "Send "),
+              ("Chose ", "Choose "), ("Turned ", "Turn "), ("Selected ", "Select "))
+
+
+class RecordError(Exception):
+    """Why a task can't become a check: one sentence, an HTTP status and a code."""
+
+    def __init__(self, message, status=400, code="cant_record"):
+        super().__init__(message)
+        self.message, self.status, self.code = message, status, code
+
+
+def imperative(text):
+    text = " ".join(str(text or "").split())
+    for done, do in IMPERATIVE:
+        if text.startswith(done):
+            text = do + text[len(done):]
+            break
+    return text.replace(" and pressed Return", " and press Return")
+
+
+def _redact(text):
+    from ..secret_filter import redact
+    return redact(str(text or ""))
+
+
+def _app(record):
+    """(bundle, name) the check runs: the task's start app, else the first app it opened."""
+    app = record.get("app") if isinstance(record.get("app"), dict) else {}
+    start = record.get("appId") or app.get("id")
+    bundle = app.get("bundleId") or (start if isinstance(start, str) and "." in start else None)
+    if bundle and start != ANY_APP:
+        return bundle, app.get("name") or record.get("appName")
+    for event in record.get("events") or ():
+        if event.get("event") == "frontier_action" and event.get("operation") == "LAUNCH_APP" \
+                and isinstance(event.get("target_label"), str) and "." in event["target_label"]:
+            return event["target_label"].strip(), None
+    return None, None
+
+
+def _steps(record, app_name):
+    texts = []
+    for event in record.get("events") or ():
+        if event.get("event") != "step" or not isinstance(event.get("text"), str):
+            continue
+        text = _redact(imperative(event["text"]))[:STEP_TEXT_LIMIT]
+        if text.startswith("Read ") and ":" in text:
+            text = text.split(":", 1)[0]  # the value it read is an expectation, not a step
+        if text and (not texts or texts[-1] != text):
+            texts.append(text)
+    if texts and app_name and texts[0].casefold() == f"open {app_name}".casefold():
+        texts = texts[1:]  # the check launches its app itself
+    goal = _redact(" ".join(str(record.get("goal") or "").split()))[:STEP_TEXT_LIMIT]
+    if len(texts) > STEP_LIMIT or (not texts and goal):
+        return [goal] if goal else []
+    return texts
+
+
+def _expect(record):
+    from ..agent_hooks import MASK
+    summary = record.get("summary") if isinstance(record.get("summary"), dict) else {}
+    proof = [item for item in summary.get("proof") or () if isinstance(item, dict)]
+    if not proof:
+        proof = [{"quote": e.get("quote"), "screen": e.get("screen")} for e in record.get("events") or ()
+                 if e.get("event") == "receipt"]
+    out, seen, screen = [], set(), None
+    for item in proof:
+        quote = " ".join(str(item.get("quote") or "").split())
+        if item.get("screen"):
+            screen = " ".join(str(item["screen"]).split())
+        if not quote or MASK in quote or quote.startswith("/"):
+            continue
+        quote = _redact(quote)
+        if MASK in quote:
+            continue
+        if len(quote) > QUOTE_LIMIT:
+            quote = quote[:QUOTE_LIMIT].rsplit(" ", 1)[0] or quote[:QUOTE_LIMIT]
+        if quote.casefold() in seen:
+            continue
+        seen.add(quote.casefold())
+        out.append({"text": quote})
+        if len(out) >= EXPECT_LIMIT:
+            break
+    # Quick's proof names a breadcrumb of taps ("General › About") that no navigation bar shows: no bar to end on.
+    if screen and record.get("engine") != FAST and BREADCRUMB not in screen and MASK not in screen \
+            and not screen.startswith("/"):
+        out.append({"visible": {"role": "navbar", "id": _redact(screen)[:200]},
+                    "name": f"Ends on {screen}"[:LIMITS["name"]]})
+    return out
+
+
+def check_data(record, *, name=None):
+    """The check file's shape (verify.checks) for a run ``record`` (Run.public() or a journal row with its events)."""
+    if record.get("finishedAt") is None or record.get("status") in ("queued", "running"):
+        raise RecordError("The task is still running. Record it once it ends.", 409, "run_active")
+    bundle, app_name = _app(record)
+    if not bundle:
+        raise RecordError("The task didn't open an app, so there's nothing to check.", 400, "no_app")
+    steps = _steps(record, app_name)
+    title = " ".join(str(name or "").split()) or " ".join(str(record.get("goal") or "").split()) or "Recorded check"
+    title = _redact(title)
+    data = {"version": 1, "name": title[:LIMITS["name"] - 1] + "…" if len(title) > LIMITS["name"] else title,
+            "app": {"bundle": bundle}}
+    if steps:
+        data["steps"] = steps
+    data["expect"] = _expect(record)
+    return data
+
+
+def check_yaml(record, *, name=None, path=".mobster/checks/<name>.yaml"):
+    """The check file's text for ``record``: a header, then YAML that verify.checks.load_check reads back."""
+    import yaml
+
+    from ..agent_hooks import MASK
+    from ..verify.checks import check_from_dict
+    data = check_data(record, name=name)
+    check_from_dict(data)  # the same validation a check file gets: never hand out one that can't load
+    created = record.get("finishedAt") or record.get("createdAt")
+    date = time.strftime("%-d %b %Y", time.localtime(created / 1000)) if isinstance(created, (int, float)) \
+        else time.strftime("%-d %b %Y")
+    goal = " ".join(_redact(record.get("goal") or "the task").split())
+    text = HEADER.format(goal=goal[:80] + ("…" if len(goal) > 80 else ""), date=date, path=path)
+    if any(MASK in step for step in data.get("steps") or ()):
+        text += MASKED
+    if not data["expect"]:
+        text += NO_EXPECT
+    return text + yaml.safe_dump(data, sort_keys=False, allow_unicode=True, default_flow_style=False, width=100)
+
+
+def journal_paths():
+    """Where the Mac app and `mobster serve` keep their task journals, in the order they are tried."""
+    from ..paths import PACKAGE, source_checkout, user_data_dir
+    paths = [user_data_dir() / "state" / "mobster.sqlite3"]
+    if source_checkout():
+        paths.append(PACKAGE / ".state" / "mobster.sqlite3")
+    return paths
+
+
+def find_run(run_id, paths=None):
+    """The run ``run_id`` from the first journal that has it (metadata plus ``events``). Raises RecordError."""
+    run_id = str(run_id or "").strip().lower()
+    if not RUN_ID.fullmatch(run_id):
+        raise RecordError("A task's id is 12 characters of 0-9 and a-f, as the Mobster app and "
+                          "`mobster history` show it.", 400, "bad_run_id")
+    searched = []
+    for path in paths if paths is not None else journal_paths():
+        path = Path(path)
+        if not path.is_file():
+            continue
+        searched.append(path)
+        record = _read(path, run_id)
+        if record is not None:
+            return record
+    if not searched:
+        raise RecordError("Mobster found no task history on this Mac. Run a task in the Mobster app or with "
+                          "`mobster serve` first.", 404, "no_history")
+    raise RecordError(f"No task {run_id} in Mobster's history. The Mobster app keeps the last 100 tasks.", 404,
+                      "run_not_found")
+
+
+def _read(path, run_id):
+    # Read-only, with no lock or write, so it works while the app has the journal open.
+    for uri in (f"file:{path}?mode=ro", f"file:{path}?immutable=1"):
+        try:
+            connection = sqlite3.connect(uri, uri=True, timeout=3)
+        except sqlite3.Error:
+            continue
+        try:
+            row = connection.execute("SELECT data FROM runs WHERE id=?", (run_id,)).fetchone()
+            if row is None:
+                return None
+            record = json.loads(row[0])
+            record["events"] = [json.loads(item[0]) for item in connection.execute(
+                "SELECT data FROM events WHERE run_id=? ORDER BY seq", (run_id,))]
+            return record
+        except (sqlite3.Error, ValueError, TypeError):
+            continue
+        finally:
+            connection.close()
+    raise RecordError(f"Mobster couldn't read its task history at {path}.", 503, "journal_unreadable")