taler-android

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

explore.py (8845B)


      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 """Random exploration of the wallet, biased towards screens not yet seen.
     15 
     16 A plain monkey spends its time on the main screen, so this keeps a count of
     17 which labels it has already tapped in each screen signature and prefers the
     18 untried ones.  Environment actions — back, rotation, process death, a URI
     19 arriving from outside — are mixed in at low rates, because they are where
     20 state-restoration bugs live.
     21 
     22 The seed makes a run reproducible, but the authoritative record is still the
     23 action log the episode writes: it replays even if the exploration policy
     24 changes.
     25 """
     26 
     27 from __future__ import annotations
     28 
     29 import random
     30 import sys
     31 import time
     32 from collections import Counter
     33 from pathlib import Path
     34 
     35 sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "corpus"))
     36 
     37 import oracles  # noqa: E402
     38 import uris as corpus  # noqa: E402
     39 from device import PKG, Device  # noqa: E402
     40 from episode import Action, Episode  # noqa: E402
     41 import scenarios  # noqa: E402
     42 from stack import Env  # noqa: E402
     43 
     44 # Labels that end the session or throw away the wallet; reachable, but rarely,
     45 # or exploration would spend its life on the first screen again.
     46 DESTRUCTIVE = (
     47     "reset wallet", "delete wallet", "dangerously", "wipe", "logout", "log out",
     48     "reset", "clear",
     49 )
     50 # Labels that lead out of the app entirely.
     51 LEAVES_APP = ("authorize in bank", "export", "share", "save", "open in browser")
     52 
     53 
     54 class Explorer:
     55     def __init__(self, episode: Episode, seed: int = 0, allow_destructive: bool = False,
     56                  env=None):
     57         self.ep = episode
     58         self.rng = random.Random(seed)
     59         self.allow_destructive = allow_destructive
     60         self.tapped: dict[str, Counter] = {}
     61         self.new_screens = 0
     62         self.uri_pool = list(corpus.all_uris().items())
     63         self.rng.shuffle(self.uri_pool)
     64         self.env = env
     65         # Steps since the walk last saw a screen it had not seen before.
     66         self.stale = 0
     67         self.restarts = 0
     68 
     69     def _pick_label(self, signature: str, labels: list[str]) -> str | None:
     70         """Prefer a label never tapped on this screen before."""
     71         seen = self.tapped.setdefault(signature, Counter())
     72         usable = [
     73             label for label in labels
     74             if (self.allow_destructive or not any(d in label.lower() for d in DESTRUCTIVE))
     75             and not any(x in label.lower() for x in LEAVES_APP)
     76         ]
     77         if not usable:
     78             return None
     79         fresh = [label for label in usable if seen[label] == 0]
     80         choice = self.rng.choice(fresh or usable)
     81         seen[choice] += 1
     82         return choice
     83 
     84     def refresh_state(self) -> None:
     85         """Go back to a deep state when the walk stops finding anything new.
     86 
     87         A random walk settles into a few screens it can reach from wherever it
     88         is; re-running a scenario setup puts it somewhere else entirely, which
     89         is cheaper than waiting for chance to do it.
     90         """
     91         import scenarios
     92         if self.env is None:
     93             return
     94         choices = [scenarios.funded_and_paid, scenarios.fund_wallet,
     95                    lambda app, env: app.fresh_start(dev_mode=True)]
     96         setup = self.rng.choice(choices)
     97         self.restarts += 1
     98         self.ep.actions.append(Action("restart_state", setup.__name__
     99                                       if hasattr(setup, "__name__") else "fresh"))
    100         try:
    101             setup(self.ep.app, self.env)
    102         except Exception as e:
    103             print(f"could not refresh the state: {e}")
    104         self.stale = 0
    105 
    106     def step(self) -> None:
    107         screen, _ = self.ep.observe()
    108         # A tap can leave the app -- a KYC link opens Chrome, "Open in banking
    109         # app" opens whatever handles payto -- and a random walk has no reason
    110         # to find its way back, so a whole run can end up exploring a browser.
    111         if screen.activity and not screen.activity.startswith(PKG):
    112             self.ep.actions.append(Action("return_to_app", screen.activity[:60]))
    113             self.ep.dev.launch()
    114             time.sleep(4)
    115             screen, _ = self.ep.observe()
    116         signature = screen.signature()
    117         if len(self.ep.signatures) > self.new_screens:
    118             self.new_screens = len(self.ep.signatures)
    119             self.stale = 0
    120         else:
    121             self.stale += 1
    122         if self.stale >= 25:
    123             self.refresh_state()
    124             return
    125 
    126         roll = self.rng.random()
    127         # An error sheet or a dead end: get out before doing anything else.
    128         if screen.find(r"(?i)export error diagnostics") or not screen.labelled():
    129             self.ep.perform(Action("back"), screen)
    130             return
    131         if roll < 0.06:
    132             self.ep.perform(Action("back"), screen)
    133             return
    134         if roll < 0.12:
    135             self.ep.perform(Action("scroll_down" if self.rng.random() < 0.75 else "scroll_up"),
    136                             screen)
    137             return
    138         if roll < 0.14:
    139             self.ep.perform(Action("rotate", self.rng.random() < 0.5), screen)
    140             return
    141         if roll < 0.16:
    142             self.ep.perform(Action("process_death"), screen)
    143             return
    144         if roll < 0.175:
    145             # Losing the network mid-operation is where retry logic shows its
    146             # seams; it is turned back on immediately so the walk can continue.
    147             self.ep.perform(Action("offline_blip"), screen)
    148             return
    149         if roll < 0.21 and self.uri_pool:
    150             name, uri = self.uri_pool[self.ep.steps % len(self.uri_pool)]
    151             self.ep.perform(Action("uri", uri), screen)
    152             return
    153         if roll < 0.33 and screen.editable():
    154             self.ep.perform(Action("type", self.rng.choice(corpus.TEXT_INPUTS)), screen)
    155             return
    156 
    157         labels = [n.label.strip() for n in screen.tappable() if n.label.strip()]
    158         label = self._pick_label(signature, labels)
    159         if label is None:
    160             self.ep.perform(Action("back"), screen)
    161             return
    162         self.ep.perform(Action("tap_label", label), screen)
    163 
    164     def run(self, steps: int) -> dict:
    165         for i in range(steps):
    166             try:
    167                 self.step()
    168             except Exception as e:  # keep exploring; the oracle records the state
    169                 self.ep.session.add([oracles.Finding("driver-error", f"{type(e).__name__}: {e}")])
    170         screen, _ = self.ep.observe()
    171         return self.ep.finish({"new_screens": len(self.ep.signatures)})
    172 
    173 
    174 def main() -> int:
    175     steps = int(sys.argv[1]) if len(sys.argv) > 1 else 60
    176     seed = int(sys.argv[2]) if len(sys.argv) > 2 else 1
    177     serial = sys.argv[3] if len(sys.argv) > 3 else "emulator-5554"
    178     out = Path("/opt/taler-sim/run/out")
    179 
    180     dev = Device(serial)
    181     ep = Episode(dev, out, name=f"explore-seed{seed}-{int(time.time())}",
    182                  coverage_dir=Path("/opt/taler-sim/run/coverage"))
    183     # Start from a wallet that already holds coins and has paid once: most of
    184     # the interesting screens do not exist in an empty wallet.
    185     env = Env.load()
    186     # Vary the starting point: a wallet with coins and a purchase behind it
    187     # reaches different screens than an empty one, and both are worth walking.
    188     setups = [
    189         ("funded_and_paid", scenarios.funded_and_paid),
    190         ("fund_wallet", scenarios.fund_wallet),
    191         ("fresh", lambda app, env: app.fresh_start(dev_mode=True)),
    192     ]
    193     name, setup = setups[seed % len(setups)] if seed % 4 else setups[0]
    194     print(f"starting state: {name}")
    195     try:
    196         setup(ep.app, env)
    197     except Exception as e:
    198         print(f"warning: could not reach the {name} state ({e}); "
    199               f"exploring from wherever the app is")
    200     explorer = Explorer(ep, seed=seed, env=env)
    201     summary = explorer.run(steps)
    202 
    203     print(f"steps: {summary['steps']}  distinct screens: {summary['distinct_screens']}"
    204           f"  state refreshes: {explorer.restarts}")
    205     print(f"findings: {len(summary['findings'])} ({summary['serious']} serious)")
    206     for f in summary["findings"]:
    207         print(f"  [{f['kind']}] {f['detail'][:160]}")
    208     print(f"artifacts: {ep.dir}")
    209     return 0
    210 
    211 
    212 if __name__ == "__main__":
    213     sys.exit(main())