mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/runs.py

@@ -0,0 +1,57 @@
+"""The run folder: ``.mobster/runs/<run id>/`` and the ``.gitignore`` that keeps it out of git."""
+
+import os
+import secrets
+import time
+from pathlib import Path
+
+
+def new_run_id():
+    """YYYYMMDD-HHMMSS-xxxx: the local time plus 4 random hex characters."""
+    return time.strftime("%Y%m%d-%H%M%S") + "-" + secrets.token_hex(2)
+
+
+# Runs and test results show whatever was on the screen, and the cache is per machine.
+GITIGNORE = "runs/\nbuild/\ncache/\ntest-results/\n"
+OLD_GITIGNORES = ("runs/\nbuild/\n",)
+
+
+def ensure_gitignore(runs_dir):
+    # Never over the user's own file; one an earlier Mobster wrote, word for word, is brought up to date.
+    runs_dir = Path(runs_dir)
+    if runs_dir.parent.name != ".mobster":
+        return
+    folder = runs_dir.parent
+    ignore = folder / ".gitignore"
+    if ignore.exists():
+        try:
+            if ignore.is_file() and not ignore.is_symlink() and ignore.read_text(encoding="utf-8") in OLD_GITIGNORES:
+                temporary = folder / ".gitignore.tmp"
+                temporary.write_text(GITIGNORE, encoding="utf-8")
+                os.replace(temporary, ignore)
+        except (OSError, UnicodeDecodeError):
+            pass  # the user's file, or one we can't read: left as it is
+        return
+    try:
+        folder.mkdir(parents=True, exist_ok=True)
+        with open(ignore, "x", encoding="utf-8") as handle:
+            handle.write(GITIGNORE)
+    except FileExistsError:
+        pass  # another run wrote it first
+
+
+def make_run_dir(runs_dir):
+    # 0700, as the task journal's are: a run's frames and steps hold what was on the screen.
+    runs_dir = Path(runs_dir)
+    ensure_gitignore(runs_dir)
+    runs_dir.mkdir(parents=True, exist_ok=True)
+    while True:
+        run_id = new_run_id()
+        run_dir = runs_dir / run_id
+        try:
+            run_dir.mkdir(mode=0o700)
+        except FileExistsError:
+            continue
+        os.chmod(run_dir, 0o700)  # whatever the umask
+        (run_dir / "frames").mkdir(mode=0o700)
+        return run_id, run_dir

mobile_agent/verify/screen_coverage.py

