taler-android

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

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.