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)