@@ -0,0 +1,181 @@
+"""Observe required intermediate accessibility screens and retain incomplete-coverage evidence."""
+
+import threading
+from contextlib import contextmanager
+
+from .assertions import evaluate_on
+
+
+class ScreenCoverage:
+    def _incomplete_screen(self, reason):
+        with self._screen_coverage_lock:
+            if self._screen_result_sealed:
+                return
+            if self._screen_coverage_issue is None:
+                self._screen_coverage_issue = reason
+        self.log(f"screen coverage incomplete: {reason}")
+
+    @contextmanager
+    def _screen_frame(self, label):
+        tracked = label in ("launch", "step")
+        if tracked:
+            with self._screen_coverage_lock:
+                admitted = not self._screen_frames_sealed
+                if admitted:
+                    self._screen_frames_pending += 1
+        else:
+            admitted = True
+        try:
+            yield admitted
+        finally:
+            if tracked and admitted:
+                with self._screen_coverage_lock:
+                    self._screen_frames_pending -= 1
+
+    def _seal_screen_frames(self):
+        with self._screen_coverage_lock:
+            self._screen_frames_sealed = True
+            self._verdict_thread = threading.get_ident()
+            if self._screen_frames_pending and self._screen_coverage_issue is None:
+                self._screen_coverage_issue = "An intermediate screen observation was in flight at the verdict"
+
+    def _reserve_source_read(self):
+        """Admit a source request before it starts, including reads nested inside driver.observe."""
+        with self._screen_coverage_lock:
+            if self._screen_result_sealed:
+                return None
+            if self._screen_frames_sealed and threading.get_ident() != self._verdict_thread:
+                reason = "A screen read began after the final verdict started"
+                if self._screen_coverage_issue is None:
+                    self._screen_coverage_issue = reason
+                rejected = True
+            else:
+                self._screen_frames_pending += 1
+                rejected = False
+        if rejected:
+            self.log(f"screen coverage incomplete: {reason}")
+            return None
+        released = False
+
+        def release():
+            nonlocal released
+            with self._screen_coverage_lock:
+                if not released:
+                    released = True
+                    self._screen_frames_pending -= 1
+
+        return release
+
+    def _late_screen_frame(self, label, path):
+        with self._screen_coverage_lock:
+            late = label in ("launch", "step") and self._screen_frames_sealed
+        if late:
+            try:
+                path.unlink(missing_ok=True)
+            except OSError as error:
+                self.log(f"late screen frame could not be removed: {type(error).__name__}")
+        return late
+
+    def reserve_step_frame(self):
+        """Count a keyless step before its capture thread is scheduled; return its once-only release."""
+        with self._screen_coverage_lock:
+            if self._screen_frames_sealed:
+                return None
+            self._screen_frames_pending += 1
+        released = False
+
+        def release():
+            nonlocal released
+            with self._screen_coverage_lock:
+                if not released:
+                    released = True
+                    self._screen_frames_pending -= 1
+
+        return release
+
+    def _check_pending_screens(self):
+        with self._screen_coverage_lock:
+            pending = self._screen_frames_pending
+        if pending:
+            self._incomplete_screen("An intermediate screen capture was still in flight at the verdict")
+
+    def _observe_screen(self, frame, tree=None):
+        """Use one AX read for every requested per-screen check, with or without an image."""
+        if not (self.check.throughout or self.check.somewhere or self._a11y or self._l10n):
+            return
+        try:
+            tree = tree or self.read_tree()
+        except Exception as error:
+            self.log(f"screen observation skipped: {type(error).__name__}")
+            self._incomplete_screen("An accessibility screen could not be read or evaluated")
+            return
+        with self._screen_coverage_lock:
+            if self._screen_result_sealed or (self._screen_frames_sealed
+                                              and threading.get_ident() != self._verdict_thread):
+                return
+            try:
+                self._sweep(frame, tree)
+                self._audit_screen(frame, tree)
+            except Exception as error:
+                self.log(f"screen observation skipped: {type(error).__name__}")
+                self._incomplete_screen("An accessibility screen could not be read or evaluated")
+
+    def _finalize_screen_coverage(self):
+        """Freeze the reported marker with collector writes and pending reads under one short lock."""
+        with self._screen_coverage_lock:
+            if self._screen_coverage_final is not None:
+                return dict(self._screen_coverage_final)
+            if self._screen_frames_pending and self._screen_coverage_issue is None:
+                self._screen_coverage_issue = "A screen observation was still in flight at the verdict"
+            self._screen_result_sealed = True
+            self._screen_coverage_final = {
+                "complete": self._screen_verdict_audited and self._screen_coverage_issue is None
+                            and (self._a11y is None or self._a11y.screens > 0),
+                "a11yScreens": self._a11y.screens if self._a11y is not None else 0,
+            }
+            return dict(self._screen_coverage_final)
+
+    def _audit_screen(self, frame, tree):
+        """Add the already-read screen to the accessibility audit."""
+        collectors = [item for item in (self._a11y, self._l10n, self._ax_device) if item is not None]
+        for collector in collectors:
+            if collector.add(tree, frame) is False:
+                self._incomplete_screen("A screen audit reached its 60-screen limit")
+
+    def _sweep(self, frame, tree):
+        check = self.check
+        if not (check.throughout or check.somewhere):
+            return
+        frame = self._relative(frame)
+        fingerprint = tree.audit_fingerprint()
+        for assertion, result in zip(check.throughout, evaluate_on(check.throughout, tree)):
+            text = assertion.name or result.text
+            if result.ok:
+                continue
+            prior = self._unframed_findings.get((fingerprint, text)) if frame else None
+            if prior is not None:
+                prior["frame"] = prior["evidence"] = frame
+                del self._unframed_findings[(fingerprint, text)]
+            elif not any(item["id"] == text and item["frame"] == frame for item in self.findings):
+                finding = {"id": text, "guideline": None, "level": "fail", "frame": frame,
+                           "message": f"{text}: {result.observed}",
+                           "evidence": frame or "an observed accessibility screen"}
+                self.findings.append(finding)
+                if frame is None:
+                    self._unframed_findings[(fingerprint, text)] = finding
+        for index, result in enumerate(evaluate_on(check.somewhere, tree)):
+            if result.ok:
+                self._held_somewhere.add(index)
+
+    def _missing_somewhere(self):
+        """A finding for each ``somewhere`` assertion no screen held."""
+        # The run may not have reached that screen, so a person looks (needs_review) rather than the check failing.
+        out = []
+        for index, assertion in enumerate(self.check.somewhere):
+            if index not in self._held_somewhere:
+                text = assertion.name or assertion.render()
+                out.append({"id": text, "guideline": None, "level": "review", "frame": None,
+                            "message": f"{text}: no screen the run visited showed it. Open the screens in the "
+                                       "report; if the app has it, add a step that goes there.",
+                            "evidence": f"{len(self.frames)} frames in the run"})
+        return out

