device.py (35905B)
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 terminal is Fragments and XML views with a Compose navigation shell on top, 17 and carries no testTags anywhere, so widgets are addressed through the 18 semantics the app already exposes -- text, content-description and bounds. 19 Everything here is black-box; the only app-specific knowledge is the package 20 name and the one activity. 21 22 Two things differ from the wallet's equivalent and matter everywhere: 23 24 * **The terminal is no longer landscape-locked.** It declared 25 `screenOrientation="landscape"` through round three and declares `fullUser` 26 on master, so the window follows `user_rotation` and portrait is a live set 27 of layouts. `wm size` still reports the panel and does not move when the 28 device turns. Sizes therefore come from the view hierarchy's own root 29 bounds, and only fall back to `wm size`. 30 * **A setup URI is a VIEW deep link**, not an ACTION_SEND. The manifest's 31 VIEW filter covers the `taler-pos` scheme, which is the only scheme the 32 terminal accepts, so the ordinary deep-link path is also the real one. 33 """ 34 35 from __future__ import annotations 36 37 import os 38 import re 39 import shlex 40 import subprocess 41 import time 42 import xml.etree.ElementTree as ET 43 from dataclasses import dataclass, field 44 from typing import Optional 45 46 ADB = os.environ.get("POS_ADB", "/opt/android-sdk/platform-tools/adb") 47 48 # The emulator console port a worker gets. Deliberately *not* 5554: the wallet 49 # simulator numbers its workers from there, and on a host running both, the 50 # second harness to start does not boot anything -- the ports are taken -- it 51 # silently attaches to the other one's emulators and drives the wrong app. 52 # Neither side notices, because adb reports a device either way. 53 PORT_BASE = int(os.environ.get("POS_PORT_BASE", "5584")) 54 PKG = os.environ.get("POS_PKG", "net.taler.merchantpos") 55 ACTIVITY = f"{PKG}/{PKG}.MainActivity" 56 HOOKS = f"{PKG}/{PKG}.sim.PosSimHooks" 57 58 BOUNDS_RE = re.compile(r"\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]") 59 60 61 def serial_for(worker: int | str | None = None) -> str: 62 """The adb serial for a worker index. 63 64 `POS_SERIAL` overrides it outright, for attaching to an emulator somebody 65 else started. 66 """ 67 if os.environ.get("POS_SERIAL"): 68 return os.environ["POS_SERIAL"] 69 if worker is None: 70 worker = os.environ.get("POS_WORKER", "0") 71 return f"emulator-{PORT_BASE + 2 * int(worker)}" 72 73 74 @dataclass(frozen=True) 75 class Node: 76 """One node of the accessibility tree, flattened.""" 77 78 cls: str 79 text: str 80 desc: str 81 rid: str 82 clickable: bool 83 scrollable: bool 84 editable: bool 85 checkable: bool 86 checked: bool 87 enabled: bool 88 selected: bool 89 bounds: tuple[int, int, int, int] 90 91 @property 92 def center(self) -> tuple[int, int]: 93 x1, y1, x2, y2 = self.bounds 94 return (x1 + x2) // 2, (y1 + y2) // 2 95 96 @property 97 def label(self) -> str: 98 return self.text or self.desc 99 100 @property 101 def area(self) -> int: 102 x1, y1, x2, y2 = self.bounds 103 return max(0, x2 - x1) * max(0, y2 - y1) 104 105 def __str__(self) -> str: 106 kind = self.cls.rsplit(".", 1)[-1] 107 flags = "".join( 108 f for f, on in (("C", self.clickable), ("S", self.scrollable), 109 ("E", self.editable), ("v", self.checked), 110 ("x", not self.enabled)) 111 if on 112 ) 113 rid = self.rid.rsplit("/", 1)[-1] 114 return (f"{kind}{'[' + flags + ']' if flags else ''} " 115 f"{self.label!r}{'#' + rid if rid else ''} @{self.center}") 116 117 118 @dataclass 119 class Screen: 120 """A parsed UI dump plus the cheap derived views the driver needs.""" 121 122 nodes: list[Node] = field(default_factory=list) 123 activity: str = "" 124 125 def labelled(self) -> list[Node]: 126 return [n for n in self.nodes if n.label.strip()] 127 128 def tappable(self) -> list[Node]: 129 """Clickable nodes, plus labelled leaves. 130 131 The terminal's two keypads (amount entry and the order grid) build each 132 key as a Button whose label is a child TextView, and the product cards 133 in the order grid mark only the card clickable -- so both the 134 containers and the labels have to count as tap targets for novelty 135 tracking to mean anything. 136 """ 137 out = [n for n in self.nodes if n.clickable and n.enabled and n.area > 0] 138 seen = {n.bounds for n in out} 139 for n in self.labelled(): 140 if n.bounds not in seen and n.area > 0: 141 out.append(n) 142 seen.add(n.bounds) 143 return out 144 145 def editable(self) -> list[Node]: 146 return [n for n in self.nodes if n.editable and n.enabled] 147 148 def texts(self) -> list[str]: 149 return [n.label.strip() for n in self.labelled()] 150 151 def root_bounds(self) -> Optional[tuple[int, int, int, int]]: 152 """The largest node's box, which is the window the app is drawing in.""" 153 if not self.nodes: 154 return None 155 return max(self.nodes, key=lambda n: n.area).bounds 156 157 def tap_target(self, node: Node) -> Node: 158 """The node that actually reacts when the user aims at `node`. 159 160 Three shapes occur in this app: the labelled node is itself clickable 161 (most of Compose); the label sits inside a clickable ancestor (the 162 product cards, the drawer rows); or the label is a separate TextView 163 next to an unlabelled clickable, which is how the amount keypad and the 164 history row actions are built. The last case needs a neighbour search, 165 not a containment search, or the tap lands on nothing at all. 166 """ 167 if node.clickable: 168 return node 169 cx, cy = node.center 170 # Containment is checked against *every* clickable, enabled or not. 171 # A disabled Compose Button is still a clickable node, and skipping it 172 # sent the search off to the nearest enabled neighbour -- which for 173 # the amount keypad's Charge button is a digit key three rows up. The 174 # caller then read that key's "enabled" and concluded that charging 175 # nothing was allowed, which is the opposite of what the screen does. 176 clickables = [n for n in self.nodes if n.clickable and n.area > 0] 177 containing = [n for n in clickables 178 if n.bounds[0] <= cx <= n.bounds[2] 179 and n.bounds[1] <= cy <= n.bounds[3]] 180 if containing: 181 return min(containing, key=lambda n: n.area) 182 clickables = [n for n in clickables if n.enabled] 183 x1, y1, x2, y2 = node.bounds 184 185 def neighbour_distance(n: Node) -> Optional[int]: 186 if n.bounds[2] < x1 or n.bounds[0] > x2: 187 return None 188 if n.bounds[3] <= y1: 189 return y1 - n.bounds[3] 190 if n.bounds[1] >= y2: 191 return n.bounds[1] - y2 192 return 0 193 194 scored = [(d, n) for n in clickables 195 if (d := neighbour_distance(n)) is not None and d <= 120] 196 if scored: 197 return min(scored, key=lambda row: row[0])[1] 198 return node 199 200 def unnamed_clickables(self) -> list[Node]: 201 """Clickable nodes a screen reader cannot announce. 202 203 A clickable with no text of its own is fine when the label sits 204 *inside* it: the semantics merge and TalkBack reads the child. What is 205 not fine is a label that is only a neighbour, or no label at all -- 206 which is what an icon button without a contentDescription looks like. 207 """ 208 labelled = [n for n in self.nodes if n.label.strip() and n.area > 0] 209 out = [] 210 for node in self.nodes: 211 if not (node.clickable and node.enabled and node.area > 0): 212 continue 213 if node.label.strip(): 214 continue 215 x1, y1, x2, y2 = node.bounds 216 if (x2 - x1) >= 900 and (y2 - y1) >= 600: 217 continue # a full-screen container, not a control 218 contains_label = any( 219 x1 <= n.bounds[0] and y1 <= n.bounds[1] 220 and n.bounds[2] <= x2 and n.bounds[3] <= y2 221 for n in labelled 222 ) 223 if not contains_label: 224 out.append(node) 225 return out 226 227 def find(self, pattern: str) -> Optional[Node]: 228 rx = re.compile(pattern, re.I) 229 for n in self.nodes: 230 if n.label and rx.search(n.label): 231 return n 232 return None 233 234 def find_all(self, pattern: str) -> list[Node]: 235 rx = re.compile(pattern, re.I) 236 return [n for n in self.nodes if n.label and rx.search(n.label)] 237 238 def has(self, pattern: str) -> bool: 239 return self.find(pattern) is not None 240 241 def signature(self) -> str: 242 """Stable-ish identity of a screen, for novelty tracking and oracles. 243 244 Only the set of labels and the shape of the interactive nodes go in, so 245 the same screen with a different order total still matches itself. 246 """ 247 labels = sorted({re.sub(r"\d+[.,]?\d*", "#", t) for t in self.texts()}) 248 shape = f"{len(self.tappable())}/{len(self.editable())}" 249 return f"{self.activity}|{shape}|{'|'.join(labels)}" 250 251 def __str__(self) -> str: 252 return "\n".join(str(n) for n in self.labelled()) 253 254 255 class Device: 256 def __init__(self, serial: Optional[str] = None, pkg: str = PKG): 257 serial = serial or serial_for() 258 self.serial = serial 259 self.pkg = pkg 260 self._sdk_int: Optional[int] = None 261 self._size: Optional[tuple[int, int]] = None 262 self._display: Optional[tuple[int, int]] = None 263 # Where the soft keyboard starts, learned rather than asked for: the 264 # IME is not in the accessibility dump and its window frame is the 265 # whole screen, so neither can be read directly. What can be read is 266 # the app's own window, which shrinks to the keyboard's top edge -- so 267 # the first dump taken over a resized window records it, and dialogs, 268 # whose dump covers only the dialog, use the figure from then on. 269 self._ime_top: Optional[int] = None 270 self._swdp: Optional[int] = None 271 272 # -- plumbing --------------------------------------------------------- 273 274 def adb(self, *args: str, timeout: int = 60, check: bool = True) -> str: 275 proc = subprocess.run( 276 [ADB, "-s", self.serial, *args], 277 capture_output=True, text=True, timeout=timeout, 278 ) 279 if check and proc.returncode != 0: 280 raise RuntimeError(f"adb {' '.join(args)} failed: {proc.stderr.strip()}") 281 return proc.stdout 282 283 def shell(self, cmd: str, timeout: int = 60, check: bool = True) -> str: 284 return self.adb("shell", cmd, timeout=timeout, check=check) 285 286 # -- observation ------------------------------------------------------ 287 288 @property 289 def sdk_int(self) -> int: 290 if self._sdk_int is None: 291 out = self.shell("getprop ro.build.version.sdk", check=False) 292 try: 293 self._sdk_int = int(out.strip() or 0) 294 except ValueError: 295 self._sdk_int = 0 296 return self._sdk_int 297 298 def current_activity(self) -> str: 299 out = self.shell("dumpsys activity activities | grep -m1 ResumedActivity", check=False) 300 m = re.search(r"([A-Za-z0-9_.]+/[A-Za-z0-9_.]+)", out) 301 return m.group(1) if m else "" 302 303 def dump(self, retries: int = 3) -> Screen: 304 """Read the accessibility tree. 305 306 uiautomator fails while the UI is still settling ("could not get idle 307 state"), which is routine right after a tap, so this retries. The 308 terminal makes it worse than the wallet does: the order grid animates 309 its stock badges and the payment screen re-renders a QR code every 310 second, so a dump during a payment check can need all three attempts. 311 """ 312 xml = "" 313 for attempt in range(retries): 314 out = self.shell("uiautomator dump /sdcard/ui.xml", check=False) 315 if "dumped" in out.lower(): 316 xml = self.adb("exec-out", "cat", "/sdcard/ui.xml", check=False) 317 if xml.lstrip().startswith("<?xml"): 318 break 319 time.sleep(1 + attempt) 320 if not xml.lstrip().startswith("<?xml"): 321 return Screen(activity=self.current_activity()) 322 screen = self._parse(xml) 323 # The window the app draws in is the authority on size, not wm size: 324 # a landscape-locked activity on a portrait device makes the two 325 # disagree, and every swipe computed from the wrong one misses. 326 box = screen.root_bounds() 327 if box: 328 self._size = (box[2] - box[0], box[3] - box[1]) 329 full_h = self.display_size()[1] 330 if 0 < box[3] < full_h * 0.95 and box[1] == 0: 331 self._ime_top = box[3] 332 return screen 333 334 def _parse(self, xml: str) -> Screen: 335 screen = Screen(activity=self.current_activity()) 336 try: 337 root = ET.fromstring(xml) 338 except ET.ParseError: 339 return screen 340 for el in root.iter("node"): 341 m = BOUNDS_RE.match(el.get("bounds", "")) 342 if not m: 343 continue 344 cls = el.get("class", "") 345 screen.nodes.append(Node( 346 cls=cls, 347 text=el.get("text", ""), 348 desc=el.get("content-desc", ""), 349 rid=el.get("resource-id", ""), 350 clickable=el.get("clickable") == "true", 351 scrollable=el.get("scrollable") == "true", 352 editable=cls.endswith("EditText"), 353 checkable=el.get("checkable") == "true", 354 checked=el.get("checked") == "true", 355 enabled=el.get("enabled") == "true", 356 selected=el.get("selected") == "true", 357 bounds=tuple(int(v) for v in m.groups()), # type: ignore[arg-type] 358 )) 359 return screen 360 361 def screenshot(self, path: str) -> None: 362 png = subprocess.run([ADB, "-s", self.serial, "exec-out", "screencap", "-p"], 363 capture_output=True, timeout=60).stdout 364 with open(path, "wb") as f: 365 f.write(png) 366 367 def logcat(self, clear: bool = False, lines: Optional[int] = None) -> str: 368 """Read the log, or clear it. 369 370 `lines` bounds the read to the most recent entries. Reading the whole 371 buffer costs seconds once it has filled, which is far too slow to do 372 after every action. 373 """ 374 if clear: 375 self.adb("logcat", "-c", check=False) 376 return "" 377 args = ["logcat", "-d"] 378 if lines: 379 args += ["-t", str(lines)] 380 return self.adb(*args, timeout=120, check=False) 381 382 def _physical(self) -> tuple[int, int]: 383 """What `wm size` reports: the panel, in its natural orientation.""" 384 out = self.shell("wm size") 385 m = re.search(r"Override size: (\d+)x(\d+)", out) or \ 386 re.search(r"Physical size: (\d+)x(\d+)", out) 387 return (int(m.group(1)), int(m.group(2))) if m else (1080, 2400) 388 389 def rotation(self) -> int: 390 """The device's rotation, 0-3, as the system has it.""" 391 out = self.shell("settings get system user_rotation", check=False) or "" 392 try: 393 return int(out.strip()) % 4 394 except ValueError: 395 return 0 396 397 def is_portrait(self) -> bool: 398 """Whether the app's window is currently taller than it is wide. 399 400 Derived rather than assumed. `wm size` does not move when the device 401 turns -- it reports the panel -- so the orientation is the natural one 402 rotated by `user_rotation`, and which *value* means portrait depends 403 on the panel: every AVD this harness creates is landscape-natural 404 (`emu.sh` writes the LCD geometry), a stock phone AVD is not. 405 """ 406 w, h = self._physical() 407 natural_portrait = h > w 408 quarter_turned = self.rotation() % 2 == 1 409 return natural_portrait != quarter_turned 410 411 def rotate(self, portrait: bool, timeout: float = 25.0) -> tuple[int, int]: 412 """Turn the device and wait for the app's window to follow. 413 414 The terminal used to be locked to landscape and is not any more -- 415 `android:screenOrientation` is `fullUser` on master -- so portrait is 416 a live set of layouts rather than dead code. Auto-rotation is pinned 417 off and `user_rotation` is written directly, because an emulator has 418 no accelerometer to tilt. 419 420 Which value means portrait depends on the panel's natural 421 orientation, so both are *tried* rather than worked out: a value 422 computed from `wm size` was right in principle and wrong in practice 423 often enough to turn a rotation failure into a harness error for 424 every scenario that followed. The window is the only authority, and 425 it is asked. 426 427 Returns the window size afterwards, or raises if neither value turned 428 it: a caller that thinks it is testing portrait and is not would 429 report every landscape layout under a portrait name. 430 """ 431 self.shell("settings put system accelerometer_rotation 0", check=False) 432 w, h = self._physical() 433 natural_portrait = h > w 434 first = 0 if (natural_portrait == portrait) else 1 435 # Each value gets its own budget. Giving up on one after a single 436 # dump was wrong twice over: the first dump after a write is often 437 # taken before the window manager has resized anything, so a correct 438 # value looked wrong, and the "other" value was then written on top of 439 # it -- turning the device away from what was asked for. 440 per_value = max(6.0, timeout / 2) 441 for value in (first, 1 - first): 442 self.shell(f"settings put system user_rotation {value}", 443 check=False) 444 deadline = time.monotonic() + per_value 445 while time.monotonic() < deadline: 446 time.sleep(1.0) 447 self._size = self._display = None 448 try: 449 box = self.dump().root_bounds() 450 except Exception: 451 continue # a dump during a rotation can come back torn 452 if box is None: 453 continue 454 width, height = box[2] - box[0], box[3] - box[1] 455 if (height > width) == portrait: 456 self._size = (width, height) 457 return self._size 458 self._size = self._display = None 459 raise RuntimeError( 460 f"the window did not turn to {'portrait' if portrait else 'landscape'} " 461 f"within {timeout}s (user_rotation={self.rotation()}, " 462 f"physical={w}x{h})") 463 464 def size(self) -> tuple[int, int]: 465 """The app window's size in pixels. 466 467 A dump fills this in; without one, fall back to the panel's size 468 turned to match the current rotation. It used to be forced landscape 469 unconditionally, which was right while the terminal was locked to 470 landscape and wrong the moment it stopped being. 471 """ 472 if self._size is None: 473 w, h = self._physical() 474 if (h > w) != self.is_portrait(): 475 w, h = h, w 476 self._size = (w, h) 477 return self._size 478 479 def smallest_width_dp(self) -> int: 480 """The `smallestScreenWidthDp` five of the terminal's screens branch on. 481 482 Read from the device rather than guessed from the AVD profile: the 483 profile does not decide it, the LCD geometry written into the AVD 484 does, and a harness that assumed "tablet" ran half the layouts it 485 thought it was covering. 486 """ 487 if self._swdp is None: 488 width, height = self.display_size() 489 density = 160 490 out = self.shell("wm density", check=False) or "" 491 m = re.search(r"(?:Override|Physical) density:\s*(\d+)", out) 492 if m: 493 density = int(m.group(1)) 494 self._swdp = int(min(width, height) * 160 / max(density, 1)) 495 return self._swdp 496 497 def is_phone_layout(self) -> bool: 498 """True where the terminal picks its phone layouts.""" 499 return self.smallest_width_dp() < 720 500 501 def display_size(self) -> tuple[int, int]: 502 """The physical display, turned to match the current rotation. 503 504 `size()` answers with the app's window, which the keyboard shrinks and 505 a dialog replaces entirely; this one only moves when the device does. 506 """ 507 if self._display is None: 508 w, h = self._physical() 509 if (h > w) != self.is_portrait(): 510 w, h = h, w 511 self._display = (w, h) 512 return self._display 513 514 IME_INSET = re.compile( 515 r"InsetsSource[^\n]*type=ime[^\n]*frame=\[(\d+),(\d+)\]\[(\d+),(\d+)\]" 516 r"[^\n]*visible=true") 517 518 def ime_top(self) -> Optional[int]: 519 """The y where the soft keyboard starts, or None if it is not up. 520 521 The window manager publishes it as an inset, which is the only exact 522 source: the keyboard is not in the accessibility dump and its own 523 window frame covers the whole screen. A dump taken over a window the 524 keyboard resized gives the same number and is kept as a fallback, 525 because an app whose screens do not resize under the IME -- this one's 526 login form does not -- never produces one. 527 """ 528 if not self.keyboard_shown(): 529 return None 530 out = self.shell("dumpsys window displays", check=False) 531 m = self.IME_INSET.search(out or "") 532 if m: 533 self._ime_top = int(m.group(2)) 534 return self._ime_top 535 536 # -- acting ----------------------------------------------------------- 537 538 def tap(self, x: int, y: int) -> None: 539 self.shell(f"input tap {x} {y}") 540 541 def tap_node(self, node: Node, screen: Optional[Screen] = None) -> None: 542 target = screen.tap_target(node) if screen is not None else node 543 x, y = target.center 544 self.tap(x, y) 545 546 def long_press(self, node: Node, ms: int = 800) -> None: 547 """Hold a finger on a node long enough for a long-press gesture. 548 549 A zero-distance `input swipe` is what works: a press that never moved. 550 Moving even two pixels turns it into a drag and cancels the long press. 551 """ 552 x, y = node.center 553 self.shell(f"input swipe {x} {y} {x} {y} {ms}") 554 555 def type_text(self, s: str) -> None: 556 """Type into the focused field. 557 558 "input text" maps each character through a KeyCharacterMap and throws 559 NullPointerException on anything it cannot map, so non-ASCII goes 560 through the clipboard instead (which needs the sim build's hooks). 561 """ 562 if not s: 563 return 564 if not s.isascii() or len(s) > 200: 565 self.paste_text(s) 566 return 567 for chunk in re.split(r"( )", s): 568 if not chunk: 569 continue 570 if chunk == " ": 571 self.shell("input keyevent 62") 572 else: 573 self.shell(f"input text {shlex.quote(chunk)}", check=False) 574 575 def paste_text(self, s: str) -> None: 576 """Put text on the clipboard through the sim hooks, then paste it.""" 577 res = self.shell( 578 f"am broadcast -a {self.pkg}.sim.SET_CLIPBOARD " 579 f"-n {HOOKS} --es text {shlex.quote(s)}", 580 check=False, 581 ) 582 if "Broadcast completed" not in res: 583 raise RuntimeError( 584 f"clipboard hook unavailable (is this the sim APK?): {res.strip()[:200]}" 585 ) 586 self.shell("input keyevent KEYCODE_PASTE") 587 588 def clear_field(self, node: Node, screen: Optional[Screen] = None, 589 width: int = 48) -> None: 590 """Empty a text field by selecting all of it and deleting. 591 592 `KEYCODE_DEL` alone needs as many events as the field has characters, 593 and the merchant URL field comes prefilled with a host name -- so the 594 select-all shortcut does it in two events instead of forty. 595 """ 596 self.tap_node(node, screen) 597 time.sleep(0.3) 598 self.shell("input keyevent KEYCODE_MOVE_END") 599 self.shell(f"input keyevent --longpress {' '.join(['KEYCODE_DEL'] * width)}", 600 check=False) 601 602 def key(self, keycode: str) -> None: 603 self.shell(f"input keyevent {keycode}") 604 605 def keyboard_shown(self) -> bool: 606 """Whether the soft keyboard is up. 607 608 This matters more than it sounds. The IME is its own window, and the 609 terminal's login form does not resize under it -- so the hierarchy 610 still reports the Connect button at its layout position while the 611 keyboard is drawn on top of it, and a tap aimed there lands on a key. 612 Nothing is logged, nothing changes on screen, and the scenario waits 613 out its timeout concluding that the button does nothing. 614 """ 615 out = self.shell("dumpsys input_method | grep -m1 mInputShown", check=False) 616 return "mInputShown=true" in out 617 618 def hide_keyboard(self, timeout: float = 6.0) -> bool: 619 """Put the soft keyboard away, and say whether it went. 620 621 BACK is what does it: the IME consumes the first BACK to dismiss 622 itself, so this cannot navigate away by accident *while the keyboard 623 is up* -- which is why the state is checked first and after rather 624 than pressing hopefully. ESCAPE looks like the tidier choice and does 625 nothing at all on a soft keyboard. 626 """ 627 if not self.keyboard_shown(): 628 return True 629 deadline = time.monotonic() + timeout 630 while time.monotonic() < deadline: 631 self.key("KEYCODE_BACK") 632 time.sleep(0.8) 633 if not self.keyboard_shown(): 634 return True 635 return False 636 637 def back(self) -> None: 638 self.key("KEYCODE_BACK") 639 640 def scroll(self, down: bool = True, screen: Optional[Screen] = None, 641 node: Optional[Node] = None) -> None: 642 """Swipe inside the scrollable area of the current screen. 643 644 Fixed coordinates break as soon as the layout changes, so the gesture 645 is derived from a scrollable node when there is one and from the window 646 otherwise. `node` pins it to one of several scrollables, which the 647 order screen needs: its category list and its product grid scroll 648 independently and the grid is not always the larger of the two. 649 """ 650 width, height = self.size() 651 area = None 652 if node is not None: 653 area = node.bounds 654 elif screen is not None: 655 scrollables = [n for n in screen.nodes if n.scrollable and n.area > 0] 656 if scrollables: 657 area = max(scrollables, key=lambda n: n.area).bounds 658 if area is None: 659 area = (0, height // 8, width, height - height // 8) 660 x1, y1, x2, y2 = area 661 x = (x1 + x2) // 2 662 near, far = y1 + (y2 - y1) // 6, y2 - (y2 - y1) // 6 663 start, end = (far, near) if down else (near, far) 664 # 800 ms makes this a drag rather than a fling: a fling carries on 665 # under its own momentum and can scroll a whole row past the next dump. 666 self.shell(f"input swipe {x} {start} {x} {end} 800") 667 668 def swipe_from_left_edge(self) -> None: 669 """Open the navigation drawer with the edge gesture. 670 671 The hamburger button is the ordinary way in and is what scenarios use; 672 this exists because the drawer is also reachable by gesture, and 673 `gesturesEnabled` is switched off while the terminal has no valid 674 config -- which is a thing worth testing rather than assuming. 675 """ 676 width, height = self.size() 677 y = height // 2 678 self.shell(f"input swipe 2 {y} {width // 2} {y} 400") 679 680 # -- app lifecycle and entry points ----------------------------------- 681 682 def launch(self, timeout: int = 90) -> None: 683 """Bring the terminal to the front. 684 685 `am start -W` waits for the activity to be drawn, which is what makes 686 the next dump meaningful -- and which hangs for the full timeout when 687 the launch is blocked by a system dialog ("Taler POS keeps stopping") 688 or when the activity dies while starting. A `subprocess.TimeoutExpired` 689 there aborts the whole scenario with a traceback about adb, so it is 690 caught and retried without the wait; a scenario that then finds no app 691 reports that instead, which is a far more useful failure. 692 """ 693 try: 694 self.shell(f"am start -W -n {ACTIVITY}", timeout=timeout, check=False) 695 return 696 except subprocess.TimeoutExpired: 697 pass 698 self.shell(f"am start -n {ACTIVITY}", timeout=30, check=False) 699 time.sleep(3) 700 701 def stop(self) -> None: 702 self.shell(f"am force-stop {self.pkg}") 703 704 def kill(self) -> None: 705 """Process death without a clean shutdown, to test state restoration.""" 706 self.shell(f"am kill {self.pkg}") 707 708 def clear_data(self) -> None: 709 self.shell(f"pm clear {self.pkg}") 710 711 def grant_camera(self) -> None: 712 """Re-grant the camera permission, which "pm clear" takes away.""" 713 self.shell(f"pm grant {self.pkg} android.permission.CAMERA", check=False) 714 715 def revoke_camera(self) -> None: 716 self.shell(f"pm revoke {self.pkg} android.permission.CAMERA", check=False) 717 718 def setup_uri(self, uri: str) -> None: 719 """Hand a `taler-pos://` setup URI to the terminal. 720 721 This is a plain VIEW deep link, which is both what the manifest filter 722 declares and what the QR scanner synthesises internally -- so the two 723 provisioning paths differ only in how the string is obtained. 724 """ 725 self.shell(f"am start -a android.intent.action.VIEW -d {shlex.quote(uri)} " 726 f"-n {ACTIVITY}", timeout=120, check=False) 727 728 def _hook_report(self, action: str, marker: str, 729 timeout: float = 8.0) -> Optional[str]: 730 """Ask a reporting hook a question and read its answer out of the log. 731 732 A broadcast receiver cannot return a value, so the hooks that read 733 something out of the app process print it instead. The log is cleared 734 first so that an answer from an earlier call cannot be mistaken for 735 this one. 736 """ 737 self.adb("logcat", "-c", "-b", "main", check=False) 738 res = self.shell(f"am broadcast -a {self.pkg}.sim.{action} -n {HOOKS}", 739 check=False) 740 if "Broadcast completed" not in res: 741 return None 742 deadline = time.monotonic() + timeout 743 pattern = re.compile(rf"{re.escape(marker)}\s*(.*)$") 744 while time.monotonic() < deadline: 745 for line in self.logcat(lines=500).splitlines(): 746 m = pattern.search(line) 747 if m: 748 return m.group(1).strip() 749 time.sleep(0.5) 750 return None 751 752 def report_nfc_payload(self) -> Optional[str]: 753 """What the terminal is offering over host card emulation. 754 755 Returns the URI, the string "none" when the terminal published 756 nothing, or None when the hook did not answer at all. On an emulator 757 this is always "none": the NFC service refuses to publish anything on 758 a device with no NFC adapter, and no emulator image has one -- so this 759 is a check that the terminal is *not* publishing, not a way to read 760 the pay URI. `read_clipboard` is that. 761 """ 762 return self._hook_report("REPORT_NFC_PAYLOAD", "nfc-payload:") 763 764 def read_clipboard(self) -> Optional[str]: 765 """What is on the clipboard, read from inside the app. 766 767 The clipboard may only be read by the foreground app, and the hook 768 runs in it -- so this is how a URI the terminal only draws as a QR 769 code becomes readable: tap the screen's copy button, then ask. 770 """ 771 value = self._hook_report("REPORT_CLIPBOARD", "clipboard:") 772 return None if value in (None, "none") else value 773 774 def airplane_mode(self, on: bool) -> None: 775 self.shell(f"cmd connectivity airplane-mode {'enable' if on else 'disable'}", 776 check=False) 777 778 def set_app_locale(self, tag: str) -> None: 779 """Set the per-app language, as the terminal's own Settings screen does. 780 781 API 33 and later only; below that the app's language picker writes a 782 value the framework ignores, which is itself worth knowing but is not 783 what this is for. 784 """ 785 if self.sdk_int < 33: 786 raise RuntimeError(f"per-app locales need API 33, device is {self.sdk_int}") 787 self.shell(f"cmd locale set-app-locales {self.pkg} --locales {tag}", 788 check=False) 789 790 # -- waiting and convenience ------------------------------------------ 791 792 def wait_for(self, pattern: str, timeout: int = 60, poll: float = 1.5) -> Screen: 793 """Poll the UI until some label matches, and return that screen. 794 795 Raises TimeoutError with the last screen's labels attached, which is 796 what makes a failing scenario readable afterwards. 797 """ 798 deadline = time.monotonic() + timeout 799 last = Screen() 800 while time.monotonic() < deadline: 801 last = self.dump() 802 if last.find(pattern): 803 return last 804 time.sleep(poll) 805 raise TimeoutError( 806 f"no label matching {pattern!r} within {timeout}s; " 807 f"screen showed: {last.texts()}" 808 ) 809 810 def wait_gone(self, pattern: str, timeout: int = 60, poll: float = 1.5) -> Screen: 811 """Poll until no label matches any more.""" 812 deadline = time.monotonic() + timeout 813 last = Screen() 814 while time.monotonic() < deadline: 815 last = self.dump() 816 if not last.find(pattern): 817 return last 818 time.sleep(poll) 819 raise TimeoutError( 820 f"{pattern!r} still on screen after {timeout}s: {last.texts()}") 821 822 def tap_text(self, pattern: str, timeout: int = 30) -> Screen: 823 """Wait for a label, tap what serves it, and return that screen.""" 824 screen = self.wait_for(pattern, timeout=timeout) 825 node = screen.find(pattern) 826 if node is None: 827 raise RuntimeError(f"{pattern!r} matched but was gone before the tap; " 828 f"screen now: {self.dump().texts()}") 829 self.tap_node(node, screen) 830 return screen 831 832 833 if __name__ == "__main__": 834 import sys 835 d = Device(sys.argv[1] if len(sys.argv) > 1 else None) 836 s = d.dump() 837 print(f"activity: {s.activity}") 838 print(f"window: {d.size()}") 839 print(f"nodes: {len(s.nodes)} labelled: {len(s.labelled())} " 840 f"tappable: {len(s.tappable())} editable: {len(s.editable())}") 841 print(s) 842 print("signature:", s.signature()[:300])