device.py (20646B)
1 # This file is part of GNU Taler 2 # (C) 2026 Taler Systems S.A. 3 # 4 # GNU Taler is free software; you can redistribute it and/or modify it under the 5 # terms of the GNU General Public License as published by the Free Software 6 # Foundation; either version 3, or (at your option) any later version. 7 # 8 # GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 9 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 10 # A PARTICULAR PURPOSE. See the GNU General Public License for more details. 11 # 12 # You should have received a copy of the GNU General Public License along with 13 # GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 14 """Thin adb wrapper: one emulator, seen through the accessibility tree. 15 16 The wallet is almost entirely Jetpack Compose and carries no testTags, so the 17 driver addresses widgets through the semantics the app already exposes: text, 18 content-description and bounds. Everything here is therefore black-box; the 19 only app-specific knowledge is the package name. 20 """ 21 22 from __future__ import annotations 23 24 import re 25 import shlex 26 import subprocess 27 import time 28 import xml.etree.ElementTree as ET 29 from dataclasses import dataclass, field 30 from typing import Iterable, Optional 31 32 ADB = "/opt/android-sdk/platform-tools/adb" 33 PKG = "net.taler.wallet.fdroid.debug" 34 ACTIVITY = f"{PKG}/net.taler.wallet.main.MainActivity" 35 36 BOUNDS_RE = re.compile(r"\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]") 37 38 39 @dataclass(frozen=True) 40 class Node: 41 """One node of the accessibility tree, flattened.""" 42 43 cls: str 44 text: str 45 desc: str 46 rid: str 47 clickable: bool 48 scrollable: bool 49 editable: bool 50 checkable: bool 51 checked: bool 52 enabled: bool 53 bounds: tuple[int, int, int, int] 54 55 @property 56 def center(self) -> tuple[int, int]: 57 x1, y1, x2, y2 = self.bounds 58 return (x1 + x2) // 2, (y1 + y2) // 2 59 60 @property 61 def label(self) -> str: 62 return self.text or self.desc 63 64 @property 65 def area(self) -> int: 66 x1, y1, x2, y2 = self.bounds 67 return max(0, x2 - x1) * max(0, y2 - y1) 68 69 def __str__(self) -> str: 70 kind = self.cls.rsplit(".", 1)[-1] 71 flags = "".join( 72 f for f, on in (("C", self.clickable), ("S", self.scrollable), 73 ("E", self.editable), ("x", not self.enabled)) 74 if on 75 ) 76 return f"{kind}{'[' + flags + ']' if flags else ''} {self.label!r} @{self.center}" 77 78 79 @dataclass 80 class Screen: 81 """A parsed UI dump plus the cheap derived views the driver needs.""" 82 83 nodes: list[Node] = field(default_factory=list) 84 activity: str = "" 85 86 def labelled(self) -> list[Node]: 87 return [n for n in self.nodes if n.label.strip()] 88 89 def tappable(self) -> list[Node]: 90 """Clickable nodes, plus labelled leaves (Compose often marks only an 91 ancestor clickable, so a text node's own box is the better tap target).""" 92 out = [n for n in self.nodes if n.clickable and n.enabled and n.area > 0] 93 seen = {n.bounds for n in out} 94 for n in self.labelled(): 95 if n.bounds not in seen and n.area > 0: 96 out.append(n) 97 seen.add(n.bounds) 98 return out 99 100 def editable(self) -> list[Node]: 101 return [n for n in self.nodes if n.editable and n.enabled] 102 103 def texts(self) -> list[str]: 104 return [n.label.strip() for n in self.labelled()] 105 106 def tap_target(self, node: Node) -> Node: 107 """The node that actually reacts when the user aims at `node`. 108 109 Three shapes occur in this app: the labelled node is itself clickable; 110 the label sits inside a clickable ancestor (ordinary Compose); or the 111 label is a separate TextView *underneath* an unlabelled Button, which 112 is how the main screen's Send/Request/Withdraw/Deposit buttons are 113 built. The last case needs a neighbour search, not a containment 114 search, or the tap lands on nothing at all. 115 """ 116 if node.clickable and node.enabled: 117 return node 118 cx, cy = node.center 119 clickables = [n for n in self.nodes if n.clickable and n.enabled and n.area > 0] 120 containing = [n for n in clickables 121 if n.bounds[0] <= cx <= n.bounds[2] 122 and n.bounds[1] <= cy <= n.bounds[3]] 123 if containing: 124 return min(containing, key=lambda n: n.area) 125 # A clickable node directly above or below, overlapping horizontally. 126 x1, y1, x2, y2 = node.bounds 127 128 def neighbour_distance(n: Node) -> Optional[int]: 129 if n.bounds[2] < x1 or n.bounds[0] > x2: 130 return None 131 if n.bounds[3] <= y1: 132 return y1 - n.bounds[3] 133 if n.bounds[1] >= y2: 134 return n.bounds[1] - y2 135 return 0 136 137 scored = [(d, n) for n in clickables 138 if (d := neighbour_distance(n)) is not None and d <= 120] 139 if scored: 140 return min(scored, key=lambda row: row[0])[1] 141 return node 142 143 def unnamed_clickables(self) -> list[Node]: 144 """Clickable nodes a screen reader cannot announce. 145 146 A clickable node with no text of its own is fine when the label sits 147 *inside* it: Compose merges the semantics and TalkBack reads the child. 148 What is not fine is a label that is only a neighbour, which is how the 149 main screen's action buttons are built. Only the latter are returned. 150 """ 151 labelled = [n for n in self.nodes if n.label.strip() and n.area > 0] 152 out = [] 153 for node in self.nodes: 154 if not (node.clickable and node.enabled and node.area > 0): 155 continue 156 if node.label.strip(): 157 continue 158 x1, y1, x2, y2 = node.bounds 159 if x2 - x1 >= 600 and y2 - y1 >= 600: 160 continue # a full-screen container, not a control 161 contains_label = any( 162 x1 <= n.bounds[0] and y1 <= n.bounds[1] 163 and n.bounds[2] <= x2 and n.bounds[3] <= y2 164 for n in labelled 165 ) 166 if not contains_label: 167 out.append(node) 168 return out 169 170 def find(self, pattern: str) -> Optional[Node]: 171 rx = re.compile(pattern, re.I) 172 for n in self.nodes: 173 if n.label and rx.search(n.label): 174 return n 175 return None 176 177 def signature(self) -> str: 178 """Stable-ish identity of a screen, for novelty tracking and oracles. 179 180 Only the set of labels and the shape of the interactive nodes go in, so 181 the same screen with a different balance still matches itself. 182 """ 183 labels = sorted({re.sub(r"\d+[.,]?\d*", "#", t) for t in self.texts()}) 184 shape = f"{len(self.tappable())}/{len(self.editable())}" 185 return f"{self.activity}|{shape}|{'|'.join(labels)}" 186 187 def __str__(self) -> str: 188 return "\n".join(str(n) for n in self.labelled()) 189 190 191 class Device: 192 def __init__(self, serial: str = "emulator-5554", pkg: str = PKG): 193 self.serial = serial 194 self.pkg = pkg 195 self._sdk_int: Optional[int] = None 196 self._size: Optional[tuple[int, int]] = None 197 198 # -- plumbing --------------------------------------------------------- 199 200 def adb(self, *args: str, timeout: int = 60, check: bool = True) -> str: 201 proc = subprocess.run( 202 [ADB, "-s", self.serial, *args], 203 capture_output=True, text=True, timeout=timeout, 204 ) 205 if check and proc.returncode != 0: 206 raise RuntimeError(f"adb {' '.join(args)} failed: {proc.stderr.strip()}") 207 return proc.stdout 208 209 def shell(self, cmd: str, timeout: int = 60, check: bool = True) -> str: 210 return self.adb("shell", cmd, timeout=timeout, check=check) 211 212 # -- observation ------------------------------------------------------ 213 214 @property 215 def sdk_int(self) -> int: 216 """The device's API level, read once. 217 218 Scenarios need this because the *harness* has version floors of its 219 own: per-app language is API 33+, for instance, so a scenario that 220 changes it on an older device is testing adb, not the wallet. 221 """ 222 if self._sdk_int is None: 223 out = self.shell("getprop ro.build.version.sdk", check=False) 224 try: 225 self._sdk_int = int(out.strip() or 0) 226 except ValueError: 227 self._sdk_int = 0 228 return self._sdk_int 229 230 def current_activity(self) -> str: 231 out = self.shell("dumpsys activity activities | grep -m1 ResumedActivity", check=False) 232 m = re.search(r"([A-Za-z0-9_.]+/[A-Za-z0-9_.]+)", out) 233 return m.group(1) if m else "" 234 235 def dump(self, retries: int = 3) -> Screen: 236 """Read the accessibility tree. 237 238 uiautomator fails while the UI is still settling ("could not get idle 239 state"), which is routine right after a tap, so this retries. 240 """ 241 xml = "" 242 for attempt in range(retries): 243 out = self.shell("uiautomator dump /sdcard/ui.xml", check=False) 244 if "dumped" in out.lower(): 245 xml = self.adb("exec-out", "cat", "/sdcard/ui.xml", check=False) 246 if xml.lstrip().startswith("<?xml"): 247 break 248 time.sleep(1 + attempt) 249 if not xml.lstrip().startswith("<?xml"): 250 return Screen(activity=self.current_activity()) 251 return self._parse(xml) 252 253 def _parse(self, xml: str) -> Screen: 254 screen = Screen(activity=self.current_activity()) 255 try: 256 root = ET.fromstring(xml) 257 except ET.ParseError: 258 return screen 259 for el in root.iter("node"): 260 m = BOUNDS_RE.match(el.get("bounds", "")) 261 if not m: 262 continue 263 cls = el.get("class", "") 264 screen.nodes.append(Node( 265 cls=cls, 266 text=el.get("text", ""), 267 desc=el.get("content-desc", ""), 268 rid=el.get("resource-id", ""), 269 clickable=el.get("clickable") == "true", 270 scrollable=el.get("scrollable") == "true", 271 editable=el.get("class", "").endswith("EditText") 272 or el.get("focusable") == "true" and "EditText" in cls, 273 checkable=el.get("checkable") == "true", 274 checked=el.get("checked") == "true", 275 enabled=el.get("enabled") == "true", 276 bounds=tuple(int(v) for v in m.groups()), # type: ignore[arg-type] 277 )) 278 return screen 279 280 def screenshot(self, path: str) -> None: 281 png = subprocess.run([ADB, "-s", self.serial, "exec-out", "screencap", "-p"], 282 capture_output=True, timeout=60).stdout 283 with open(path, "wb") as f: 284 f.write(png) 285 286 def logcat(self, clear: bool = False, lines: Optional[int] = None) -> str: 287 """Read the log, or clear it. 288 289 `lines` bounds the read to the most recent entries. Reading the whole 290 buffer costs seconds once it has filled up, which is far too slow to 291 do after every action in an exploration. 292 """ 293 if clear: 294 self.adb("logcat", "-c", check=False) 295 return "" 296 args = ["logcat", "-d"] 297 if lines: 298 args += ["-t", str(lines)] 299 return self.adb(*args, timeout=120, check=False) 300 301 # -- acting ----------------------------------------------------------- 302 303 def tap(self, x: int, y: int) -> None: 304 self.shell(f"input tap {x} {y}") 305 306 def tap_node(self, node: Node, screen: Optional[Screen] = None) -> None: 307 """Tap a node, or whatever clickable element really serves it.""" 308 target = screen.tap_target(node) if screen is not None else node 309 x, y = target.center 310 self.tap(x, y) 311 312 def long_press(self, node: Node, ms: int = 800) -> None: 313 """Hold a finger on a node long enough for a long-press gesture. 314 315 A zero-distance `input swipe` is what works: Compose's 316 `combinedClickable` sees it as a press that never moved. Moving even 317 two pixels turns it into a drag and the long press is cancelled, and 318 two separate `input motionevent` calls do not form one gesture at all 319 -- both were tried on a live transaction row, and only this registers. 320 """ 321 x, y = node.center 322 self.shell(f"input swipe {x} {y} {x} {y} {ms}") 323 324 def type_text(self, s: str) -> None: 325 """Type into the focused field. 326 327 "input text" maps each character through a KeyCharacterMap and throws 328 NullPointerException on anything it cannot map, so non-ASCII text goes 329 through the clipboard instead (which needs the sim build's SimHooks). 330 """ 331 if not s: 332 return 333 if not s.isascii() or len(s) > 200: 334 # Long strings are also pasted: "input text" sends them one 335 # keystroke at a time, which takes minutes for a few thousand 336 # characters and tests nothing extra. 337 self.paste_text(s) 338 return 339 # Shell-quote one chunk at a time; a space has to be a keyevent because 340 # "input text" splits its arguments on it. 341 for chunk in re.split(r"( )", s): 342 if not chunk: 343 continue 344 if chunk == " ": 345 self.shell("input keyevent 62") 346 else: 347 self.shell(f"input text {shlex.quote(chunk)}", check=False) 348 349 def paste_text(self, s: str) -> None: 350 """Put text on the clipboard through SimHooks, then paste it.""" 351 res = self.shell( 352 f"am broadcast -a net.taler.wallet.sim.SET_CLIPBOARD " 353 f"-n {self.pkg}/net.taler.wallet.sim.SimHooks --es text {shlex.quote(s)}", 354 check=False, 355 ) 356 if "Broadcast completed" not in res: 357 raise RuntimeError( 358 f"clipboard hook unavailable (is this the fdroidSim APK?): {res.strip()[:200]}" 359 ) 360 self.shell("input keyevent KEYCODE_PASTE") 361 362 def key(self, keycode: str) -> None: 363 self.shell(f"input keyevent {keycode}") 364 365 def back(self) -> None: 366 self.key("KEYCODE_BACK") 367 368 def size(self) -> tuple[int, int]: 369 """Current display size in pixels, cached per orientation.""" 370 if self._size is None: 371 out = self.shell("wm size") 372 m = re.search(r"Override size: (\d+)x(\d+)", out) or \ 373 re.search(r"Physical size: (\d+)x(\d+)", out) 374 w, h = (int(m.group(1)), int(m.group(2))) if m else (1080, 2400) 375 # wm size always reports the natural orientation, so swap when the 376 # device is rotated. 377 rotation = self.shell("settings get system user_rotation", 378 check=False).strip() 379 if rotation in ("1", "3"): 380 w, h = h, w 381 self._size = (w, h) 382 return self._size 383 384 def scroll(self, down: bool = True, screen: Optional[Screen] = None) -> None: 385 """Swipe inside the scrollable area of the current screen. 386 387 Fixed coordinates break as soon as the device is rotated or the layout 388 changes, so the gesture is derived from the scrollable node when there 389 is one and from the display size otherwise. 390 """ 391 width, height = self.size() 392 area = None 393 if screen is not None: 394 scrollables = [n for n in screen.nodes if n.scrollable and n.area > 0] 395 if scrollables: 396 area = max(scrollables, key=lambda n: n.area).bounds 397 if area is None: 398 area = (0, height // 8, width, height - height // 8) 399 x1, y1, x2, y2 = area 400 x = (x1 + x2) // 2 401 near, far = y1 + (y2 - y1) // 6, y2 - (y2 - y1) // 6 402 start, end = (far, near) if down else (near, far) 403 # 800 ms makes this a drag rather than a fling: a fling carries on 404 # under its own momentum and can scroll a whole row past the next dump. 405 self.shell(f"input swipe {x} {start} {x} {end} 800") 406 407 def portrait(self) -> None: 408 """Undo any rotation left behind by an earlier episode. 409 410 user_rotation is a system setting, so "pm clear" on the app does not 411 reset it and a landscape device silently invalidates every gesture 412 computed for portrait. 413 """ 414 self.shell("settings put system accelerometer_rotation 0") 415 self.shell("settings put system user_rotation 0") 416 self._size = None 417 418 def rotate(self, landscape: bool) -> None: 419 self.shell("settings put system accelerometer_rotation 0") 420 self.shell(f"settings put system user_rotation {1 if landscape else 0}") 421 self._size = None 422 423 # -- app lifecycle and entry points ----------------------------------- 424 425 def launch(self) -> None: 426 self.shell(f"am start -W -n {ACTIVITY}", timeout=120) 427 428 def stop(self) -> None: 429 self.shell(f"am force-stop {self.pkg}") 430 431 def kill(self) -> None: 432 """Process death without a clean shutdown, to test state restoration.""" 433 self.shell(f"am kill {self.pkg}") 434 435 def clear_data(self) -> None: 436 self.shell(f"pm clear {self.pkg}") 437 438 def grant_camera(self) -> None: 439 """Re-grant the camera permission, which "pm clear" takes away.""" 440 self.shell(f"pm grant {self.pkg} android.permission.CAMERA", check=False) 441 442 def send_uri(self, uri: str) -> None: 443 """Hand a Taler URI to the wallet. 444 445 ACTION_SEND/text/plain is used rather than a VIEW intent because the 446 manifest's VIEW filter covers taler:// and payto:// but not the 447 taler+http:// form that a local http deployment hands out. 448 """ 449 self.shell( 450 "am start -a android.intent.action.SEND -t text/plain " 451 f"-n {ACTIVITY} --es android.intent.extra.TEXT {uri!r}", 452 timeout=120, 453 ) 454 455 def send_ndef(self, uri: str) -> None: 456 """Deliver a URI the way a tapped NFC tag does. 457 458 ACTION_NDEF_DISCOVERED carries its URI in a Parcelable NdefMessage, 459 which `am start` cannot build, so the sim build's SimHooks receiver 460 constructs it in-process. It deliberately leaves `intent.data` unset, 461 which is the branch MainActivity falls back to -- the one no scenario 462 had ever reached. 463 """ 464 self.shell( 465 f"am broadcast -a net.taler.wallet.sim.SEND_NDEF " 466 f"-n {self.pkg}/net.taler.wallet.sim.SimHooks --es uri {uri!r}", 467 timeout=120, 468 ) 469 470 # -- waiting and convenience ------------------------------------------ 471 472 def wait_for(self, pattern: str, timeout: int = 60, poll: float = 1.5) -> Screen: 473 """Poll the UI until some label matches, and return that screen. 474 475 Raises TimeoutError with the last screen's labels attached, which is 476 what makes a failing scenario readable afterwards. 477 """ 478 deadline = time.monotonic() + timeout 479 last = Screen() 480 while time.monotonic() < deadline: 481 last = self.dump() 482 if last.find(pattern): 483 return last 484 time.sleep(poll) 485 raise TimeoutError( 486 f"no label matching {pattern!r} within {timeout}s; " 487 f"screen showed: {last.texts()}" 488 ) 489 490 def tap_text(self, pattern: str, timeout: int = 30) -> Screen: 491 """Wait for a label, tap what serves it, and return that screen.""" 492 screen = self.wait_for(pattern, timeout=timeout) 493 node = screen.find(pattern) 494 if node is None: 495 # The screen changed between matching and tapping; say so plainly 496 # rather than failing with a bare assertion. 497 raise RuntimeError(f"{pattern!r} matched but was gone before the tap; " 498 f"screen now: {self.dump().texts()}") 499 self.tap_node(node, screen) 500 return screen 501 502 def view_uri(self, uri: str) -> None: 503 """Deliver a URI the way a browser link or QR deep link would.""" 504 self.shell(f"am start -a android.intent.action.VIEW -d {uri!r}", timeout=120, check=False) 505 506 507 if __name__ == "__main__": 508 import sys 509 d = Device(sys.argv[1] if len(sys.argv) > 1 else "emulator-5554") 510 s = d.dump() 511 print(f"activity: {s.activity}") 512 print(f"nodes: {len(s.nodes)} labelled: {len(s.labelled())} " 513 f"tappable: {len(s.tappable())} editable: {len(s.editable())}") 514 print(s) 515 print("signature:", s.signature()[:200])