mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/android/conditions.py

@@ -0,0 +1,128 @@
+"""A check's conditions on Android: the ones with an Android equivalent are set, the rest make the check couldn't-run
+(it never runs in the wrong state)."""
+
+import re
+
+from ..verify.conditions import ConditionError
+from .adb import AdbError
+
+# iOS privacy service -> Android runtime permissions.
+PERMISSIONS = {
+    "calendar": ("android.permission.READ_CALENDAR", "android.permission.WRITE_CALENDAR"),
+    "contacts": ("android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"),
+    "contacts-limited": ("android.permission.READ_CONTACTS", "android.permission.WRITE_CONTACTS"),
+    "location": ("android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION"),
+    "location-always": ("android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION",
+                        "android.permission.ACCESS_BACKGROUND_LOCATION"),
+    "microphone": ("android.permission.RECORD_AUDIO",),
+    "photos": ("android.permission.READ_MEDIA_IMAGES", "android.permission.READ_MEDIA_VIDEO"),
+}
+NOT_ON_ANDROID = {
+    "push": "conditions.push sends an APNs payload, which Android has no equivalent of here",
+    "content_size": "conditions.content_size has no Android mapping yet",
+    "increase_contrast": "conditions.increase_contrast has no Android mapping yet",
+    "route": "conditions.route has no Android mapping yet",
+    "media": "conditions.media has no Android mapping yet",
+    "status_bar": "conditions.status_bar has no Android mapping yet",
+    "network": "conditions.network shapes traffic through an iOS simulator's proxy, which Android has no equivalent of "
+               "here",
+}
+SUPPORTED = ("appearance", "locale", "location", "permissions")   # what _apply sets; any other key is refused
+FIX = "Remove that condition, or run the check on an iOS simulator with --sim."
+
+
+class AndroidConditions:
+    """Same shape as verify.conditions.Applier: before_launch, after_launch, launch_args, launch_env, restore, report,
+    and ``net``, which is always None: network conditions and request stubs are an iOS simulator's (netrun.py)."""
+
+    net = None
+
+    def __init__(self, spec, adb, *, bundle, emulator, actions=None):
+        self.spec, self.adb, self.bundle, self.emulator = dict(spec), adb, bundle, emulator
+        self.actions = actions      # the run's action journal (verify/actions.py): every change is journaled first
+        self.applied, self.skipped, self._undo = [], [], []
+
+    def _change(self, operation, call, *args, **kwargs):
+        """One device change, journaled before it is sent; an answer that never came stops the run, never retried."""
+        if self.actions is None:
+            raise ConditionError("Device condition changes need an action journal.", FIX)
+        with self.actions.action(operation):
+            return call(*args, **kwargs)
+
+    def launch_args(self):
+        return ()
+
+    def launch_env(self):
+        return {}
+
+    def before_launch(self):
+        for key in self.spec:   # a key added for iOS later is refused here too, never skipped unseen
+            if key not in SUPPORTED:
+                why = NOT_ON_ANDROID.get(key, f"conditions.{key} has no Android mapping yet")
+                raise ConditionError(f"{why}, so this check can't run on Android.", FIX)
+        try:
+            self._apply()
+        except AdbError as error:
+            raise ConditionError(f"Mobster couldn't set a condition on the Android device: {error}",
+                                 "Run `mobster sim doctor`, then try again. Remove the condition to run the check "
+                                 "without it.") from None
+
+    def _apply(self):
+        spec = self.spec
+        if "appearance" in spec:
+            text = self.adb.shell("cmd", "uimode", "night", timeout=10, check=False).text
+            old = re.search(r"Night mode: (yes|no)", text)
+            self._change("CONDITION_SET", self.adb.shell, "cmd", "uimode", "night",
+                         "yes" if spec["appearance"] == "dark" else "no", timeout=10)
+            if old:
+                self._undo.append(("cmd", "uimode", "night", old.group(1)))
+            self.applied.append("appearance")
+        if "locale" in spec:
+            tag = spec["locale"].replace("_", "-")
+            def set_locale():
+                result = self.adb.shell("cmd", "locale", "set-app-locales", self.bundle, "--locales", tag, timeout=10,
+                                        check=False)
+                if result.code != 0 or b"xception" in result.out + result.err:
+                    raise AdbError("per-app languages need Android 13 or later")
+            self._change("CONDITION_SET", set_locale)
+            self._undo.append(("cmd", "locale", "set-app-locales", self.bundle, "--locales", ""))
+            self.applied.append("locale")
+        if "location" in spec:
+            if not self.emulator:
+                raise ConditionError("conditions.location sets an emulator's GPS fix, and a USB Android phone has no "
+                                     "such control, so this check can't run on it.", FIX)
+            place = spec["location"]
+            self._change("CONDITION_SET", self.adb.adb, "emu", "geo", "fix", f"{place['longitude']:g}",
+                         f"{place['latitude']:g}", timeout=10)
+            self.applied.append("location")
+        if spec.get("permissions") and not self.emulator:
+            # As on an iPhone: a phone's permissions are someone's own, so a check never changes them there.
+            self.skipped.append({"key": "permissions", "why": "Mobster never changes an app's permissions on a phone."})
+            return
+        for service, action in (spec.get("permissions") or {}).items():
+            names = PERMISSIONS.get(service)
+            if names is None:
+                raise ConditionError(f"conditions.permissions.{service} has no Android permission.", FIX)
+            for name in names:
+                def change(name=name, action=action):
+                    try:
+                        self.adb.permission(self.bundle, name, action == "grant")
+                    except AdbError:
+                        # A permission the app does not declare, or the OS version lacks, cannot be revoked.
+                        if action == "grant":
+                            raise
+                self._change("CONDITION_SET", change)
+            self.applied.append("permissions")
+
+    def after_launch(self):
+        """Nothing is sent after launch on Android."""
+
+    def restore(self, actions=None):
+        """Undo each change under the device lease, journaled; stop at the first that isn't confirmed, never retried."""
+        if actions is not None:
+            self.actions = actions
+        while self._undo:
+            self._change("CONDITION_RESTORE", self.adb.shell, *self._undo.pop(), timeout=10)
+
+    def report(self):
+        return {"applied": list(dict.fromkeys(self.applied)), "skipped": list(self.skipped)}

