README.md (4072B)
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 # `6-simulator` — the terminal, driven in an emulator, nightly 18 19 ```bash 20 contrib/ci/ci.sh 6-simulator # as the buildbot runs it 21 PUBLISH=0 contrib/ci/jobs/6-simulator/job.sh # locally, report on disk 22 POS_SUITE_ARGS='--tag mock' \ 23 PUBLISH=0 contrib/ci/jobs/6-simulator/job.sh # a subset, while iterating 24 ``` 25 26 This is the integration half of [`5-coverage`](../5-coverage/README.md). That 27 job runs every JVM unit test; this one boots an Android emulator, installs the 28 `sim` build of `merchant-terminal`, walks all 103 scenarios in 29 `pos-simulator/driver/suite.py`, and then calls 5-coverage's own script with 30 `EMULATOR_EC_DIR` pointed at the execution data the run produced. There is one 31 report, not two, and it is the merged one. 32 33 ## Why it is nightly and not per-push 34 35 Measured over 57 real scenario runs the mean scenario is 103.7 s, so the suite 36 is about **three hours serially**. The harness can drive five emulators side by 37 side and finish in about forty minutes, and this job deliberately does not: the 38 container worker is shared with every other repository's CI, and a nightly has 39 nowhere to be. `POS_WORKER` stays `0`. 40 41 `config.ini` carries `RUN_ON = nightly`, which the buildmaster honours by 42 skipping the stage in push builds. Stages are discovered by listing this 43 directory, so without that key the job would run on every push — three hours of 44 emulator time holding the worker, which is worse than a job that fails, because 45 a failure at least gets noticed. 46 47 ## Why it is advisory 48 49 `HALT_ON_FAILURE = False` with `WARN_ON_FAILURE = True`, as the deploy jobs 50 have. 87 of the 103 scenarios need the public `demo.taler.net` deployment — 51 backend, exchange and bank — and that tracks master and is redeployed without 52 reference to this repository. An outage there is not a defect here, so the job 53 warns and the build stays green. 54 55 That is safe because of how `suite.py` reports: it exits non-zero **only** for 56 harness errors. A scenario that finds something wrong with the app still exits 57 `ok`, because the finding is the result rather than a crash. So a failure of 58 this job means the harness could not run at all. 59 60 ## The TLS wrinkle 61 62 `ConfigFragment.sanitizeMerchantUrlAndUpdateFields` and 63 `MainActivity.handleSetupIntent` both hard-code `https://`, so the harness's own 64 backend has to answer TLS, and the `sim` build type compiles the simulator's CA 65 in as an extra trust anchor. 66 67 The CA's private key is **not** in git, deliberately — see 68 [`pos-simulator/tls/README.md`](../../../../pos-simulator/tls/README.md). A CI 69 checkout has `ca.crt` and `srv.crt` and neither key, so the job generates its 70 own set and copies the new `ca.crt` over 71 `merchant-terminal/src/sim/res/raw/sim_ca.crt` **before** building the APK: the 72 anchor is compiled in, so a new CA means a new build. On a host that already 73 has `ca.key` — a dedicated simulator box — nothing is regenerated. 74 75 ## What it needs from the image 76 77 All of it is already in `contrib/ci/Containerfile`: the emulator and the 78 `android-36;google_apis;x86_64` system image, `taler-wallet-cli` for the 13 79 `pay` scenarios, `taler-twister` for the 15 `fault` ones, `openssl`, and a 80 `python3` — the driver is pure standard library. It also needs `/dev/kvm`, 81 which the buildmaster passes to every container unconditionally; without 82 acceleration the suite is a day rather than three hours.