taler-android

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

episode.py (10296B)


      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 shortest sequence that still
     18 reproduces it, not just a stack trace.  Actions are addressed by label wherever
     19 possible, because coordinates stop meaning anything as soon as a layout shifts.
     20 """
     21 
     22 from __future__ import annotations
     23 
     24 import json
     25 import time
     26 from dataclasses import asdict, dataclass, field
     27 from pathlib import Path
     28 from typing import Any, Optional
     29 
     30 import coverage as coverage_mod
     31 import oracles
     32 from device import Device, Screen
     33 from wallet import Wallet
     34 
     35 
     36 @dataclass
     37 class Action:
     38     """A replayable step."""
     39 
     40     op: str
     41     arg: Any = None
     42 
     43     def describe(self) -> str:
     44         return f"{self.op}({self.arg!r})" if self.arg is not None else f"{self.op}()"
     45 
     46 
     47 class Episode:
     48     def __init__(
     49         self,
     50         dev: Device,
     51         out_dir: str | Path,
     52         name: str = "episode",
     53         settle: float = 1.2,
     54         coverage_dir: str | Path | None = None,
     55     ):
     56         self.dev = dev
     57         self.app = Wallet(dev)
     58         # Whatever has been exercised so far lives in the app process; a wipe
     59         # takes it with it unless it is dumped first.
     60         self.app.before_wipe = lambda: self.dump_coverage("before-wipe")
     61         self.dir = Path(out_dir) / name
     62         self.dir.mkdir(parents=True, exist_ok=True)
     63         self.name = name
     64         self.settle = settle
     65         self.actions: list[Action] = []
     66         self.session = oracles.Session()
     67         self.signatures: set[str] = set()
     68         self.steps = 0
     69         self._shots = 0
     70         # JaCoCo data lives in the app process, so it has to be collected
     71         # before anything kills it.
     72         self.coverage_dir = Path(coverage_dir) if coverage_dir else None
     73         self._dumps = 0
     74         self.dev.logcat(clear=True)
     75 
     76     # -- acting -----------------------------------------------------------
     77 
     78     def perform(self, action: Action, screen: Optional[Screen] = None) -> None:
     79         """Run one action, recording it first so a crash still leaves a trace."""
     80         self.actions.append(action)
     81         self._write_actions()
     82         op, arg = action.op, action.arg
     83         if op == "tap_label":
     84             current = screen or self.dev.dump()
     85             target = current.find(f"^{_escape(arg)}$") or current.find(_escape(arg))
     86             if target is None:
     87                 return
     88             before = current.signature()
     89             # A random walk taps labels indiscriminately, and a label that is
     90             # not a control legitimately changes nothing -- "Pending:", a
     91             # timestamp, a section header.  Only a tap that had something to
     92             # hit can have failed silently.
     93             resolved = current.tap_target(target)
     94             interactive = resolved.clickable and resolved.enabled
     95             self.dev.tap_node(target, current)
     96             time.sleep(self.settle)
     97             after = self.dev.dump()
     98             if interactive:
     99                 fresh = self.session.add(oracles.silent_failure(
    100                     self.dev, str(arg), before, after.signature()))
    101                 for finding in fresh:
    102                     self._capture(finding, after, None)
    103         elif op == "tap_xy":
    104             self.dev.tap(arg[0], arg[1])
    105         elif op == "long_press_label":
    106             target = (screen or self.dev.dump()).find(_escape(arg))
    107             if target is not None:
    108                 self.dev.long_press(target)
    109         elif op == "type":
    110             fields = (screen or self.dev.dump()).editable()
    111             if fields:
    112                 self.dev.tap_node(fields[0], screen)
    113                 time.sleep(0.4)
    114                 self.dev.shell("input keyevent KEYCODE_MOVE_END")
    115                 for _ in range(24):
    116                     self.dev.shell("input keyevent KEYCODE_DEL")
    117                 self.dev.type_text(arg)
    118         elif op == "scroll_down":
    119             self.dev.scroll(down=True, screen=screen)
    120         elif op == "scroll_up":
    121             self.dev.scroll(down=False, screen=screen)
    122         elif op == "back":
    123             self.dev.back()
    124         elif op == "rotate":
    125             self.dev.rotate(landscape=bool(arg))
    126         elif op == "uri":
    127             self.dev.send_uri(arg)
    128         elif op == "view_uri":
    129             self.dev.view_uri(arg)
    130         elif op == "offline_blip":
    131             self.dev.shell("cmd connectivity airplane-mode enable", check=False)
    132             time.sleep(3)
    133             self.dev.shell("cmd connectivity airplane-mode disable", check=False)
    134             time.sleep(2)
    135         elif op == "process_death":
    136             self.dump_coverage("before-kill")
    137             self.dev.kill()
    138             time.sleep(1)
    139             self.dev.launch()
    140         elif op == "relaunch":
    141             self.dump_coverage("before-relaunch")
    142             self.dev.stop()
    143             self.dev.launch()
    144         elif op == "home_screen":
    145             self.app.home()
    146         else:
    147             raise ValueError(f"unknown action {op}")
    148         self.steps += 1
    149         time.sleep(self.settle)
    150 
    151     # -- observing --------------------------------------------------------
    152 
    153     def observe(self, with_log: bool = True,
    154                 log_lines: int = 600) -> tuple[Screen, list[oracles.Finding]]:
    155         """Read the screen, run the oracles, keep the evidence for anything new.
    156 
    157         Only the tail of the log is read: the whole buffer takes seconds once
    158         it has filled, and the oracles are looking at what just happened.
    159         """
    160         screen = self.dev.dump()
    161         log = self.dev.logcat(lines=log_lines) if with_log else None
    162         fresh = self.session.check(self.dev, screen=screen, log=log)
    163         self.signatures.add(screen.signature())
    164         for finding in fresh:
    165             self._capture(finding, screen, log)
    166         return screen, fresh
    167 
    168     def _capture(self, finding: oracles.Finding, screen: Screen, log: Optional[str]) -> None:
    169         stem = f"{finding.kind}-{finding.fingerprint}"
    170         self._shots += 1
    171         try:
    172             self.dev.screenshot(str(self.dir / f"{stem}.png"))
    173         except Exception:
    174             pass
    175         payload = {
    176             "finding": asdict(finding),
    177             "fingerprint": finding.fingerprint,
    178             "step": self.steps,
    179             "screen": screen.texts(),
    180             "signature": screen.signature(),
    181             "actions": [asdict(a) for a in self.actions],
    182         }
    183         (self.dir / f"{stem}.json").write_text(json.dumps(payload, indent=2))
    184         if log:
    185             (self.dir / f"{stem}.logcat.txt").write_text(log[-400_000:])
    186 
    187     # -- finishing --------------------------------------------------------
    188 
    189     def _write_actions(self) -> None:
    190         (self.dir / "actions.json").write_text(
    191             json.dumps([asdict(a) for a in self.actions], indent=2)
    192         )
    193 
    194     def dump_coverage(self, tag: str = "end") -> Optional[Path]:
    195         """Collect execution data, if this is an instrumented build."""
    196         if self.coverage_dir is None:
    197             return None
    198         self._dumps += 1
    199         target = self.coverage_dir / f"{self.name}-{self._dumps:02d}-{tag}.ec"
    200         try:
    201             return coverage_mod.dump(self.dev, target, name=f"{tag}.ec")
    202         except Exception as e:
    203             print(f"coverage dump failed ({tag}): {e}")
    204             return None
    205 
    206     def check_database(self) -> list[oracles.Finding]:
    207         """Oracles that read the wallet database, not the screen.
    208 
    209         Done once per episode rather than per step: the database has to be
    210         copied off the device, which is too slow for the action loop.
    211         """
    212         found = oracles.background_failures(self.dev, keep_db_at=str(self.dir / "walletdb"))
    213         found += oracles.unfinished_transactions(self.dev)
    214         found += oracles.db_intact(self.dev)
    215         fresh = self.session.add(found)
    216         for finding in fresh:
    217             self._capture(finding, self.dev.dump(), None)
    218         return fresh
    219 
    220     def finish(self, extra: Optional[dict] = None) -> dict:
    221         self.dump_coverage("end")
    222         try:
    223             self.check_database()
    224         except Exception as e:
    225             print(f"database oracle failed: {e}")
    226         findings = list(self.session.findings.values())
    227         summary = {
    228             "name": self.name,
    229             "steps": self.steps,
    230             "distinct_screens": len(self.signatures),
    231             "findings": [asdict(f) | {"fingerprint": f.fingerprint} for f in findings],
    232             "serious": len(self.session.serious()),
    233             **(extra or {}),
    234         }
    235         (self.dir / "summary.json").write_text(json.dumps(summary, indent=2))
    236         # Keeping only the tail of the raw log loses the start of a chatty
    237         # scenario, and with it whatever wallet-core operations ran early --
    238         # `coverage/operations.py` reads these files and reported
    239         # updateExchangeEntry as never exercised although tapping "Reload
    240         # information" calls it forty times.  So the wallet's own lines are
    241         # kept in full (they are what the oracles and the operation census
    242         # read) and the rest of the system log keeps its tail.
    243         log = self.dev.logcat()
    244         mine = [l for l in log.splitlines()
    245                 if "taler-wallet" in l or "BackendManager" in l
    246                 or "SimHooks" in l]
    247         (self.dir / "logcat.txt").write_text(
    248             "\n".join(mine)[-4_000_000:] + "\n--- other tags, tail ---\n"
    249             + log[-400_000:])
    250         return summary
    251 
    252 
    253 def _escape(text: str) -> str:
    254     import re
    255     return re.escape(text)