taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

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])