mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/netstubs.py

@@ -0,0 +1,132 @@
+"""A check's ``stubs:``: fixed answers to named requests, served by the run's proxy (netproxy.py)."""
+
+import difflib
+import json
+import mimetypes
+from pathlib import Path
+
+from .assertions import CheckError
+from .conditions import _file
+
+KEYS = ("match", "respond")
+MATCH_KEYS = ("host", "path_prefix", "method")
+RESPOND_KEYS = ("status", "json", "file", "delay_ms")
+METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS")
+STUB_LIMIT = 50
+DELAY_LIMIT = 30000   # ms
+BODY_LIMIT = 8 * 1024 * 1024
+
+
+def _keys(value, allowed, where):
+    for key in value:
+        if key not in allowed:
+            close = difflib.get_close_matches(str(key), allowed, n=1)
+            raise CheckError(f"{where}.{key} isn't a setting; " + (f"did you mean {close[0]}? " if close else "")
+                             + f"Use {', '.join(allowed)}.")
+
+
+def _host(value, where):
+    text = value.strip().lower() if isinstance(value, str) else ""
+    bare = text[2:] if text.startswith("*.") else text
+    if not bare or any(c in bare for c in "/:*? ") or bare.startswith(".") or bare.endswith("."):
+        raise CheckError(f"{where} must be a host name such as api.example.com or *.example.com, without a scheme, "
+                         "port or path.")
+    return text
+
+
+def parse(value, base_dir=None):
+    """The normalized ``stubs`` list of a check file: () when absent. Raises CheckError."""
+    if value is None:
+        return ()
+    if not isinstance(value, list) or not value:
+        raise CheckError("stubs must list requests to answer, such as [{match: {host: api.example.com}, "
+                         "respond: {status: 200, json: {items: []}}}].")
+    if len(value) > STUB_LIMIT:
+        raise CheckError(f"stubs has more than {STUB_LIMIT} entries. Keep the ones the check needs.")
+    out = []
+    for index, item in enumerate(value):
+        where = f"stubs[{index}]"
+        if not isinstance(item, dict) or set(item) != set(KEYS):
+            raise CheckError(f"{where} needs match and respond, such as {{match: {{host: api.example.com}}, "
+                             "respond: {status: 200, json: {}}}.")
+        match, respond = item["match"], item["respond"]
+        if not isinstance(match, dict) or not isinstance(respond, dict):
+            raise CheckError(f"{where}.match and {where}.respond must each be a mapping.")
+        _keys(match, MATCH_KEYS, f"{where}.match")
+        _keys(respond, RESPOND_KEYS, f"{where}.respond")
+        if "host" not in match:
+            raise CheckError(f"{where}.match needs a host.")
+        prefix = match.get("path_prefix", "/")
+        if not isinstance(prefix, str) or not prefix.startswith("/"):
+            raise CheckError(f"{where}.match.path_prefix must start with /, such as /v1/items.")
+        method = match.get("method")
+        if method is not None and (not isinstance(method, str) or method.upper() not in METHODS):
+            raise CheckError(f"{where}.match.method must be one of {', '.join(METHODS)}.")
+        status = respond.get("status", 200)
+        if isinstance(status, bool) or not isinstance(status, int) or not 100 <= status <= 599:
+            raise CheckError(f"{where}.respond.status must be a whole number from 100 to 599.")
+        delay = respond.get("delay_ms", 0)
+        if isinstance(delay, bool) or not isinstance(delay, int) or not 0 <= delay <= DELAY_LIMIT:
+            raise CheckError(f"{where}.respond.delay_ms must be a whole number of milliseconds from 0 to "
+                             f"{DELAY_LIMIT}.")
+        if "json" in respond and "file" in respond:
+            raise CheckError(f"{where}.respond has both json and file. Keep one.")
+        stub = {"host": _host(match["host"], f"{where}.match.host"), "path_prefix": prefix,
+                "method": method.upper() if method else None, "status": status, "delay_ms": delay,
+                "json": None, "file": None}
+        if "json" in respond:
+            try:
+                json.dumps(respond["json"])
+            except (TypeError, ValueError):
+                raise CheckError(f"{where}.respond.json must be plain JSON: text, numbers, lists and "
+                                 "objects.") from None
+            stub["json"] = respond["json"]
+        elif "file" in respond:
+            stub["file"] = _file(respond["file"], f"{where}.respond.file", base_dir)
+            if Path(stub["file"]).stat().st_size > BODY_LIMIT:
+                raise CheckError(f"{where}.respond.file is larger than {BODY_LIMIT // 1024 // 1024} MiB. Trim it.")
+        out.append(stub)
+    return tuple(out)
+
+
+def to_dict(stubs, project_root=None):
+    """The file shape of ``stubs``, with paths relative to ``project_root`` where they sit inside it."""
+    def relative(path):
+        try:
+            return str(Path(path).relative_to(Path(project_root).resolve()))
+        except (ValueError, TypeError):
+            return path
+    out = []
+    for stub in stubs:
+        match = {"host": stub["host"], "path_prefix": stub["path_prefix"]}
+        if stub["method"]:
+            match["method"] = stub["method"]
+        respond = {"status": stub["status"]}
+        if stub["json"] is not None:
+            respond["json"] = json.loads(json.dumps(stub["json"]))
+        if stub["file"]:
+            respond["file"] = relative(stub["file"])
+        if stub["delay_ms"]:
+            respond["delay_ms"] = stub["delay_ms"]
+        out.append({"match": match, "respond": respond})
+    return out
+
+
+def host_matches(pattern, host):
+    host = host.lower()
+    return host.endswith(pattern[1:]) if pattern.startswith("*.") else host == pattern
+
+
+def matches(stub, host, method, path):
+    return (host_matches(stub["host"], host) and (not stub["method"] or stub["method"] == method.upper())
+            and path.startswith(stub["path_prefix"]))
+
+
+def answer(stub):
+    """(status, content type, body bytes) of a stub's response."""
+    if stub["file"]:
+        kind = mimetypes.guess_type(stub["file"])[0] or "application/octet-stream"
+        return stub["status"], kind, Path(stub["file"]).read_bytes()
+    if stub["json"] is not None:
+        return stub["status"], "application/json", json.dumps(stub["json"]).encode()
+    return stub["status"], "text/plain", b""

