taler-android

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

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.