taler-android

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

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