mobile_agent/android/doctor.py

@@ -0,0 +1,54 @@
+"""`mobster sim doctor` rows for Android: SDK, platform-tools, emulator, an AVD, acceleration, devices."""
+
+import platform
+
+from ..sim.doctor import FAIL, OK, SKIP, WARN, check
+from . import adb as adb_module
+
+SDK_FIX = ("Install Android Studio, open it once, and let it install the SDK (about 3 GB with platform-tools and the "
+           "emulator)")
+EMULATOR_FIX = "In Android Studio: Settings > SDK Manager > SDK Tools > Android Emulator"
+AVD_FIX = "In Android Studio: Device Manager > Create Virtual Device (an arm64 system image on Apple silicon)"
+
+
+def run_checks(manager):
+    """Rows for the SDK in use. ``manager`` is an EmulatorManager."""
+    root = manager.root
+    if root is None:
+        return [check("android_sdk", "Android SDK", FAIL, "not found (no ANDROID_HOME, no ~/Library/Android/sdk)",
+                      SDK_FIX)]
+    rows = [check("android_sdk", "Android SDK", OK, str(root))]
+    adb_path = adb_module.tool("adb", root)
+    if not adb_path:
+        rows.append(check("android_adb", "adb", FAIL, "platform-tools is missing",
+                          "SDK Manager > SDK Tools > Platform-Tools"))
+    else:
+        version = manager._run([adb_path, "version"], 10, None)
+        first = version.text.splitlines()[0] if version.code == 0 and version.text else ""
+        rows.append(check("android_adb", "adb", OK if first else FAIL, first or "adb did not run",
+                          "" if first else "Reinstall platform-tools from the SDK Manager"))
+    emulator = adb_module.tool("emulator", root)
+    rows.append(check("android_emulator", "Android emulator", OK if emulator else WARN,
+                      emulator or "not installed: USB phones still work", "" if emulator else EMULATOR_FIX))
+    if not emulator:
+        rows.append(check("android_avd", "Android virtual device", SKIP, "needs the emulator"))
+    else:
+        avds = manager.avds()
+        rows.append(check("android_avd", "Android virtual device", OK if avds else WARN,
+                          ", ".join(avds) if avds else "none yet", "" if avds else AVD_FIX))
+        machine = platform.machine()
+        rows.append(check("android_accel", "Hardware acceleration", OK if machine == "arm64" else WARN,
+                          "Apple silicon (Hypervisor.framework)" if machine == "arm64"
+                          else f"{machine}: the emulator needs HVF and an x86_64 image",
+                          "" if machine == "arm64" else "Use an x86_64 system image"))
+    try:
+        devices = manager.devices()
+    except Exception as error:
+        return rows + [check("android_devices", "Android devices", FAIL, f"adb failed: {error}",
+                             "Run `adb kill-server`, then `adb devices -l`")]
+    blocked = [row for row in devices if row["state"] != "device"]
+    detail = "; ".join(f"{row['name']} ({row['kind']}, {row['state']})" for row in devices) or "none connected"
+    fix = ("Unlock the phone and accept the USB debugging prompt" if any(r["state"] == "unauthorized" for r in blocked)
+           else "Reconnect the device" if blocked else "")
+    rows.append(check("android_devices", "Android devices", WARN if blocked else OK if devices else SKIP, detail, fix))
+    return rows

