README.md (18593B)
1 <!-- 2 This file is part of GNU Taler 3 (C) 2026 Taler Systems S.A. 4 5 GNU Taler is free software; you can redistribute it and/or modify it under the 6 terms of the GNU General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 --> 16 17 # Wallet simulator 18 19 Drives the Android wallet in an emulator against a local GNU Taler stack, to 20 measure how much of the app gets exercised and to find sequences that end in an 21 internal-core-error screen, a stuck transaction or a crash. 22 23 ## Where it runs 24 25 Everything runs on `tripwire.taler.net` (256 cores, 251 GB RAM, KVM): the Taler 26 services, the emulators and the driver all live there, so the observe-act loop 27 never crosses the network. Only the APK is built elsewhere and copied in. 28 29 ``` 30 tripwire:/opt/taler-sim/ 31 backend/ sim.conf, stack.sh the Taler services 32 emu/ emu.sh AVD lifecycle, one AVD per worker 33 driver/ device.py stack.py emulator control, counterparty HTTP clients 34 apk/ wallet.apk pushed from a build host 35 run/ stack/env.json, logs, emulator logs 36 ``` 37 38 The checkout under `simulator/` in taler-android is the source of truth; push it 39 with 40 41 ```bash 42 rsync -a simulator/ root@tripwire.taler.net:/opt/taler-sim/ 43 ``` 44 45 ## Running it 46 47 Bring the stack and one emulator up, then check that the basics work: 48 49 ```bash 50 ssh root@tripwire.taler.net 51 cd /opt/taler-sim 52 53 backend/stack.sh start # wipes the DB, starts the services, ~15 s 54 emu/emu.sh create 0 # once per worker 55 emu/emu.sh boot 0 # ~50 s 56 emu/emu.sh prepare 0 # install the APK, kill animations, adb reverse 57 cd driver 58 python3 stack.py # merchant instance, bank accounts, top-ups 59 python3 smoke_withdraw.py # end-to-end withdrawal through the UI 60 python3 smoke_pay.py # order, pay, refund 61 ``` 62 63 Then drive it in earnest. One scenario, or a few, on one worker: 64 65 ```bash 66 python3 suite.py --list 67 SIM_WORKER=0 python3 suite.py history exchange_add_remove 68 ``` 69 70 Everything, across four emulators, with the findings merged: 71 72 ```bash 73 python3 campaign.py suite --workers 4 --tag try1 74 python3 campaign.py explore --workers 4 --steps 150 --seed 42 75 ``` 76 77 Unattended, round after round (provision, a random walk with a fresh seed, 78 then every scenario, dumping coverage after each phase): 79 80 ```bash 81 nohup setsid ./forever.sh 1 > /opt/taler-sim/run/forever.log 2>&1 & 82 tail -f /opt/taler-sim/run/rounds.log 83 touch /opt/taler-sim/run/STOP # stops after the round in flight 84 ``` 85 86 A set of scenarios that needs a different stack — KYC, or fault injection — 87 goes through `phase.sh`, which pauses the rounds, swaps the stack, runs them, 88 restores the default stack and resumes: 89 90 ```bash 91 ./phase.sh sim-kyc.conf kyc_withdraw_trips_rule kyc_transaction_actions 92 ./phase.sh sim-twister.conf twister_withdraw_faults twister_field_faults 93 SIM_DESTRUCTIVE=1 ./phase.sh sim.conf revoke_denomination 94 ``` 95 96 The environment reaches the scenarios, so a phase is also how a destructive 97 scenario gets a stack of its own to ruin. 98 99 Reading the results: 100 101 ```bash 102 python3 report.py '*history*' --notes # episodes and their findings 103 python3 ../coverage/operations.py # wallet-core operations exercised 104 ``` 105 106 Coverage reports are built where the APK was built, because they need the 107 uninstrumented classes and the sources: 108 109 ```bash 110 rsync -a root@tripwire.taler.net:/opt/taler-sim/run/coverage/ /tmp/ec/ 111 JAVA_HOME=/home/claude/jdk-17 simulator/coverage/report.sh /tmp/ec 112 python3 simulator/coverage/gaps.py simulator/out/coverage/coverage.xml 113 ``` 114 115 `gaps.py` ranks what is still untouched. Four composables in that ranking have 116 no caller at all -- `PromptAddContactScreen`, `GridMenu`, `DemandAttention` and 117 `SelectExchangeDialogFragment`, about 190 lines -- so no scenario can ever 118 reach them. 119 120 ## The app under test 121 122 The simulator drives the **`sim` build type** of the wallet 123 (`./gradlew :wallet:assembleFdroidSim`), which is `debug` plus two things: 124 125 * `enableAndroidTestCoverage`, so the APK carries the JaCoCo agent and 126 `driver/coverage.py` can ask it for execution data mid-session; 127 * `wallet/src/sim/`, a receiver (`SimHooks`) for the two things adb cannot do — 128 dumping that coverage, and delivering an NDEF message the way a tapped NFC 129 tag would (the extra is a Parcelable, so `am start` cannot carry it). 130 131 It keeps the `.debug` application id, so the package driven is the same 132 `net.taler.wallet.fdroid.debug` a developer would install, and it is never 133 published. 134 135 One side effect worth knowing: `testBuildType "sim"` is what makes AGP create 136 an androidTest variant for this build type (and therefore instrument the app's 137 classes at all), and it also moves which unit-test task `:wallet:check` 138 resolves to — `testFdroidSimUnitTest` rather than `testFdroidDebugUnitTest`. 139 `sim` is `initWith debug`, so the same tests run against the same code, and CI 140 asks for `:wallet:check` rather than a task name. 141 142 ### Developer mode is mandatory 143 144 `HandleUriScreen` only accepts `taler+http://` URIs when developer mode is on, 145 and `MainActivity` pushes the *persisted* flag into `MainViewModel` at every 146 start — so a debug build does **not** come up in developer mode, whatever 147 `BuildConfig.DEBUG` says. `Wallet.fresh_start()` therefore switches it on 148 through Settings before anything else; without that step every URI from a local 149 http stack comes back as "Unsupported URI". 150 151 ### A stack restart invalidates the wallet 152 153 `stack.sh start` drops the database, so the exchange comes back with a new 154 master key and any coins already in the wallet are worthless. Always pair a 155 stack restart with a wallet wipe (`fresh_start()`, i.e. `pm clear`). 156 157 ## URL topology 158 159 Every service is configured with a `http://localhost:<port>/` base URL, and the 160 driver maps those same ports into each emulator with `adb reverse`. One URL 161 namespace is therefore valid both on the host and inside the wallet, which 162 matters because the merchant and the bank hand out absolute URLs that both sides 163 have to be able to resolve. 164 165 | Service | Port | 166 | --- | --- | 167 | donau | 8079 | 168 | merchant | 8080 | 169 | exchange | 8081 | 170 | libeufin-bank | 8082 | 171 | auditor | 8083 | 172 173 Plain HTTP needs no patched app: `usesCleartextTraffic` is already set in the 174 wallet manifest, and wallet-core 1.6.42 (the version in the shipped 175 `net.taler:qtart` AAR) has retired its `allowHttp` flag — it logs 176 "allowHttp flag not supported anymore" and never requires TLS. A debug build 177 also starts in dev mode on its own, because `MainViewModel` seeds dev mode from 178 `BuildConfig.DEBUG`. 179 180 ## Config variants 181 182 `backend/sim.conf` is the default stack. `SIM_CONF` selects a variant: 183 184 | Variant | What it adds | 185 | --- | --- | 186 | `sim.conf` | exchange, merchant, libeufin bank, donau; two exchange accounts (x-taler-bank and IBAN) with a wire fee each, a signed Bitcoin address, terms of service, and age-restricted denominations | 187 | `sim-kyc.conf` | KYC on, with a rule that trips when more than EUR:5 is withdrawn in a day | 188 | `sim-twister.conf` | `taler-twister` in front of the exchange on port 8088, for fault injection | 189 190 ```bash 191 SIM_CONF=sim-twister.conf backend/stack.sh start 192 ``` 193 194 **Only one stack at a time.** The exchange's secmod helpers use a runtime 195 directory derived from the user, not from the config, so a second stack 196 started alongside the first takes its sockets away and both fail with 197 "Could not connect to taler-exchange-helper-secmod-cs". Stop one before 198 starting another, or give the second its own `TALER_RUNTIME_DIR`. 199 200 ### The second exchange 201 202 `backend/exchange2.sh` runs a second, independent exchange on port 8091 from 203 `backend/sim-exchange2.conf`: its own database, offline key (so its own master 204 key), `TALER_RUNTIME_DIR` for the secmod sockets, and account at the stack's 205 libeufin bank. `stack.sh start` starts it as well unless `SIM_EXCHANGE2=0`, 206 and stops it first on the way down -- it has an account at a bank whose 207 database the stack wipes, so it cannot outlive a stack start. 208 209 With only one payment service every "which one?" step picks the only 210 candidate: the exchange picker, "treat as global" and the balance scopes a 211 second service creates are unreachable without this. 212 213 ### Three things the default config gets wrong for a wallet 214 215 Each cost this campaign a round or two to notice, and each is a one-line 216 config fix: 217 218 * **A wire method the app does not know breaks the whole reply.** The 219 exchange's wire methods reach the app as an enum, and one unrecognised name 220 makes `getDepositWireTypes` throw rather than skipping it, which hangs the 221 add-account form (`findings/unknown-wire-method-hangs-the-deposit-form.md`). 222 `SIM_EXTRA_PAYTOS` therefore signs a Bitcoin address only; a Cyclos one is 223 opt-in, because keeping it would block every deposit scenario. 224 * **A wire method with no fee does not exist** as far as the wallet is 225 concerned. `taler-unified-setup.sh` signs a wire fee only for the method it 226 is told about with `-d`, and wallet-core hides every account whose method 227 has none, so a second enabled account stays invisible. `stack.sh` uploads a 228 fee for each extra account's method. 229 * **The shipped `TERMS_DIR` is empty.** It is `${TALER_DATA_HOME}terms/`, 230 which in a test home has nothing in it, so `/terms` answers "501 not 231 configured" and the wallet never asks anyone to accept anything. The 232 exchange serves *rendered* terms (one subdirectory per language), not the 233 `.rst` sources it ships, so `stack.sh` runs `taler-terms-generator` once 234 into `$SIM_ROOT/terms`. 235 * **Age restriction needs `AGE_RESTRICTION_ENABLED`** in `[exchange]` on top 236 of the age-restricted denominations, or `/keys` advertises an age mask of 0 237 and the age picker never appears. 238 239 ## The three ways it drives the app 240 241 **Scenarios** (`driver/suite.py`, 87 of them) walk one feature each, 242 deliberately: the transaction list and its per-transaction actions, suspend / 243 resume / abort / abandon, exchange management and terms of service, every 244 settings row, deposits in all three account formats, peer payments in both 245 directions, order templates, v1 contract choices and token issuance, the scan 246 screen's manual entry, and a batch of adversarial sequences (process death 247 mid-flow, airplane mode mid-withdrawal, two pay URIs at once, force-purging an 248 exchange that still holds coins). 249 250 ```bash 251 python3 suite.py --list 252 python3 suite.py history exchange_add_remove # a few 253 python3 campaign.py suite --workers 4 --tag iter5 # all of them, 4 emulators 254 ``` 255 256 A scenario that cannot reach its feature fails loudly (`Ctx.require`) instead 257 of reporting a green row for having done nothing. 258 259 **Exploration** (`driver/explore.py`) takes over where scenarios end: it starts 260 from a funded, already-paid wallet and walks at random, biased towards screens 261 it has not seen, mixing in URIs from the corpus and environment faults. 262 263 **QR codes through the camera** (`driver/qrsuite.py`) render a payload with 264 `qrencode`, hang it on the wall of the emulator's virtual scene and read it 265 with the camera, so the scan screen and `QrCameraAnalyzer` run for real. The 266 poster can only be set at launch, so there is one emulator boot per payload. 267 268 ## How the wallet is driven 269 270 `device.py` works through the accessibility tree. The wallet is ~90 Compose 271 files with no `testTag`s anywhere, so widgets are addressed by the semantics the 272 app already publishes — `text` and `content-desc` — and tapped at the centre of 273 their bounds. A screen's "signature" (its set of labels, with numbers masked, 274 plus the count of interactive nodes) identifies a state well enough to detect 275 novelty during random exploration. 276 277 Taler URIs reach the wallet as `ACTION_SEND` / `text/plain` rather than as a 278 `VIEW` deep link: the manifest's VIEW filter covers `taler://` and `payto://` 279 but not the `taler+http://` form a local http deployment produces. `view_uri()` 280 is kept for the schemes the filter does cover. 281 282 ### Destructive scenarios 283 284 `revoke_denomination` takes a denomination key away from the exchange while the 285 wallet holds coins of it. That is stack-wide and lasts until the next stack 286 start, so it refuses to run unless `SIM_DESTRUCTIVE=1`, and it belongs in a 287 phase of its own. 288 289 `wallet_lock_without_credential` is destructive to the *device* rather than the 290 stack: it sets a PIN with `locksettings` so that the wallet lock can be 291 switched on, and clears it again in a `finally`. If that scenario is ever 292 killed outright, clear it by hand before the emulator sees a keyguard: 293 294 ```bash 295 adb -s emulator-5562 shell locksettings clear --old 1234 296 adb -s emulator-5562 shell locksettings set-disabled true 297 ``` 298 299 300 ```bash 301 SIM_DESTRUCTIVE=1 driver/phase.sh sim.conf revoke_denomination 302 ``` 303 304 ### Failing a wallet-core call from the outside 305 306 wallet-core takes two developer-mode URIs that are worth more than any proxy 307 for testing the app's own error handling: 308 309 ``` 310 taler+http://dev-experiment/api-error?operation=<op>&detail=<base64url JSON>&count=<n> 311 taler+http://dev-experiment/api-response?operation=<op>&response=<base64url JSON>&count=<n> 312 ``` 313 314 The first fails the named operation `n` times with the given error (the detail 315 must be an object with a numeric `code`); the second answers it with a canned 316 reply. `api_error_sweep` uses the first to make each screen's own call fail and 317 records which screens then say nothing; `api_response_hostile` uses the second 318 to feed the balance screen values this stack cannot produce. Both clear up 319 after themselves (`clear-api-errors`, `clear-api-responses`), and a fresh 320 profile resets the state anyway. 321 322 Two things to know: the operation name must be one wallet-core knows (the app's 323 own list is in `coverage/app-operations.txt`), and applying an experiment ends 324 with a back navigation, which *closes the app* when the URI is what started 325 it — so a scenario has to put the app back in the foreground before it can 326 look at anything. 327 328 ## What counts as a finding 329 330 `driver/oracles.py` is the contract. A refusal is not a bug — the wallet is 331 supposed to reject a stale order or a malformed URI and say so. A finding is a 332 crash, an ANR, a native abort, an error wallet-core itself calls unexpected or 333 an invariant failure (`TalerErrorCode` 2, 56, 60, 7001, 7007, 7047, 7048), an 334 error screen whose text reads like a defect, a blank screen, or a corrupt 335 database. Each one is written to the episode directory with a screenshot, the 336 logcat tail, the screen's labels and the full action list that produced it, and 337 fingerprinted so repeats collapse. 338 339 ## Tools 340 341 | Tool | What it is for | 342 | --- | --- | 343 | `driver/probe.py` | one action, then a dump — how labels get discovered | 344 | `driver/report.py` | summarise episode directories and their findings | 345 | `driver/dbprobe.py` | copy the wallet's SQLite database off the device and query it | 346 | `driver/replay.py` | replay an episode, and shrink it with ddmin | 347 | `coverage/report.sh` | merge `.ec` files into an HTML/XML report | 348 | `coverage/gaps.py` | rank what is still uncovered, and diff two reports | 349 | `findings/new_finding.py` | scaffold a write-up from an episode's artifacts | 350 351 ## Findings 352 353 `findings/` holds a write-up plus a standalone reproducer per confirmed defect. 354 So far: 355 356 * `addglobalcurrencyexchange-null-masterpub.md` — "Treat as global" on an 357 exchange the wallet has never contacted sends a request with no 358 `exchangeMasterPub`, so wallet-core answers `WALLET_UNEXPECTED_EXCEPTION` 359 (7001) and the UI shows nothing at all. Four taps from a fresh profile. 360 361 ## Gotchas the harness learned the hard way 362 363 * **Rotation outlives app data.** `user_rotation` is a system setting, so 364 `pm clear` does not undo a `rotate` action from an earlier episode, and a 365 landscape device invalidates every gesture computed for portrait. 366 `Device.portrait()` runs at the start of each episode, and `Device.scroll()` 367 derives its swipe from the scrollable node's own bounds rather than from 368 fixed coordinates. 369 * **`input text` cannot type non-ASCII.** It maps characters through a 370 KeyCharacterMap and throws `NullPointerException`. Non-ASCII text goes 371 through `SimHooks.SET_CLIPBOARD` plus `KEYCODE_PASTE` instead; the clipboard 372 may only be written by the foreground app, which is where the simulator is 373 pasting anyway. 374 * **Settings is longer than one screen**, and how much fits depends on how many 375 rows the wallet has to show, so callers wait for the screen and then scroll 376 to the row they want. 377 * **`uiautomator dump` fails while the UI is settling** ("could not get idle 378 state"); `Device.dump()` retries. 379 * **A label is often not the thing you can tap.** The main screen's action 380 buttons keep their text in a sibling node, so `Screen.tap_target()` resolves 381 a label to the clickable node that contains it *or sits next to it*. 382 * **A screen's title and its submit button often share a string.** "Add 383 account" is the app bar title, the list screen's add icon and the form's 384 submit button; a label search finds the title, which is not clickable, and 385 the neighbour search then lands on a tab or the back arrow. `Ctx.tap_button` 386 takes the lowest matching node that is clickable *and* contains the label. 387 * **An ad-hoc probe must name its serial.** `Device()` defaults to 388 `emulator-5554`, which is worker 0 -- a probe written without a serial 389 interferes with a running round. Worker 4 (`emulator-5562`) is the spare: 390 `SIM_WORKER=4`, or `Device("emulator-5562")`. 391 * **Reachable from the host is not reachable from the emulator.** Everything 392 goes through `adb reverse`, and a port that is not in `env.json`'s `ports` 393 is not mapped; the wallet then fails to add a payment service and says 394 nothing about it, which looks exactly like a scenario that worked. 395 * **`pgrep -f X` matches the shell whose command line contains X**, so a "wait 396 until the run finishes" loop waits forever on itself — and a bracket class 397 (`[f]orever.sh`) only helps when the *pattern* is bracketed and the waiting 398 command does not also mention the plain name later on its own command line. 399 Prefer matching on something the waiter cannot contain, or check a pid file. 400 The same trap kills an ssh session when `pkill -f` matches the ssh command 401 itself.