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)