mobile_agent/android/driver.py

@@ -0,0 +1,137 @@
+"""The Android driver: reads the screen with uiautomator, acts with `adb shell input`, over one adb connection.
+
+It hands the agent and verify the same Snapshot and AXTree an iPhone does. Nothing here talks to the Appium
+UIAutomator2 server yet: a dump costs about a second where the server's tree costs a few hundred ms, and the server's
+APKs need a pinned download (see docs/android.mdx).
+"""
+
+import time
+
+from ..drivers import Driver, register_driver
+from ..state import HOST_KEY_OPERATIONS, TEXT_OPERATIONS, from_wda_root
+from ..transport import Deadline, TransportError
+from ..wda.gestures import _swipe_points
+from ..wda.guards import DriverRejection, grounded_target
+from . import adb as adb_module
+from .tree import to_wda
+
+FRESH_SECONDS = 1.0
+SWIPE_MILLIS = 350
+KEYCODES = {"HOME": 3, "BACK": 4, "VOLUME_UP": 24, "VOLUME_DOWN": 25, "SUBMIT": 66}
+SOURCE = "android"
+
+
+class AndroidDriver(Driver):
+    capabilities = frozenset({"active_app", "capture_preview", "effects", "evidence_source", "launch", "long_press",
+                              "open_url", "tap_point"})
+    # Every method that changes the device: a verify run journals each call (verify/actions.py, guard_driver).
+    effects = ("execute", "launch", "open_url", "tap_point", "long_press")
+    can_type = True
+
+    def __init__(self, serial, adb=None):
+        self.adb = adb or adb_module.Adb(serial)
+        self.serial = serial
+        self._screen = None
+        self.last_image = None
+
+    def _guard(self, call, *args, **kwargs):
+        try:
+            return call(*args, **kwargs)
+        except adb_module.AdbError as error:
+            raise TransportError(str(error)) from None
+
+    def screen(self):
+        """(width px, height px, dpi), read once: a rotation or a density change needs a new driver."""
+        if self._screen is None:
+            self._screen = self._guard(self.adb.screen_px)
+        return self._screen
+
+    def evidence_source(self, timeout=15):
+        """The tree as WDA-shaped XML, for verify's evidence read."""
+        width, height, density = self.screen()
+        xml = self._guard(self.adb.dump_ui, timeout)
+        try:
+            return to_wda(xml, width, height, density)
+        except ValueError as error:
+            raise TransportError(f"The Android accessibility tree could not be read: {error}") from None
+
+    def observe(self, timeout=10):
+        from ..state import _parse_wda
+        snapshot = from_wda_root(_parse_wda(self.evidence_source(timeout)))
+        snapshot.source = SOURCE
+        return snapshot
+
+    def active_app(self, timeout=5):
+        return self._guard(self.adb.front_package)
+
+    def capture_preview(self, timeout=3):
+        return self._guard(self.adb.screenshot_data_uri, timeout)
+
+    def launch(self, package, timeout=20):
+        self._guard(self.adb.launch, package)
+        return self.observe(timeout)
+
+    def open_url(self, url):
+        self._guard(self.adb.open_url, url)
+
+    def tap_point(self, x, y):
+        """Tap a screen point given as fractions of the screen."""
+        width, height, _ = self.screen()
+        self._guard(self.adb.tap, x * width, y * height)
+
+    def long_press(self, x, y):
+        width, height, _ = self.screen()
+        self._guard(self.adb.long_press, x * width, y * height)
+
+    def _check_current(self, snapshot, deadline):
+        if time.monotonic() - snapshot.captured_at <= FRESH_SECONDS:
+            return
+        if self.observe(timeout=deadline.remaining()).fingerprint != snapshot.fingerprint:
+            raise DriverRejection("stale_revision")
+
+    def execute(self, operation, target, snapshot, text=None, timeout=10):
+        deadline = Deadline(timeout)
+        width, height, _ = self.screen()
+        if operation in HOST_KEY_OPERATIONS or operation == "BACK":
+            self._guard(self.adb.key, KEYCODES[operation])
+            return {"dispatch_attempted": True}
+        if operation == "LAUNCH_APP":
+            self._guard(self.adb.launch, target)
+            return {}
+        if operation == "SUBMIT":
+            grounded_target(operation, target, snapshot)
+            if "SUBMIT" not in target.actions:
+                raise ValueError("SUBMIT needs a keyboard and an editable field")
+            self._check_current(snapshot, deadline)
+            self._guard(self.adb.key, KEYCODES["SUBMIT"])
+        elif operation == "TAP":
+            grounded_target(operation, target, snapshot)
+            self._check_current(snapshot, deadline)
+            x, y = target.tap_point
+            self._guard(self.adb.tap, x * width, y * height)
+        elif operation in TEXT_OPERATIONS:
+            grounded_target(operation, target, snapshot)
+            self._check_current(snapshot, deadline)
+            if not isinstance(text, str) or not text:
+                raise ValueError("TYPE requires text")
+            x, y = target.tap_point
+            self._guard(self.adb.tap, x * width, y * height)
+            self._guard(self.adb.text, text)
+            if operation == "TYPE_SUBMIT":
+                self._guard(self.adb.key, KEYCODES["SUBMIT"])
+        elif operation in {"SWIPE_UP", "SWIPE_DOWN", "SWIPE_LEFT", "SWIPE_RIGHT"}:
+            aimed = None
+            if target is not None and operation in {"SWIPE_LEFT", "SWIPE_RIGHT"}:
+                grounded_target(operation, target, snapshot)
+                aimed = target.rect
+            x1, y1, x2, y2 = _swipe_points(operation, width, height, aimed)
+            self._guard(self.adb.swipe, x1, y1, x2, y2, SWIPE_MILLIS)
+        else:
+            raise ValueError("Unsupported Android operation")
+        return {}
+
+    def close(self):
+        """Nothing is held open: adb runs one command per call."""
+
+
+register_driver("android", AndroidDriver)

