taler-android

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

episode.py (11413B)


      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 """One run of the simulator: actions in, artifacts and findings out.
     15 
     16 Every action is recorded in a form that can be replayed, which is what makes a
     17 finding useful: the artifact directory holds the sequence that produced it, not
     18 just a stack trace.  Actions are addressed by label wherever possible, because
     19 coordinates stop meaning anything as soon as a layout shifts -- and the
     20 terminal's layout shifts with the width of the screen, since it has a tablet
     21 and a phone variant of the config screen.
     22 """
     23 
     24 from __future__ import annotations
     25 
     26 import json
     27 import time
     28 from dataclasses import asdict, dataclass
     29 from pathlib import Path
     30 from typing import Any, Optional
     31 
     32 import coverage as coverage_mod
     33 import oracles
     34 from device import Device, Screen
     35 from pos import Pos
     36 
     37 
     38 @dataclass
     39 class Action:
     40     """A replayable step."""
     41 
     42     op: str
     43     arg: Any = None
     44 
     45     def describe(self) -> str:
     46         return f"{self.op}({self.arg!r})" if self.arg is not None else f"{self.op}()"
     47 
     48 
     49 class Episode:
     50     def __init__(
     51         self,
     52         dev: Device,
     53         out_dir: str | Path,
     54         name: str = "episode",
     55         settle: float = 1.2,
     56         coverage_dir: str | Path | None = None,
     57     ):
     58         self.dev = dev
     59         self.app = Pos(dev)
     60         # Whatever has been exercised so far lives in the app process; a wipe
     61         # takes it with it unless it is dumped first.
     62         self.app.before_wipe = lambda: self.dump_coverage("before-wipe")
     63         self.dir = Path(out_dir) / name
     64         self.dir.mkdir(parents=True, exist_ok=True)
     65         self.name = name
     66         self.settle = settle
     67         self.actions: list[Action] = []
     68         self.session = oracles.Session()
     69         self.signatures: set[str] = set()
     70         self.steps = 0
     71         self.notes: list[str] = []
     72         self._shots = 0
     73         self._progress_since = time.monotonic()
     74         self._progress_signature = ""
     75         self.coverage_dir = Path(coverage_dir) if coverage_dir else None
     76         self._dumps = 0
     77         self.dev.logcat(clear=True)
     78 
     79     # -- acting -----------------------------------------------------------
     80 
     81     def note(self, text: str) -> None:
     82         """Record something the scenario established, for the write-up.
     83 
     84         A finding is only half the story; the other half is what the harness
     85         had arranged, and that is rarely visible in a screenshot -- "the token
     86         had 12 seconds left" is the difference between a bug and a
     87         misunderstanding.
     88         """
     89         self.notes.append(f"[{self.steps}] {text}")
     90 
     91     def perform(self, action: Action, screen: Optional[Screen] = None) -> None:
     92         """Run one action, recording it first so a crash still leaves a trace."""
     93         self.actions.append(action)
     94         self._write_actions()
     95         op, arg = action.op, action.arg
     96         if op == "tap_label":
     97             current = screen or self.dev.dump()
     98             target = current.find(f"^{_escape(arg)}$") or current.find(_escape(arg))
     99             if target is None:
    100                 return
    101             before = current.signature()
    102             resolved = current.tap_target(target)
    103             # A control the keyboard is drawing over cannot be tapped where
    104             # the dump says it is -- and a dialog's dump covers only the
    105             # dialog, so it reports its buttons at coordinates the keyboard
    106             # owns.  Tapping there presses a key: an attempt at the
    107             # custom-product dialog's Add typed a "u" into the price field and
    108             # the scenario went on believing it had pressed the button.
    109             ime_top = self.dev.ime_top()
    110             if ime_top is not None and resolved.bounds[1] >= ime_top:
    111                 self.note(f"{arg!r} is behind the keyboard at "
    112                           f"{resolved.bounds}; not tapping it")
    113                 return
    114             interactive = resolved.clickable and resolved.enabled
    115             self.dev.tap_node(target, current)
    116             time.sleep(self.settle)
    117             after = self.dev.dump()
    118             if interactive:
    119                 fresh = self.session.add(oracles.silent_failure(
    120                     self.dev, str(arg), before, after.signature()))
    121                 for finding in fresh:
    122                     self._capture(finding, after, None)
    123         elif op == "tap_xy":
    124             self.dev.tap(arg[0], arg[1])
    125         elif op == "long_press_label":
    126             target = (screen or self.dev.dump()).find(_escape(arg))
    127             if target is not None:
    128                 self.dev.long_press(target)
    129         elif op == "type":
    130             fields = (screen or self.dev.dump()).editable()
    131             if fields:
    132                 self.dev.clear_field(fields[0], screen)
    133                 self.dev.type_text(arg)
    134         elif op == "scroll_down":
    135             self.dev.scroll(down=True, screen=screen)
    136         elif op == "scroll_up":
    137             self.dev.scroll(down=False, screen=screen)
    138         elif op == "back":
    139             self.dev.back()
    140         elif op == "drawer_gesture":
    141             self.dev.swipe_from_left_edge()
    142         elif op == "setup_uri":
    143             self.dev.setup_uri(arg)
    144         elif op == "offline_blip":
    145             self.dev.airplane_mode(True)
    146             time.sleep(4)
    147             self.dev.airplane_mode(False)
    148             time.sleep(3)
    149         elif op == "offline":
    150             self.dev.airplane_mode(bool(arg))
    151             time.sleep(3)
    152         elif op == "process_death":
    153             self.dump_coverage("before-kill")
    154             self.dev.kill()
    155             time.sleep(1.5)
    156             self.dev.launch()
    157         elif op == "relaunch":
    158             self.dump_coverage("before-relaunch")
    159             self.dev.stop()
    160             self.dev.launch()
    161         else:
    162             raise ValueError(f"unknown action {op}")
    163         self.steps += 1
    164         time.sleep(self.settle)
    165 
    166     # -- observing --------------------------------------------------------
    167 
    168     def observe(self, with_log: bool = True,
    169                 log_lines: int = 800) -> tuple[Screen, list[oracles.Finding]]:
    170         """Read the screen, run the oracles, keep the evidence for anything new.
    171 
    172         Only the tail of the log is read: the whole buffer takes seconds once
    173         it has filled, and the oracles are looking at what just happened.
    174         """
    175         # A dump that lost its race with the UI comes back empty, and every
    176         # oracle then reasons about a screen that was never read.
    177         screen = self.app._stable_dump()
    178         # A progress message is only stuck if it has been the *same* progress
    179         # message for a while, so the clock restarts whenever the screen
    180         # changes.
    181         signature = screen.signature()
    182         if signature != self._progress_signature:
    183             self._progress_signature = signature
    184             self._progress_since = time.monotonic()
    185         log = self.dev.logcat(lines=log_lines) if with_log else None
    186         fresh = self.session.check(self.dev, screen=screen, log=log,
    187                                    progress_since=self._progress_since)
    188         self.signatures.add(signature)
    189         for finding in fresh:
    190             self._capture(finding, screen, log)
    191         return screen, fresh
    192 
    193     def judge(self, found: list[oracles.Finding],
    194               screen: Optional[Screen] = None) -> list[oracles.Finding]:
    195         """Record findings a scenario produced by its own reasoning.
    196 
    197         The screen oracles see every dump; a scenario's own checks -- that the
    198         backend and the screen disagree, that an order was left behind -- have
    199         to be handed in, and this is where they get their screenshot and their
    200         action list.
    201         """
    202         fresh = self.session.add(found)
    203         if fresh:
    204             shot = screen or self.dev.dump()
    205             for finding in fresh:
    206                 self._capture(finding, shot, None)
    207         return fresh
    208 
    209     def _capture(self, finding: oracles.Finding, screen: Screen,
    210                  log: Optional[str]) -> None:
    211         stem = f"{finding.kind}-{finding.fingerprint}"
    212         self._shots += 1
    213         try:
    214             self.dev.screenshot(str(self.dir / f"{stem}.png"))
    215         except Exception:
    216             pass
    217         payload = {
    218             "finding": asdict(finding),
    219             "fingerprint": finding.fingerprint,
    220             "step": self.steps,
    221             "screen": screen.texts(),
    222             "signature": screen.signature(),
    223             "notes": list(self.notes),
    224             "actions": [asdict(a) for a in self.actions],
    225         }
    226         (self.dir / f"{stem}.json").write_text(json.dumps(payload, indent=2))
    227         if log:
    228             (self.dir / f"{stem}.logcat.txt").write_text(log[-400_000:])
    229 
    230     # -- finishing --------------------------------------------------------
    231 
    232     def _write_actions(self) -> None:
    233         (self.dir / "actions.json").write_text(
    234             json.dumps([asdict(a) for a in self.actions], indent=2))
    235 
    236     def dump_coverage(self, tag: str = "end") -> Optional[Path]:
    237         """Collect execution data, if this is an instrumented build."""
    238         if self.coverage_dir is None:
    239             return None
    240         self._dumps += 1
    241         target = self.coverage_dir / f"{self.name}-{self._dumps:02d}-{tag}.ec"
    242         try:
    243             return coverage_mod.dump(self.dev, target, name=f"{tag}.ec")
    244         except Exception as e:
    245             print(f"coverage dump failed ({tag}): {e}")
    246             return None
    247 
    248     def finish(self, extra: Optional[dict] = None) -> dict:
    249         self.dump_coverage("end")
    250         findings = list(self.session.findings.values())
    251         summary = {
    252             "name": self.name,
    253             "steps": self.steps,
    254             "distinct_screens": len(self.signatures),
    255             "notes": self.notes,
    256             "findings": [asdict(f) | {"fingerprint": f.fingerprint} for f in findings],
    257             "serious": len(self.session.serious()),
    258             **(extra or {}),
    259         }
    260         (self.dir / "summary.json").write_text(json.dumps(summary, indent=2))
    261         # The terminal's own tags are what the oracles read, so they are kept
    262         # in full; the rest of the system log keeps its tail, which is where
    263         # an ANR or a native abort shows up.
    264         log = self.dev.logcat()
    265         mine = [l for l in log.splitlines()
    266                 if any(tag in l for tag in (
    267                     "taler-pos", "ConfigManager", "ConfigFragment", "PaymentManager",
    268                     "HistoryManager", "RefundManager", "OrderManager",
    269                     "PosSimHooks", "taler-wallet-hce", "MainActivity"))]
    270         (self.dir / "logcat.txt").write_text(
    271             "\n".join(mine)[-4_000_000:] + "\n--- other tags, tail ---\n"
    272             + log[-400_000:])
    273         return summary
    274 
    275 
    276 def _escape(text: str) -> str:
    277     import re
    278     return re.escape(text)