taler-android

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

README.md (6401B)


      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 # `5-coverage` — the report on lcov.taler.net
     18 
     19 ```bash
     20 contrib/ci/ci.sh 5-coverage            # as the buildbot runs it
     21 PUBLISH=0 contrib/ci/jobs/5-coverage/job.sh   # locally, leaves the report on disk
     22 ```
     23 
     24 The site serves a directory of HTML per repository. For the C codebases that
     25 directory comes from lcov's `genhtml`; nothing on the receiving end needs
     26 lcov's own format, so this ships **JaCoCo's** report, which is the same thing
     27 for the JVM — a source-annotated page per class, green and red down the
     28 gutter — plus a landing page over the top. It lands in
     29 `/artifacts/taler-android/lcov/$CI_COMMIT_REF/taler-android` and goes to
     30 `rsync://taler.host.internal:424243/incoming_taler/`, the same way
     31 `exchange/contrib/ci/jobs/002-test/5-coverage.sh` does it.
     32 
     33 No registration is needed: the buildbot lists `contrib/ci/jobs` to find its
     34 stages (`GenerateStagesCommand` in `taler-deployment/buildbot/master.cfg`),
     35 so a directory here is a job.
     36 
     37 ## What it covers, and what it does not
     38 
     39 It runs **every JVM unit test in the repository** — `taler-kotlin-android`,
     40 `merchant-lib`, `merchant-terminal` and `wallet`, the four modules that have
     41 any. `cashier` and `donau-verificator` have none.
     42 
     43 For the two apps a simulator drives, the tests run against the **`sim` build
     44 type** (`:merchant-terminal:testSimUnitTest`, `:wallet:testFdroidSimUnitTest`)
     45 rather than `debug`. That is not a preference: JaCoCo matches execution data
     46 to classes by a checksum of the class file, so unit-test and emulator data can
     47 only appear in one report if both were recorded against the same variant.
     48 Reporting the wallet against `fdroidDebug` would silently drop every `.ec`
     49 file the wallet simulator produced.
     50 
     51 It does **not** run the integration suites — `pos-simulator/` drives the
     52 merchant terminal in an Android emulator and `wallet-simulator/` drives the
     53 wallet against a complete local Taler stack, each hours rather than minutes
     54 for a whole suite even with hardware acceleration — the POS one measured
     55 103.7 s per scenario over 57 runs, and the wallet's hundred-odd scenarios are
     56 of the same order. Those are nightlies on a
     57 KVM-capable worker — [`6-simulator-pos`](../6-simulator-pos/README.md) and
     58 [`7-simulator-wallet`](../7-simulator-wallet/README.md) — not something to put
     59 on every push. Each one ends by calling this job with its execution data, so
     60 the report here is the merged one and there is no second figure to disagree
     61 with it.
     62 
     63 ### The emulator does work in this container
     64 
     65 Tested, so that the next person does not have to wonder:
     66 
     67 ```
     68 $ emulator -accel-check
     69 KVM (version 12) is installed and usable.
     70 $ emulator -avd citest -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect
     71 BOOTED after 40s
     72 API 36
     73 Physical size: 2560x1600
     74 ```
     75 
     76 Three things have to line up, and each fails in a way that looks like
     77 something else:
     78 
     79 * **The host account must be able to open `/dev/kvm`.** Not root, not the
     80   group's existence — the account the worker runs as. `ls -l /dev/kvm` can
     81   look perfectly healthy while `open()` returns `EACCES`, because access was
     82   granted by ACL to somebody else. Test it with
     83   `python3 -c "import os;os.close(os.open('/dev/kvm',os.O_RDWR))"`.
     84 * **Rootless podman needs `--group-add keep-groups`.** Without it the device
     85   appears inside the container as `nobody:nogroup` and is unusable even
     86   though the host user has access. `ci.sh` passes this, and `--device
     87   /dev/kvm`, only when the host account can actually open the device, so a
     88   worker without KVM still runs every other job.
     89 * **The emulator binary needs X libraries this image does not carry.**
     90   Without them it dies with `libX11.so.6: cannot open shared object file`,
     91   which reads like a broken SDK rather than a missing dependency:
     92 
     93   ```
     94   libx11-6 libxcb1 libxdamage1 libxext6 libxfixes3 libxcomposite1 libxcursor1
     95   libxi6 libxrandr2 libxrender1 libxtst6 libnss3 libnspr4 libpulse0 libgl1
     96   libglu1-mesa libdrm2 libgbm1 fontconfig
     97   ```
     98 
     99   plus `libasound2t64` (trixie) or `libasound2` (older), which is why the
    100   install needs a fallback.
    101 
    102 The proof above mounted the host's SDK rather than baking one in. Packaging
    103 it is the remaining work and is routine — `sdkmanager "emulator"
    104 "system-images;android-36;google_apis;x86_64"` — but it adds roughly 1.5 GB
    105 to an image every other job also pulls, so it probably wants its own
    106 Containerfile rather than the shared one.
    107 
    108 ## Feeding an emulator run in
    109 
    110 The job already takes the other half, and both nightlies use it: a
    111 `pos-simulator` run writes JaCoCo `.ec` files to `$POS_SIM_ROOT/run/coverage`
    112 and a `wallet-simulator` run to `/opt/taler-sim/run/coverage`. Drop either set
    113 into `/inputs/emulator-coverage` (or point `EMULATOR_EC_DIR` at it) and it is
    114 merged into the same report rather than needing a second one. The landing page
    115 then also lists which scenarios produced them.
    116 
    117 The wallet nightly additionally publishes a wallet-only report at
    118 <https://lcov.taler.net/taler-android-wallet/>, from the same execution data
    119 and with the wallet harness's own landing page — the repo-wide page here
    120 cannot say much about one app among six.
    121 
    122 That is the whole integration, so when a worker with KVM exists the remaining
    123 work is to run the suite there and hand the directory over:
    124 
    125 ```bash
    126 ssh <worker> 'cd /tmp/taler-pos-sim/driver && . ../env.sh && \
    127     python3 campaign.py suite --workers 3 --label nightly'
    128 rsync -a <worker>:/tmp/taler-pos-sim/run/coverage/ inputs/emulator-coverage/
    129 contrib/ci/ci.sh 5-coverage
    130 ```
    131 
    132 Fuzzing stays out either way: `pos-simulator/driver/explore.py` and
    133 `wallet-simulator/driver/explore.py` are random walks, so their coverage is
    134 not reproducible between runs and would make the trend line meaningless.