mobile_agent/android/emulator.py

@@ -0,0 +1,216 @@
+"""Android emulators Mobster boots: one lease per run, a cap like the iOS simulators', and only its own are stopped."""
+
+import json
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..sim.models import SimError, SimLease
+from . import adb as adb_module
+from .adb import Adb, AdbError
+
+DEFAULT_MAX = 2
+BOOT_TIMEOUT = 240
+FIRST_PORT, LAST_PORT = 5554, 5584   # emulator console ports are even; adb sees emulator-<port>
+EMULATOR_ARGS = ("-no-window", "-no-audio", "-no-snapshot-save", "-no-boot-anim", "-gpu", "swiftshader_indirect")
+AVD_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._\-]{0,63}")
+
+
+@dataclass(frozen=True)
+class AndroidTarget:
+    serial: str
+    name: str        # "Pixel_8" or the phone's model
+    kind: str        # "emulator" or "usb"
+    avd: str = ""
+
+
+def _lease(identity):
+    from ..journal import Lease
+    return Lease.device(identity)
+
+
+def _spawn(argv):
+    return subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                            start_new_session=True)
+
+
+class EmulatorManager:
+    """``adb`` lists devices, ``spawn`` starts the emulator process, ``lease`` takes the per-device lock."""
+
+    def __init__(self, data_dir, adb=None, run=adb_module.run_process, spawn=_spawn, lease=_lease, root=None,
+                 sleep=time.sleep, clock=time.monotonic):
+        self.data_dir = Path(data_dir).expanduser() / "android"
+        self.root = root if root is not None else adb_module.sdk_root()
+        self.adb = adb or Adb(run=run, binary=adb_module.tool("adb", self.root) or "adb")
+        self._run, self._spawn, self._lease, self.sleep, self.clock = run, spawn, lease, sleep, clock
+
+    @property
+    def max_emulators(self):
+        text = str(os.environ.get("MOBSTER_MAX_SIMS") or "").strip()
+        if not text:
+            return DEFAULT_MAX
+        if not text.isdigit() or int(text) < 1:
+            raise SimError("environment", f"MOBSTER_MAX_SIMS is {text!r}; it must be a whole number of 1 or more.",
+                           "Unset it to use 2.")
+        return int(text)
+
+    # -- what exists
+
+    def avds(self):
+        emulator = adb_module.tool("emulator", self.root)
+        if not emulator:
+            return []
+        result = self._run([emulator, "-list-avds"], 20, None)
+        return [line.strip() for line in result.text.splitlines() if AVD_NAME.fullmatch(line.strip())]
+
+    def avd_of(self, serial):
+        result = Adb(serial, self._run, self.adb.binary).adb("emu", "avd", "name", timeout=10, check=False)
+        lines = [line.strip() for line in result.text.splitlines() if line.strip() and line.strip() != "OK"]
+        return lines[0] if lines else ""
+
+    def devices(self):
+        """Android devices as rows: serial, name, kind, state, avd, owned (a Mobster-booted emulator), in_use."""
+        rows = []
+        for device in self.adb.devices():
+            avd = self.avd_of(device.serial) if device.kind == "emulator" and device.ready else ""
+            identity = self._identity(device.serial, avd)
+            rows.append({"platform": "android", "serial": device.serial, "name": avd or device.model or device.serial,
+                         "kind": device.kind, "state": device.state, "avd": avd,
+                         "owned": self._pid_file(avd).exists() if avd else False,
+                         "in_use": self._in_use(identity)})
+        return rows
+
+    @staticmethod
+    def _identity(serial, avd):
+        return f"android:avd:{avd}" if avd else f"android:{serial}"
+
+    def _in_use(self, identity):
+        try:
+            held = self._lease(identity)
+        except Exception:
+            return True
+        held.close()
+        return False
+
+    def _pid_file(self, avd):
+        return self.data_dir / f"{avd}.json"
+
+    # -- acquire and release
+
+    def acquire(self, avd=None, serial=None, timeout=BOOT_TIMEOUT):
+        """A lease on an idle ready device: ``serial`` (a USB phone or running emulator), else a running emulator of
+        ``avd``, else a booted one. SimError("busy") when everything is in use and the cap is reached."""
+        rows = self.devices()
+        if serial:
+            rows = [row for row in rows if row["serial"] == serial]
+            if not rows:
+                raise SimError("environment", f"No Android device {serial} is connected.", "Run `adb devices -l`.")
+        elif avd:
+            rows = [row for row in rows if row["avd"] == avd]
+        else:
+            rows = [row for row in rows if row["kind"] == "emulator"]  # a USB phone is used only when named
+        for row in rows:
+            if row["state"] != "device":
+                continue
+            lease = self._try_lease(self._identity(row["serial"], row["avd"]))
+            if lease is not None:
+                target = AndroidTarget(row["serial"], row["name"], row["kind"], row["avd"])
+                return SimLease(target, [lease])
+        if serial:
+            raise SimError("busy", f"{serial} is running a check.", "Wait for it to finish.")
+        return self._boot_and_lease(avd, timeout)
+
+    def _try_lease(self, identity):
+        try:
+            return self._lease(identity)
+        except Exception:
+            return None
+
+    def _boot_and_lease(self, avd, timeout):
+        running = [row for row in self.devices() if row["owned"]]
+        if len(running) >= self.max_emulators:
+            raise SimError("busy", f"All {self.max_emulators} of Mobster's Android emulators are running checks.",
+                           "Wait for one to finish, or set MOBSTER_MAX_SIMS higher.")
+        names = self.avds()
+        if not names:
+            raise SimError("environment", "There is no Android virtual device (AVD).",
+                           "Create one in Android Studio's Device Manager, or with avdmanager.")
+        if avd and avd not in names:
+            raise SimError("environment", f"There is no AVD named {avd}; there are {', '.join(names)}.",
+                           "Pick one of those, or create it in Android Studio's Device Manager.")
+        avd = avd or names[0]
+        lease = self._try_lease(self._identity("", avd))
+        if lease is None:
+            raise SimError("busy", f"{avd} is running a check.", "Wait for it to finish.")
+        try:
+            serial = self._boot(avd, timeout)
+        except BaseException:
+            lease.close()
+            raise
+        return SimLease(AndroidTarget(serial, avd, "emulator", avd), [lease])
+
+    def _free_port(self):
+        taken = {int(row["serial"].split("-")[1]) for row in self.adb.devices() if row.kind == "emulator"}
+        for port in range(FIRST_PORT, LAST_PORT + 1, 2):
+            if port not in taken:
+                return port
+        raise SimError("simulator", "Every emulator port from 5554 to 5584 is in use.",
+                       "Stop an emulator you started by hand.")
+
+    def _boot(self, avd, timeout):
+        emulator = adb_module.tool("emulator", self.root)
+        if not emulator:
+            raise SimError("environment", "The Android emulator is not installed.",
+                           "Install it from Android Studio's SDK Manager.")
+        port = self._free_port()
+        serial = f"emulator-{port}"
+        process = self._spawn([emulator, "-avd", avd, "-port", str(port), *EMULATOR_ARGS])
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self._pid_file(avd).write_text(json.dumps({"pid": process.pid, "serial": serial}))
+        guest = Adb(serial, self._run, self.adb.binary)
+        end = self.clock() + timeout
+        while self.clock() < end:
+            if process.poll() is not None:
+                self._pid_file(avd).unlink(missing_ok=True)
+                raise SimError("simulator", f"The emulator for {avd} exited while booting.",
+                               "Start it once from Android Studio to see why.")
+            try:
+                if serial in {d.serial for d in self.adb.devices() if d.ready} and guest.booted():
+                    return serial
+            except AdbError:
+                pass
+            self.sleep(2)
+        self._stop(avd, serial, process.pid)
+        raise SimError("simulator", f"{avd} did not finish booting in {timeout} s.",
+                       "Close other heavy jobs and try again.")
+
+    def _stop(self, avd, serial, pid):
+        Adb(serial, self._run, self.adb.binary).adb("emu", "kill", timeout=10, check=False)
+        end = self.clock() + 15
+        while self.clock() < end:
+            try:
+                os.kill(pid, 0)
+            except OSError:
+                break
+            self.sleep(.5)
+        else:
+            try:
+                os.kill(pid, 15)
+            except OSError:
+                pass
+        self._pid_file(avd).unlink(missing_ok=True)
+
+    def shutdown(self, avd=None):
+        """Stop the emulators Mobster booted (all, or ``avd``) that are not running a check. Others are never
+        touched."""
+        stopped = []
+        for row in self.devices():
+            if not row["owned"] or row["in_use"] or (avd and row["avd"] != avd):
+                continue
+            info = json.loads(self._pid_file(row["avd"]).read_text())
+            self._stop(row["avd"], row["serial"], int(info["pid"]))
+            stopped.append(row["avd"])
+        return stopped