mobile_agent/verify/smart.py

@@ -0,0 +1,106 @@
+import os
+import re
+
+NO_KEY_FIX = ("Set OPENAI_API_KEY or ANTHROPIC_API_KEY for Smart, or let your coding agent drive through "
+              "`mobster mcp`.")
+
+
+def no_smart_key(env=None):
+    """(why, fix) when Smart has no key for its model."""
+    from .. import engines
+    env = os.environ if env is None else env
+    model = engines.smart_model(env)
+    from ..ai_plans import providers
+    routed = providers.get(engines.model_provider(model))
+    if routed is not None:
+        return (f"{routed.name} has no key or sign-in here", f"Run `mobster login {routed.id}`, or `mobster login` "
+                "for an API key.")
+    if (env.get("MOBSTER_SMART_MODEL") or "").strip() != model:
+        return "no OpenAI or Anthropic key is set", NO_KEY_FIX
+    variable = "ANTHROPIC_API_KEY" if engines.model_provider(model) == "anthropic" else "OPENAI_API_KEY"
+    return (f"MOBSTER_SMART_MODEL is {model}, which needs {variable}, and it isn't set",
+            f"Set {variable} for Smart on {model}, or let your coding agent drive through `mobster mcp`.")
+
+
+# Acts that name no commit: none at all, the replay's "act" for a step it couldn't read, and contract_screen's "none".
+UNCLASSIFIED_ACTS = frozenset({"", "act", "none"})
+
+
+def approve_on_simulator(request):
+    """Smart's approver on a simulator: the app under test may buy, send, post and delete, because money and people
+    don't exist there. A commit the frontier could not classify is refused. The simulator's dialogs, including the
+    purchase sheet, answer to the check's ``dialogs``."""
+    act = request.get("act") if isinstance(request, dict) else None
+    if not isinstance(act, str) or act.strip().casefold() in UNCLASSIFIED_ACTS:
+        return "denied"
+    return "approved"
+
+
+def deny_commits(request):
+    """Smart's approver in a check on a real device (a USB iPhone, a WDA address): every declared commit is refused."""
+    # The phone is someone's own: a send, delete, post or purchase there is real, and a check never asks first.
+    return "denied"
+
+
+def is_real_device(manager):
+    """Whether ``manager`` drives someone's phone. Fails closed: only ``real_device = False`` is a simulator."""
+    return getattr(manager, "real_device", None) is not False
+
+
+def check_approver(manager):
+    return deny_commits if is_real_device(manager) else approve_on_simulator
+
+
+# System view services an app presents over itself (a share sheet, Sign in with Apple, a purchase sheet): part of
+# the app under test, not another app. SpringBoard (alerts, the Home Screen) the frontier never stops for.
+VIEW_SERVICE = re.compile(r"com\.apple\.[A-Za-z0-9.]*(?:ViewService|UIService)")
+LEFT_APP = ("On your iPhone a check stays in {app}, and Smart opened {other}, so the check stopped there. Nothing "
+            "was read from {other} for the report.")
+LEFT_APP_FIX = "Keep the check's steps inside the app, or run it on a simulator with --sim."
+
+
+class StayInApp:
+    """The phone guard for a Smart check on a real device: only the app under test, so no step reads their data."""
+
+    def __init__(self, bundle, inner=None):
+        self.bundle, self.inner, self.left = bundle, inner, None
+
+    def check(self, driver, *, cause):
+        return self.inner.check(driver, cause=cause) if self.inner is not None else None
+
+    def attached(self):
+        return self.inner.attached() if self.inner is not None else None
+
+    def allows_app(self, bundle_id):
+        if not bundle_id or VIEW_SERVICE.fullmatch(bundle_id):
+            return True
+        if bundle_id == self.bundle:  # the user's own list of apps Mobster never opens still applies
+            allows = getattr(self.inner, "allows_app", None)
+            return bool(allows(bundle_id)) if callable(allows) else True
+        self.left = bundle_id
+        return False
+
+    def finish(self, driver):
+        if self.inner is not None:
+            self.inner.finish(driver)
+
+
+def check_guard(manager, bundle):
+    if not is_real_device(manager):
+        return None
+    record = getattr(manager, "record", None) or {}
+    inner = None
+    try:
+        from ..lockscreen import guard_for
+        inner = guard_for(device_id=record.get("udid") or record.get("id"), wda_url=record.get("wdaUrl"),
+                          mode="scripts", usb=record.get("kind") == "usb")
+    except Exception:
+        inner = None  # no lock detection: the app restriction still holds
+    return StayInApp(bundle, inner)
+
+
+def smart_request(app_name, steps):
+    """What Smart is asked: "In <App>: <the step>", or the steps numbered."""
+    if len(steps) == 1:
+        return f"In {app_name}: {steps[0]}"
+    return f"In {app_name}: " + " ".join(f"{index}. {step}" for index, step in enumerate(steps, 1))

