irisandClaude Opus 5
5d77599f3f
ui-trace, the adb wrapper and its device recorder were loose files under ~/.local, and each Android checkout carried its own copy of the same emulator boot sequence. This puts them together, with an install script that symlinks them back so editing the repo is editing what runs. Two things are new rather than moved. `emu` is the emulator lifecycle -- name, serial, list, up, down -- keyed on the AVD named after the enclosing checkout, which is the rule that lets several sessions work here at once; and `adb` now fills in `-s` from that same rule, because with two emulators attached a bare `adb shell pm list packages` comes back empty rather than failing, which reads as the app being uninstalled rather than the question being ambiguous. `emu up` refuses when the machine has no room. On 2026-08-30 an emulator started with 2.8 GB available invoked the OOM killer, and what it took was not the emulator that had just started: it walked the user slice and killed pipewire, dbus-broker and another session's emulator first. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
384 lines
16 KiB
Python
Executable File
384 lines
16 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Record what an Android screen does, as text, and ask questions of it later.
|
|
|
|
Why this exists. `adb shell uiautomator dump` is the usual way to read a
|
|
screen's layout, and it costs about two seconds a call -- so an animation, a
|
|
scroll or a settling layout happens entirely in the gap between two samples,
|
|
and the only thing it can answer is what the screen looked like once it had
|
|
stopped. This drives a small resident recorder on the device instead (see
|
|
UiTrace.java beside this script), which connects to the accessibility service
|
|
once and then samples at whatever rate is asked for; 60Hz is comfortable.
|
|
|
|
The other half is that a screen has a few hundred nodes and a question is
|
|
almost always about two or three of them. So recording and reading are separate
|
|
steps: `record` saves everything, and `show` selects. A trace can be
|
|
re-interrogated with a different selector without touching the device again,
|
|
which matters because the interesting question is usually the one you think of
|
|
after seeing the first answer.
|
|
|
|
ui-trace record -d 3000 --do 'tap 540 800' -o /tmp/t.txt
|
|
ui-trace elements /tmp/t.txt # what is on screen, to pick from
|
|
ui-trace show /tmp/t.txt # what moved (the default question)
|
|
ui-trace show /tmp/t.txt -m 'Called|ask' # a timeline for those
|
|
|
|
Nothing here is specific to any app.
|
|
"""
|
|
|
|
import argparse
|
|
import os
|
|
import re
|
|
import subprocess
|
|
import sys
|
|
import tempfile
|
|
from pathlib import Path
|
|
|
|
SHARE = Path.home() / ".local/share/ui-trace"
|
|
DEVICE_JAR = "/data/local/tmp/uitrace.jar"
|
|
|
|
|
|
def find_adb():
|
|
"""The real adb, without assuming PATH has been set up for Android."""
|
|
for candidate in [
|
|
os.environ.get("ADB"),
|
|
"adb",
|
|
os.environ.get("ANDROID_HOME", "") + "/platform-tools/adb",
|
|
os.environ.get("ANDROID_SDK_ROOT", "") + "/platform-tools/adb",
|
|
str(Path.home() / "Android/Sdk/platform-tools/adb"),
|
|
]:
|
|
if not candidate or candidate.startswith("/platform-tools"):
|
|
continue
|
|
which = subprocess.run(["sh", "-c", f"command -v {candidate!r}"],
|
|
capture_output=True, text=True)
|
|
if which.returncode == 0:
|
|
return which.stdout.strip()
|
|
sys.exit("ui-trace: no adb found; set ANDROID_HOME or ADB")
|
|
|
|
|
|
def ensure_jar():
|
|
"""Build the device recorder if it is missing or older than its source."""
|
|
jar, source = SHARE / "uitrace.jar", SHARE / "UiTrace.java"
|
|
if not source.exists():
|
|
sys.exit(f"ui-trace: recorder source missing at {source}")
|
|
if not jar.exists() or jar.stat().st_mtime < source.stat().st_mtime:
|
|
print("ui-trace: building the device recorder...", file=sys.stderr)
|
|
subprocess.run([str(SHARE / "build.sh")], check=True,
|
|
stdout=subprocess.DEVNULL)
|
|
return jar
|
|
|
|
|
|
# --- recording -------------------------------------------------------------
|
|
|
|
def record(args):
|
|
jar = ensure_jar()
|
|
adb = find_adb()
|
|
target = ["-s", args.serial] if args.serial else []
|
|
pushed = subprocess.run([adb, *target, "push", str(jar), DEVICE_JAR],
|
|
capture_output=True, text=True)
|
|
if pushed.returncode != 0:
|
|
# Two emulators running is the usual cause, and adb says so plainly; there is
|
|
# nothing to add to its own message except which flag fixes it.
|
|
sys.exit(f"ui-trace: {pushed.stderr.strip() or 'adb push failed'}"
|
|
f"{'' if target else ' (use -s SERIAL to pick a device)'}")
|
|
remote = f"CLASSPATH={DEVICE_JAR} app_process /system/bin UiTrace"
|
|
remote += f" --duration {args.duration} --interval {args.interval}"
|
|
for step in args.do:
|
|
remote += f" --do {step!r}"
|
|
out = Path(args.out) if args.out else Path(
|
|
tempfile.mkstemp(prefix="ui-trace-", suffix=".txt")[1])
|
|
with out.open("w") as handle:
|
|
result = subprocess.run([adb, *target, "shell", remote], stdout=handle,
|
|
stderr=subprocess.STDOUT)
|
|
text = out.read_text()
|
|
if result.returncode != 0 or "# error" in text:
|
|
print(text[:2000], file=sys.stderr)
|
|
sys.exit("ui-trace: the device recorder failed")
|
|
frames, _ = parse(out)
|
|
print(f"ui-trace: {len(frames)} frames over {frames[-1][0] if frames else 0}ms "
|
|
f"-> {out}", file=sys.stderr)
|
|
return out
|
|
|
|
|
|
# --- reading ---------------------------------------------------------------
|
|
|
|
class Node:
|
|
__slots__ = ("depth", "box", "flags", "cls", "rid", "text", "desc", "label")
|
|
|
|
def __init__(self, parts):
|
|
self.depth = int(parts[1])
|
|
self.box = tuple(int(v) for v in parts[2:6])
|
|
self.flags, self.cls, self.rid, self.text, self.desc = parts[6:11]
|
|
self.label = (self.text or self.desc or self.rid.split("/")[-1]
|
|
or self.cls or "?")
|
|
|
|
def haystack(self):
|
|
return "\t".join((self.label, self.rid, self.cls, self.text, self.desc))
|
|
|
|
|
|
def parse(path):
|
|
"""A trace file into (frames, actions). A frame is (t_ms, [Node]).
|
|
|
|
A missing or unreadable trace exits with one line rather than a stack trace: the
|
|
caller is usually reading this in a terminal or a context window, and a traceback
|
|
says nothing a sentence cannot.
|
|
"""
|
|
frames, actions, current = [], [], None
|
|
try:
|
|
text = Path(path).read_text()
|
|
except OSError as problem:
|
|
sys.exit(f"ui-trace: cannot read {path}: {problem.strerror}")
|
|
for line in text.splitlines():
|
|
if line.startswith("F "):
|
|
_, _, at = line.split(" ", 2)
|
|
current = (int(at), [])
|
|
frames.append(current)
|
|
elif line.startswith("N\t"):
|
|
parts = line.split("\t")
|
|
# A label may itself be empty, so pad rather than trusting the count.
|
|
parts += [""] * (11 - len(parts))
|
|
if current:
|
|
current[1].append(Node(parts))
|
|
elif line.startswith("A "):
|
|
at, what = line[2:].split("\t", 1)
|
|
actions.append((int(at), what))
|
|
return frames, actions
|
|
|
|
|
|
def keyed(nodes, pattern):
|
|
"""Selected nodes by a stable key: the label, plus an index when repeated."""
|
|
seen, out = {}, {}
|
|
for node in nodes:
|
|
if pattern and not pattern.search(node.haystack()):
|
|
continue
|
|
count = seen.get(node.label, 0)
|
|
seen[node.label] = count + 1
|
|
out[node.label if count == 0 else f"{node.label} #{count + 1}"] = node
|
|
return out
|
|
|
|
|
|
def sizes(frames, pattern):
|
|
"""{key: set of (width, height)} -- see [summarise] for why this is tracked."""
|
|
seen = {}
|
|
for _, nodes in frames:
|
|
for key, node in keyed(nodes, pattern).items():
|
|
box = node.box
|
|
seen.setdefault(key, set()).add((box[2] - box[0], box[3] - box[1]))
|
|
return seen
|
|
|
|
|
|
def series(frames, pattern, field):
|
|
"""{key: [(t, value or None)]} over every frame, for the chosen field."""
|
|
pick = {"top": lambda b: b[1], "bottom": lambda b: b[3],
|
|
"left": lambda b: b[0], "right": lambda b: b[2],
|
|
"box": lambda b: b}[field]
|
|
tracks, order = {}, []
|
|
for index, (at, nodes) in enumerate(frames):
|
|
present = keyed(nodes, pattern)
|
|
for key, node in present.items():
|
|
if key not in tracks:
|
|
# Backfilled as absent, so every track is one value per frame and
|
|
# a row can be read across by index. An element that appears
|
|
# part-way through is the common case, not the exotic one.
|
|
tracks[key] = [(frames[i][0], None) for i in range(index)]
|
|
order.append(key)
|
|
tracks[key].append((at, pick(node.box)))
|
|
for key in tracks:
|
|
if key not in present:
|
|
tracks[key].append((at, None))
|
|
return order, tracks
|
|
|
|
|
|
def render(value):
|
|
if value is None:
|
|
return "-"
|
|
if isinstance(value, tuple):
|
|
return "{},{}..{},{}".format(*value)
|
|
return str(value)
|
|
|
|
|
|
def cap(rows, limit):
|
|
"""The first [limit] rows, saying how many were left out.
|
|
|
|
Every listing here shortens the same way, because the caller is usually an
|
|
agent with a context window and a screen has hundreds of nodes.
|
|
"""
|
|
if limit <= 0 or len(rows) <= limit:
|
|
return rows
|
|
print(f" (showing {limit} of {len(rows)}; --limit 0 for all)")
|
|
return rows[:limit]
|
|
|
|
|
|
def cmd_elements(args):
|
|
frames, _ = parse(args.trace)
|
|
counts = {}
|
|
for _, nodes in frames:
|
|
for node in nodes:
|
|
# A node whose only name is its class name names nothing -- a screen has
|
|
# hundreds of those and listing them is the noise this tool exists to cut.
|
|
if not args.all and not (node.text or node.desc or node.rid):
|
|
continue
|
|
entry = counts.setdefault(node.label, [0, node.cls, node.rid, node.flags])
|
|
entry[0] += 1
|
|
ranked = sorted(counts.items(), key=lambda kv: -kv[1][0])
|
|
print(f"{len(counts)} named labels over {len(frames)} frames"
|
|
+ ("" if args.all else " (--all also lists unnamed structure)"))
|
|
for label, (count, cls, rid, flags) in cap(ranked, args.limit):
|
|
mark = f" [{flags}]" if flags != "-" else ""
|
|
print(f" {count:5d}x {label[:44]:<44} {cls}{mark}"
|
|
+ (f" {rid.split('/')[-1]}" if rid else ""))
|
|
|
|
|
|
def cmd_show(args):
|
|
frames, actions = parse(args.trace)
|
|
if not frames:
|
|
sys.exit("ui-trace: no frames in that trace")
|
|
pattern = re.compile(args.match) if args.match else None
|
|
order, tracks = series(frames, pattern, args.field)
|
|
if not pattern:
|
|
summarise(order, tracks, sizes(frames, pattern), actions, args)
|
|
return
|
|
timeline(frames, order, tracks, actions, args)
|
|
|
|
|
|
def summarise(order, tracks, shapes, actions, args):
|
|
"""What moved -- the question a trace is usually recorded to answer.
|
|
|
|
Everything that held still is dropped, because a screen is mostly things
|
|
that held still and reading them is the cost this tool exists to avoid.
|
|
"""
|
|
for at, what in actions:
|
|
print(f" action t={at}ms {what}")
|
|
moved = []
|
|
for key in order:
|
|
points = [(t, v) for t, v in tracks[key] if v is not None]
|
|
if not points:
|
|
continue
|
|
values = [v for _, v in points]
|
|
if len(set(values)) > 1:
|
|
moved.append((key, points))
|
|
total = len(order)
|
|
print(f"{len(moved)} of {total} elements changed {args.field} during the trace")
|
|
for key, points in cap(moved, args.limit):
|
|
values = [v for _, v in points]
|
|
changes = [(t, v) for i, (t, v) in enumerate(points)
|
|
if i == 0 or v != points[i - 1][1]]
|
|
span = f"t={changes[1][0]}..{changes[-1][0]}ms" if len(changes) > 1 else ""
|
|
net = values[-1] - values[0] if not isinstance(values[0], tuple) else None
|
|
arrow = f"{render(values[0])} -> {render(values[-1])}"
|
|
delta = f" ({net:+d})" if net is not None else ""
|
|
# A label is only a name, and two different nodes can share one -- a text
|
|
# and the padded control wrapping it both read as their text. When the
|
|
# size changes too, the two readings are probably not the same node, and
|
|
# the move is partly the difference between them rather than travel.
|
|
shape = shapes.get(key, set())
|
|
note = f" [size changed {len(shape)}x -- may be different nodes]" if len(shape) > 1 else ""
|
|
print(f" {key[:40]:<40} {arrow}{delta} {len(changes) - 1} steps {span}{note}")
|
|
if not moved:
|
|
print(" (nothing moved)")
|
|
|
|
|
|
def timeline(frames, order, tracks, actions, args):
|
|
"""A row per change, not a row per frame.
|
|
|
|
Consecutive frames that say the same thing are one row with a time range:
|
|
at 60Hz a settled second is sixty identical rows, and the reader wants the
|
|
moment it stopped being settled.
|
|
"""
|
|
# "Nothing matched" and "matched but never moved" are different answers, and
|
|
# an empty table says neither of them.
|
|
if not order:
|
|
print(f" nothing matched /{args.match}/ in any of {len(frames)} frames."
|
|
f" Try `ui-trace elements` to see what is there.")
|
|
return
|
|
if len(order) > args.max_columns:
|
|
print(f" {len(order)} elements match, which is too many to read across."
|
|
f" Narrowing to the first {args.max_columns}; use a tighter -m,"
|
|
f" or --max-columns to widen.")
|
|
order = order[:args.max_columns]
|
|
width = max(12, max((len(k) for k in order), default=12))
|
|
width = min(width, 24)
|
|
columns = [k[:width] for k in order]
|
|
print(" " + "t (ms)".rjust(13) + " | " + " | ".join(c.ljust(width) for c in columns))
|
|
print(" " + "-" * 13 + "-+-" + "-+-".join("-" * width for _ in columns))
|
|
pending = list(actions)
|
|
previous, start, last = None, None, None
|
|
rows = [[t for t, _ in tracks[order[0]]]] if order else [[]]
|
|
|
|
def flush():
|
|
if previous is None:
|
|
return
|
|
label = f"{start}" if start == last else f"{start}-{last}"
|
|
print(" " + label.rjust(13) + " | "
|
|
+ " | ".join(render(v).ljust(width) for v in previous))
|
|
|
|
rows_out = 0
|
|
for index, (at, _) in enumerate(frames):
|
|
values = tuple(tracks[k][index][1] for k in order)
|
|
while pending and pending[0][0] <= at:
|
|
flush()
|
|
previous = None
|
|
print(f" >>> {pending[0][1]} @ t={pending[0][0]}ms")
|
|
pending.pop(0)
|
|
if values != previous:
|
|
flush()
|
|
rows_out += 1
|
|
if args.limit > 0 and rows_out > args.limit:
|
|
print(f" ... more changes after t={at}ms (--limit 0 for all)")
|
|
return
|
|
previous, start = values, at
|
|
last = at
|
|
flush()
|
|
for at, what in pending:
|
|
print(f" >>> {what} @ t={at}ms")
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(
|
|
prog="ui-trace", description=__doc__,
|
|
formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
subs = parser.add_subparsers(dest="command", required=True)
|
|
|
|
rec = subs.add_parser("record", help="record a trace from a device")
|
|
rec.add_argument("-s", "--serial", help="adb device serial")
|
|
rec.add_argument("-d", "--duration", type=int, default=3000, help="ms to record")
|
|
rec.add_argument("-i", "--interval", type=int, default=16,
|
|
help="ms between samples (0 = as fast as possible)")
|
|
rec.add_argument("--do", action="append", default=[], metavar="ACTION",
|
|
help="'wait MS' | 'tap X Y' | 'swipe X1 Y1 X2 Y2 [MS]', repeatable")
|
|
rec.add_argument("-o", "--out", help="where to save the trace")
|
|
rec.add_argument("-m", "--match", help="show a timeline for these afterwards")
|
|
rec.add_argument("--field", default="top",
|
|
choices=["top", "bottom", "left", "right", "box"])
|
|
rec.add_argument("--max-columns", type=int, default=6)
|
|
rec.add_argument("--limit", type=int, default=10, help="max rows printed; 0 for all")
|
|
|
|
for name, help_text in [("show", "what moved, or a timeline with -m"),
|
|
("elements", "every label in a trace, to pick from")]:
|
|
sub = subs.add_parser(name, help=help_text)
|
|
sub.add_argument("trace")
|
|
if name == "show":
|
|
sub.add_argument("-m", "--match", help="regex over label, id, class, text")
|
|
sub.add_argument("--field", default="top",
|
|
choices=["top", "bottom", "left", "right", "box"])
|
|
sub.add_argument("--max-columns", type=int, default=6)
|
|
sub.add_argument("--limit", type=int, default=10,
|
|
help="max rows printed; 0 for all")
|
|
else:
|
|
sub.add_argument("--limit", type=int, default=20,
|
|
help="max rows printed; 0 for all")
|
|
sub.add_argument("--all", action="store_true",
|
|
help="include nodes with no name of their own")
|
|
|
|
args = parser.parse_args()
|
|
if args.command == "record":
|
|
out = record(args)
|
|
args.trace = out
|
|
cmd_show(args)
|
|
elif args.command == "show":
|
|
cmd_show(args)
|
|
else:
|
|
cmd_elements(args)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|