mobile_agent/android/logs.py

@@ -0,0 +1,85 @@
+"""logcat and crashes. Every line passes the secret filter before it is kept."""
+
+import re
+from dataclasses import dataclass
+
+from .. import secret_filter
+from .adb import Adb, valid_package
+
+THREADTIME = re.compile(r"^(\d\d-\d\d \d\d:\d\d:\d\d\.\d+)\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+(.*?)\s*:\s?(.*)$")
+FATAL = re.compile(r"^FATAL EXCEPTION: (.*)$")
+PROCESS = re.compile(r"^Process: ([A-Za-z0-9_.]+), PID: (\d+)")
+ANR = re.compile(r"^ANR in ([A-Za-z0-9_.]+)(?: \(([^)]*)\))?")
+EXCEPTION = re.compile(r"^([A-Za-z0-9_.$]+(?:Exception|Error)): ?(.*)$")
+
+
+@dataclass(frozen=True)
+class Crash:
+    kind: str       # "crash" or "anr"
+    package: str
+    pid: int
+    thread: str
+    exception: str  # the first exception line, e.g. "java.lang.IllegalStateException: boom"
+    lines: tuple    # the block's lines, filtered
+
+
+def read_logcat(adb: Adb, since=None, limit=4000):
+    """Filtered logcat lines (`adb logcat -d -v threadtime`), newest ``limit`` of them; ``since`` is
+    "MM-DD HH:MM:SS.mmm"."""
+    args = ["logcat", "-d", "-v", "threadtime", *(["-T", since] if since else [])]
+    text = adb.adb(*args, timeout=30).text
+    return [secret_filter.redact(line) for line in text.splitlines()[-limit:]]
+
+
+def parse_crashes(lines, package=None):
+    """The crashes and ANRs in threadtime lines. ``package`` keeps only that app's."""
+    crashes, block, kind = [], [], None
+    last_key = None
+
+    def close():
+        nonlocal block, kind
+        if block:
+            crash = _crash(kind, block)
+            if crash and (package is None or crash.package == package):
+                crashes.append(crash)
+        block, kind = [], None
+
+    for raw in lines:
+        match = THREADTIME.match(raw)
+        if not match:
+            continue
+        _time, pid, _tid, level, tag, message = match.groups()
+        key = (pid, tag)
+        if kind and (key != last_key or level not in {"E", "F"}):
+            close()
+        if not kind:
+            if tag == "AndroidRuntime" and FATAL.match(message):
+                kind = "crash"
+            elif tag == "ActivityManager" and ANR.match(message):
+                kind = "anr"
+        if kind:
+            block.append(message)
+            last_key = key
+    close()
+    return crashes
+
+
+def _crash(kind, block):
+    package, pid, thread, exception = "", 0, "", ""
+    for message in block:
+        fatal, process, anr = FATAL.match(message), PROCESS.match(message), ANR.match(message)
+        if fatal:
+            thread = fatal.group(1)
+        elif process:
+            package, pid = process.group(1), int(process.group(2))
+        elif anr:
+            package, thread = anr.group(1), anr.group(2) or ""
+        elif not exception and EXCEPTION.match(message):
+            exception = message
+    if not package:
+        return None
+    return Crash(kind, package, pid, thread, exception, tuple(block))
+
+
+def crashes_of(adb, package, since=None):
+    return parse_crashes(read_logcat(adb, since), valid_package(package))