mobile_agent/verify/overlay.py

@@ -0,0 +1,174 @@
+from pathlib import Path
+
+from .. import brand as tokens
+
+
+def _between(light, dark):
+    return tuple(round((a + b) / 2) for a, b in zip(tokens.rgb(light), tokens.rgb(dark)))
+
+
+# The brand's light green and coral hold white text at 4.5:1; outlines sit halfway between light and dark tones.
+GREEN, RED = tokens.rgb(tokens.LIGHT["green"]), tokens.rgb(tokens.LIGHT["coral"])
+GREEN_LINE = _between(tokens.LIGHT["green"], tokens.DARK["green"])
+RED_LINE = _between(tokens.LIGHT["coral"], tokens.DARK["coral"])
+SHOWN = tokens.rgb(tokens.LIGHT["violet"])  # violet: every element Mobster read
+SHOWN_ALPHA = round(255 * .3)
+TINT_ALPHA = round(255 * .10)
+FONT_CANDIDATES = ("/System/Library/Fonts/SFNS.ttf", "/System/Library/Fonts/Helvetica.ttc",
+                   "/Library/Fonts/Arial.ttf", "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf")
+FRAME_CSS_WIDTH = 280   # CSS px: the verify report's frame; the suite report's is 264
+MAX_PILLS = 6
+
+
+def _font(size):
+    from PIL import ImageFont
+    for path in FONT_CANDIDATES:
+        try:
+            font = ImageFont.truetype(path, size)
+        except OSError:
+            continue
+        try:
+            font.set_variation_by_name("Bold")  # SF is a variable font; others keep their one weight
+        except Exception:
+            pass
+        return font
+    try:
+        return ImageFont.load_default(size=size)
+    except TypeError:
+        return ImageFont.load_default()
+
+
+def pill_numbers(items):
+    """Which assertions get a pill: ``items`` is [(ok, has_node)] in the check's order."""
+    ranked = sorted((index for index, (ok, has_node) in enumerate(items) if has_node),
+                    key=lambda index: (bool(items[index][0]), index))
+    return set(ranked[:MAX_PILLS])
+
+
+def draw_overlay(frame_path, tree, asserted, out_path):
+    """The accessibility overlay: ``asserted`` is [(AssertionResult, [node paths])] in the check's order."""
+    from PIL import Image, ImageDraw, ImageFilter
+    with Image.open(frame_path) as source:
+        base = source.convert("RGBA")
+    width, height = base.size
+    scale = width / (tree.size[0] or 1)
+    k = width / FRAME_CSS_WIDTH  # image px per CSS px at the report's size
+    layer = Image.new("RGBA", base.size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+
+    def box(rect, grow=0):
+        x, y, w, h = rect
+        left, top = max(0, x * scale - grow), max(0, y * scale - grow)
+        right, bottom = min(width - 1, (x + w) * scale + grow), min(height - 1, (y + h) * scale + grow)
+        return (left, top, right, bottom) if right > left and bottom > top else None
+
+    def rounded(area, radius, **style):
+        radius = max(0, min(radius, (area[2] - area[0]) / 2, (area[3] - area[1]) / 2))
+        draw.rounded_rectangle(area, radius=radius, **style)
+
+    shown = tree.shown()
+    for node in shown:
+        area = box(node.rect)
+        # Not the containers that fill the screen: their edges would only rule lines across it.
+        if area and _area(area) < .2 * width * height:
+            rounded(area, 3 * k, outline=SHOWN + (SHOWN_ALPHA,), width=max(1, round(.75 * k)))
+    grow, stroke = round(2.5 * k), max(2, round(1.5 * k))
+    items = []
+    for result, paths in asserted:
+        nodes = [node for node in (tree.by_path(path) for path in paths) if node]
+        areas = sorted({area for area in (box(node.rect, grow) for node in nodes) if area},
+                       key=lambda area: (area[1], area[0]))
+        # An element inside another the same assertion matched (a switch's own label) is outlined once, outside.
+        areas = [area for area in areas if not any(other != area and _contains(other, area) for other in areas)]
+        items.append((result, areas))
+    # Held first, failed last, so a red outline is never under a green one.
+    for result, areas in sorted(items, key=lambda item: item[0].ok, reverse=True):
+        line = (GREEN_LINE if result.ok else RED_LINE) + (255,)
+        tint = (GREEN_LINE if result.ok else RED_LINE) + (TINT_ALPHA,)
+        for area in areas:
+            rounded(area, 7 * k, fill=tint, outline=line, width=stroke)
+    numbered = sorted(pill_numbers([(result.ok, bool(areas)) for result, areas in items]),
+                      key=lambda index: (items[index][0].ok, index))
+    asserted_areas = [area for _, areas in items for area in areas]
+    edges = base.convert("L").filter(ImageFilter.FIND_EDGES)
+    font = _font(max(10, round(12 * k)))
+    placed = []
+    jobs = [(index, 0) for index in numbered] + [(index, n) for index in numbered if not items[index][0].ok
+                                                   for n in range(1, min(3, len(items[index][1])))]
+    for index, n in jobs:
+        if n and len(placed) >= MAX_PILLS + 2:
+            break
+        result, areas = items[index]
+        _pill(draw, font, index + 1, result.ok, areas[n], (width, height), k, placed,
+              [area for area in asserted_areas if area != areas[n]], edges)
+    Image.alpha_composite(base, layer).convert("RGB").save(out_path, "JPEG", quality=85)
+    return Path(out_path)
+
+
+def _overlap(a, b):
+    return max(0, min(a[2], b[2]) - max(a[0], b[0])) * max(0, min(a[3], b[3]) - max(a[1], b[1]))
+
+
+def _area(a):
+    return max(0, a[2] - a[0]) * max(0, a[3] - a[1])
+
+
+def _contains(outer, inner):
+    return outer[0] <= inner[0] and outer[1] <= inner[1] and outer[2] >= inner[2] and outer[3] >= inner[3]
+
+
+def _pill(draw, font, number, ok, area, size, k, placed, others, edges):
+    from PIL import ImageStat
+    text = str(number)
+    left, top, right, bottom = draw.textbbox((0, 0), text, font=font, anchor="ls")
+    pill_h = round(18 * k)
+    pad, mark, gap, ring = round(5.5 * k), round(7.5 * k), round(3 * k), max(1, round(k))
+    pill_w = pad + mark + gap + (right - left) + pad
+    space = round(1.5 * k)  # outside, the pill touches the outline, so it reads as the outline's own label
+    x0, y0, x1, y1 = area
+    middle = (y0 + y1) / 2 - pill_h / 2 if y1 - y0 < 2 * pill_h else y0
+    inset = round(8 * k)
+    candidates = [(x0, y0 - space - pill_h, 0), (x0 - space - pill_w, middle, 0), (x1 + space, middle, 0),
+                  (x0, y1 + space, 0), (x1 - pill_w, y0 - space - pill_h, 0), (x1 - pill_w, y1 + space, 0),
+                  (x0 + inset, y0 - pill_h / 2, 2), (x1 - inset - pill_w, y0 - pill_h / 2, 2),
+                  (x0 + space, y0 + space, 4), (x1 - space - pill_w, y0 + space, 4)]
+    best = None
+    for order, (x, y, own_cost) in enumerate(candidates):
+        if x < ring or y < ring or x + pill_w > size[0] - ring or y + pill_h > size[1] - ring:
+            continue
+        rect = (x - ring, y - ring, x + pill_w + ring, y + pill_h + ring)
+        if any(_overlap(rect, other) for other in placed):
+            continue
+        whole = _area(rect)
+        busy = ImageStat.Stat(edges.crop(tuple(round(v) for v in rect))).mean[0]
+        cost = (busy + 60 * sum(_overlap(rect, other) for other in others) / whole
+                + own_cost * _overlap(rect, area) / whole + .3 * order)
+        if best is None or cost < best[0]:
+            best = (cost, x, y)
+        if busy < 3 and not any(_overlap(rect, other) for other in others) and own_cost == 0:
+            break
+    if best is None:  # nowhere free: the top corner inside, clamped to the frame
+        x = min(max(ring, x0 + space), size[0] - pill_w - ring)
+        y = min(max(ring, y0 + space), size[1] - pill_h - ring)
+        for _ in range(12):
+            rect = (x - ring, y - ring, x + pill_w + ring, y + pill_h + ring)
+            if not any(_overlap(rect, other) for other in placed):
+                break
+            y = min(y + pill_h + 2 * ring, size[1] - pill_h - ring)
+    else:
+        _, x, y = best
+    placed.append((x - ring, y - ring, x + pill_w + ring, y + pill_h + ring))
+    radius = pill_h / 2
+    draw.rounded_rectangle((x - ring, y - ring, x + pill_w + ring, y + pill_h + ring), radius=radius + ring,
+                           fill=(255, 255, 255, 235))
+    draw.rounded_rectangle((x, y, x + pill_w, y + pill_h), radius=radius, fill=(GREEN if ok else RED) + (255,))
+    white, line = (255, 255, 255, 255), max(2, round(1.5 * k))
+    gx, gy = x + pad, y + (pill_h - mark) / 2
+    if ok:
+        draw.line([(gx + .1 * mark, gy + .55 * mark), (gx + .4 * mark, gy + .82 * mark),
+                   (gx + .92 * mark, gy + .2 * mark)], fill=white, width=line, joint="curve")
+    else:
+        draw.line([(gx + .12 * mark, gy + .12 * mark), (gx + .88 * mark, gy + .88 * mark)], fill=white, width=line)
+        draw.line([(gx + .88 * mark, gy + .12 * mark), (gx + .12 * mark, gy + .88 * mark)], fill=white, width=line)
+    draw.text((gx + mark + gap - left, y + pill_h / 2 - (top + bottom) / 2), text, font=font, fill=white,
+              anchor="ls")

mobile_agent/verify/perf.py

@@ -0,0 +1,239 @@
+"""What a check measures: launch time, the app's memory, and hangs (docs/testing.mdx, "What a check measures").
+
+Everything here is cheap enough to run on every check: one `ps` every 500 ms, the accessibility reads the run already
+makes, and the app's own log. A number Mobster could not measure is None and is named in ``notMeasured``; a budget on
+a number that is None never passes (see ``judge``)."""
+
+import math
+import os
+import re
+import subprocess
+import threading
+from dataclasses import dataclass
+
+SAMPLE_EVERY = .5
+HANG_MS = 250
+BUDGET_KEYS = ("launch_ms", "memory_mb", "hangs")
+# The app's runloop monitor: "Hang detected: 0.52s (debugger attached, not reporting)".
+HANG_LINE = re.compile(r"Hang detected: (?P<seconds>\d+(?:\.\d+)?)\s*s\b")
+PS = "/bin/ps"
+NOT_MEASURED = {
+    "firstFrame": "A simulator logs no line for the app's first frame, so only the first stable screen is timed.",
+    "droppedFrames": "A simulator exposes no Core Animation commit times, so dropped frames are not counted.",
+    "iphoneMemory": ("On an iPhone, memory needs `pymobiledevice3 developer dvt sysmon`, which Mobster does not "
+                     "call yet."),
+}
+
+
+def parse_ps(text):
+    """(rss_mb, cpu_percent) from `ps -o rss=,pcpu=` for one process; None when the line is not that."""
+    parts = (text or "").split()
+    if len(parts) != 2:
+        return None
+    try:
+        rss_kb, cpu = int(parts[0]), float(parts[1])
+    except ValueError:
+        return None
+    if rss_kb <= 0 or cpu < 0 or not math.isfinite(cpu):
+        return None
+    return rss_kb / 1024, cpu
+
+
+def ps_sample(pid, *, run=subprocess.run):
+    """One reading of a simulator app's process (a simulator's processes are the Mac's own); None once it has gone."""
+    try:
+        done = run([PS, "-o", "rss=,pcpu=", "-p", str(int(pid))], capture_output=True, text=True, timeout=2,
+                   stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return None
+    return parse_ps(done.stdout) if done.returncode == 0 else None
+
+
+def percentile(values, share):
+    """The nearest-rank percentile of ``values`` (0 < share <= 1)."""
+    ordered = sorted(values)
+    return ordered[max(0, math.ceil(share * len(ordered)) - 1)]
+
+
+def memory_summary(samples):
+    """{peakMb, p95Mb, cpuPeakPct, samples} over (rss_mb, cpu) samples; None when there are none."""
+    if not samples:
+        return None
+    memory = [mb for mb, _ in samples]
+    return {"peakMb": round(max(memory), 1), "p95Mb": round(percentile(memory, .95), 1),
+            "cpuPeakPct": round(max(cpu for _, cpu in samples), 1), "samples": len(samples)}
+
+
+class Sampler:
+    """Reads the app's process when it starts, every SAMPLE_EVERY seconds on a thread of its own while the steps run,
+    and once more when it stops: a launch-only check that settles in a second still has its readings (26 Oct 2026,
+    iOS 26.4 simulator: runs of about 1.3 s got 2, 2, 0 and 1 samples with the start and the thread alone)."""
+
+    def __init__(self, pid_of, *, sample=None, every=SAMPLE_EVERY):
+        self._pid_of, self._sample, self._every = pid_of, sample or ps_sample, every
+        self.samples = []
+        self._stop = threading.Event()
+        self._thread = None
+
+    def start(self):
+        """The first reading is taken here, so a run that ends at once still has one."""
+        self._take()
+        self._thread = threading.Thread(target=self._run, name="mobster-perf-sampler", daemon=True)
+        self._thread.start()
+
+    def _take(self):
+        try:
+            pid = self._pid_of()
+            reading = self._sample(pid) if pid else None
+        except Exception:  # a sample never costs a run
+            reading = None
+        if reading is not None:
+            self.samples.append(reading)
+
+    def _run(self):
+        while not self._stop.wait(self._every):
+            self._take()
+
+    def stop(self):
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(2)
+        self._take()
+        return memory_summary(list(self.samples))
+
+
+def hang_summary(texts, *, threshold_ms=HANG_MS):
+    """{count, longestMs, thresholdMs} over the app's log lines: the hang reports of ``threshold_ms`` or longer."""
+    found = []
+    for text in texts:
+        match = HANG_LINE.search(text or "")
+        if match and float(match.group("seconds")) * 1000 >= threshold_ms:
+            found.append(round(float(match.group("seconds")) * 1000))
+    return {"count": len(found), "longestMs": max(found, default=0), "thresholdMs": threshold_ms}
+
+
+def build(*, launch, sampler_summary, hangs, simulator):
+    """The result's ``perf``: the four numbers, the Mac's 1-minute load when they were taken, and what isn't
+    measured."""
+    missing = {"firstFrame": NOT_MEASURED["firstFrame"]} if simulator else {}
+    if simulator:
+        missing["droppedFrames"] = NOT_MEASURED["droppedFrames"]
+    else:
+        missing["droppedFrames"] = "Dropped frames are not measured on an iPhone."
+        missing["iphoneMemory"] = NOT_MEASURED["iphoneMemory"]
+    try:
+        load = round(os.getloadavg()[0], 1)
+    except (OSError, AttributeError):
+        load = None
+    return {"launch": launch, "memory": sampler_summary, "hangs": hangs, "loadAverage": load,
+            "notMeasured": missing}
+
+
+@dataclass(frozen=True)
+class Breach:
+    key: str
+    message: str
+
+
+def judge(budget, perf):
+    """(breaches, unmeasured): which of a check's ``budget`` limits the run broke, and which it could not judge.
+
+    A limit on a number that was not measured is unmeasured, never met: a run that cannot show it stayed inside the
+    budget does not pass it."""
+    perf = perf or {}
+    values = {
+        "launch_ms": ((perf.get("launch") or {}).get("interactiveMs"), "Cold launch to the first stable screen",
+                      "{:,.0f} ms", "launch time"),
+        "memory_mb": ((perf.get("memory") or {}).get("peakMb"), "Peak memory", "{:,.0f} MB", "memory"),
+        "hangs": (None if perf.get("hangs") is None else perf["hangs"]["count"], "Hangs of "
+                  f"{HANG_MS} ms or longer", "{:,.0f}", "hangs"),
+    }
+    breaches, unmeasured = [], []
+    for key in BUDGET_KEYS:
+        limit = (budget or {}).get(key)
+        if limit is None:
+            continue
+        value, what, form, short = values[key]
+        if value is None:
+            verb = "were" if short == "hangs" else "was"
+            unmeasured.append(Breach(key, f"{short.capitalize()} {verb} not measured, so budget.{key} could not be "
+                                          "checked."))
+        elif value > limit:
+            breaches.append(Breach(key, f"{what} was {form.format(value)}, over budget.{key} of {form.format(limit)}."))
+    return breaches, unmeasured
+
+
+# What history keeps of a run's perf, and the unit each is shown in.
+METRICS = {"launchMs": "ms", "memoryMb": "MB", "hangs": ""}
+REGRESS_AT, BASELINE_RUNS, BASELINE_MIN = .20, 10, 3
+
+
+def clean(found):
+    """``found`` ({launchMs, memoryMb, hangs}) with only the finite, non-negative numbers; the boundary for history."""
+    found = found if isinstance(found, dict) else {}
+    return {key: found[key] for key in METRICS
+            if isinstance(found.get(key), (int, float)) and not isinstance(found[key], bool)
+            and math.isfinite(found[key]) and found[key] >= 0}
+
+
+def numbers(perf):
+    """{launchMs, memoryMb, hangs} of a result's ``perf``: only the ones that were measured."""
+    perf = perf if isinstance(perf, dict) else {}
+    return clean({"launchMs": (perf.get("launch") or {}).get("interactiveMs"),
+                  "memoryMb": (perf.get("memory") or {}).get("peakMb"),
+                  "hangs": (perf.get("hangs") or {}).get("count")})
+
+
+def compare(metric, latest, before):
+    """(arrow, change) of ``latest`` against the median of ``before`` (a list of earlier passes): ↑ when it is 20 %
+    more (a hang count: any more), ↓ when 20 % less, else →; None with fewer than BASELINE_MIN earlier values."""
+    before = [value for value in before if value is not None]
+    if latest is None or len(before) < BASELINE_MIN:
+        return None
+    ordered = sorted(before)
+    middle = len(ordered) // 2
+    base = ordered[middle] if len(ordered) % 2 else (ordered[middle - 1] + ordered[middle]) / 2
+    if metric == "hangs":
+        arrow = "↑" if latest > base else "↓" if latest < base else "→"
+    elif base <= 0:
+        return None
+    else:
+        change = (latest - base) / base
+        arrow = "↑" if change > REGRESS_AT else "↓" if change < -REGRESS_AT else "→"
+    return arrow, {"latest": latest, "baseline": round(base, 1), "runs": len(before)}
+
+
+def trend(runs):
+    """{metric: {arrow, latest, baseline, runs}} for the newest of ``runs`` (history's, oldest first) against the
+    median of the last BASELINE_RUNS passes before it. ↑ is a regression: more time, memory or hangs."""
+    if not runs:
+        return {}
+    *earlier, latest = runs
+    passes = [run for run in earlier if run["status"] == "passed"][-BASELINE_RUNS:]
+    out = {}
+    for metric in METRICS:
+        found = compare(metric, (latest.get("perf") or {}).get(metric),
+                        [(run.get("perf") or {}).get(metric) for run in passes])
+        if found is not None:
+            out[metric] = {"arrow": found[0], **found[1]}
+    return out
+
+
+def line(found, trends=None):
+    """One line for a report: "launch 812 ms ↑, memory 214 MB →, hangs 0"; "" when nothing was measured."""
+    values, trends = clean(found), trends or {}
+    parts = []
+    for metric, word in (("launchMs", "launch"), ("memoryMb", "memory"), ("hangs", "hangs")):
+        if metric in values:
+            value = values[metric]
+            unit = METRICS[metric]
+            text = f"{word} {value:,.0f}" + (f" {unit}" if unit else "")
+            arrow = (trends.get(metric) or {}).get("arrow")
+            parts.append(text + (f" {arrow}" if arrow else ""))
+    return ", ".join(parts)
+
+
+def last_run(row):
+    """`mobster test --history`'s second line for a check, its last run's numbers and markers, or nothing."""
+    measured = line(row.get("perfLatest") or {}, row.get("perf"))
+    return f"\n    Last run: {measured}." if measured else ""