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.