mobile_agent/verify/snapshot_run.py

@@ -0,0 +1,114 @@
+"""The snapshot step of one verify run: take the screen, compare it to its baseline, record or update the baseline."""
+
+import shutil
+from pathlib import Path
+
+from . import snapshots
+from .checks import project_root
+
+LEVEL_MESSAGES = {
+    snapshots.CHANGED: "{pct} of the screen changed; the limit is {limit}. Open the diff, and run "
+                       "`mobster test --update-snapshots` if the new screen is right.",
+    snapshots.SIZE_CHANGED: "the screen is {size} px and the baseline is {base} px. Run the check on the baseline's "
+                            "device, or `mobster test --update-snapshots` to record this size.",
+}
+
+
+def _percent(value):
+    return f"{value:.2f} %" if value >= .01 or value == 0 else "under 0.01 %"
+
+
+def project_of(run):
+    """The folder holding .mobster/ for this run, or None."""
+    if run.runs_dir.parent.name == ".mobster":
+        return run.runs_dir.parent.parent
+    return project_root(run.check.source) if run.check.source else None
+
+
+def _finding(name, level, message, frame, evidence):
+    return {"id": f"snapshot {name}", "audit": "snapshot", "guideline": None, "level": level, "frame": frame,
+            "message": f"snapshot {name}: {message}", "evidence": evidence}
+
+
+def take(run, tree, frame):
+    """Compare the screen to the check's baseline. Returns (the result dict or None, findings). Never raises: a
+    snapshot that can't be taken is a finding for a person, not a crash."""
+    from PIL import Image
+    check = run.check
+    spec = check.snapshot
+    name = spec.name
+    root = project_of(run)
+    if root is None:
+        return None, [_finding(name, "review", "Mobster has no project folder to keep the baseline in. Run the check "
+                                               "from a folder with .mobster/.", frame, "no .mobster folder")]
+    target = run.target
+    device = getattr(target, "device_type", None) or "iphone"
+    key = snapshots.check_key(check.source, root, check.name)
+    baseline = snapshots.baseline_file(root, key, name, device, check.conditions)
+    folder = run.run_dir / snapshots.FOLDER
+    current_path = folder / f"{name}-current.png"
+    try:
+        folder.mkdir(parents=True, exist_ok=True)
+        run._call(run.manager.screenshot, target, current_path, quality=100)
+        with Image.open(current_path) as opened:
+            current = opened.convert("RGB")
+    except Exception as error:
+        run.log(f"snapshot: no screenshot ({type(error).__name__})")
+        return None, [_finding(name, "review", "Mobster couldn't take the screenshot, so nothing was compared.",
+                               frame, "no screenshot")]
+    rects = snapshots.mask_rects(spec, tree, current.width, status_bar_set=run._status_bar_set)
+    relative = baseline.relative_to(root).as_posix()
+    result = {"name": name, "key": relative, "status": None, "thresholdPercent": spec.threshold,
+              "size": [current.width, current.height], "masks": [[round(v) for v in rect] for rect in rects],
+              "regions": [], "changedPercent": 0.0, "changedPixels": 0, "comparedPixels": 0, "diffMs": None,
+              "baseline": None, "current": current_path.relative_to(run.run_dir).as_posix(), "diff": None,
+              "device": device, "appearance": (check.conditions or {}).get("appearance"),
+              "contentSize": (check.conditions or {}).get("content_size"),
+              "locale": (check.conditions or {}).get("locale"), "statusBarSet": run._status_bar_set}
+    existed = baseline.is_file()
+    if not existed and not check.snapshot_record:
+        return None, [_finding(name, "fail", f"there's no baseline at {relative}, and an approved CI suite never "
+                                             "records one. Record it with `mobster test --update-snapshots`, then "
+                                             "approve a new revision.", frame, relative)]
+    if check.snapshot_update or not existed:
+        snapshots.save_png(current, baseline)
+        result["status"] = snapshots.UPDATED if existed else snapshots.RECORDED
+        result["baseline"] = _copy_baseline(baseline, folder, name, run.run_dir)
+        run.log(f"snapshot {name}: baseline {result['status']} at {relative}")
+        if check.snapshot_update:
+            return result, []
+        return result, [_finding(name, "review", f"baseline recorded at {relative}. Review the screen, commit the "
+                                                 "file, and the next run compares to it.", frame, relative)]
+    try:
+        with Image.open(baseline) as opened:
+            old = opened.convert("RGB")
+    except Exception as error:
+        run.log(f"snapshot: unreadable baseline ({type(error).__name__})")
+        return result, [_finding(name, "review", f"the baseline {relative} can't be read as an image. Run "
+                                                 "`mobster test --update-snapshots` to write it again.", frame,
+                                 relative)]
+    result["baseline"] = _copy_baseline(baseline, folder, name, run.run_dir)
+    found = snapshots.compare(old, current, rects, spec.threshold)
+    result.update(status=found.status, changedPercent=round(found.changed_percent, 4),
+                  changedPixels=found.changed_pixels, comparedPixels=found.compared_pixels, regions=found.regions,
+                  diffMs=round(found.seconds * 1000))
+    run.log(f"snapshot {name}: {found.status}, {_percent(found.changed_percent)} changed, {result['diffMs']} ms")
+    if found.status == snapshots.MATCHED:
+        return result, []
+    evidence = relative
+    if found.diff is not None:
+        diff_path = folder / f"{name}-diff.png"
+        snapshots.save_png(found.diff, diff_path)
+        result["diff"] = evidence = diff_path.relative_to(run.run_dir).as_posix()
+    message = LEVEL_MESSAGES[found.status].format(
+        pct=_percent(found.changed_percent), limit=f"{spec.threshold:g} %", size="x".join(map(str, current.size)),
+        base="x".join(map(str, old.size)))
+    return result, [_finding(name, "fail", message, frame, evidence)]
+
+
+def _copy_baseline(baseline, folder, name, run_dir):
+    """A copy of the baseline in the run's folder, so a shared report carries all three images."""
+    copy = Path(folder) / f"{name}-baseline.png"
+    copy.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(baseline, copy)
+    return copy.relative_to(run_dir).as_posix()