taler-android

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

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.