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