taler-android

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

ROUND2.md (10690B)


      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 # POS simulator, round two: fault injection and the other layout
     18 
     19 Round two set out to raise coverage, with `taler-twister` for the network side.
     20 It ran in two passes. The first used five emulators, which `tripwire` cannot
     21 carry -- load reached 10 and the time per scenario went from about ninety
     22 seconds to several minutes -- and was abandoned half finished. The second used
     23 three, which is what the box takes: load settled around three and the pace came
     24 back. Everything below is from the second pass plus what the first had already
     25 collected.
     26 
     27 ## Coverage
     28 
     29 ```
     30                 round one              round two
     31 instruction     31097/40234  77.3%     34219/40234  85.0%
     32 branch           1063/1739   61.1%      1159/1739   66.6%
     33 line             3827/4864   78.7%      4155/4864   85.4%
     34 complexity       1111/1897   58.6%      1217/1897   64.2%
     35 method            792/1047   75.6%       835/1047   79.8%
     36 class             123/140    87.9%       130/140    92.9%
     37 ```
     38 
     39 `+328` lines and `+96` branches, and **no class is at 0% any more**: round
     40 one's one untouched class, `HistoryManager$forceDeleteOrder$1`, is reached
     41 now. The round-one dumps are merged in: the APK is
     42 byte-identical, and jacoco matches execution data to classes by checksum.
     43 
     44 Where it went:
     45 
     46 ```
     47 ProcessPaymentFragmentKt   42.5% -> 93.4%   (+115 lines)
     48 AmountEntryFragmentKt      78.7% -> 95.6%   (+46)
     49 OrderFragmentKt            76.4% -> 84.7%   (+51)
     50 PaymentManager             62.1% -> 83.5%   (+22)
     51 ConfigManager              71.3% -> 82.2%   (+28)
     52 ~.payment (package)        62.5% -> 90.5%
     53 ```
     54 
     55 Branch coverage rose by five and a half points against line coverage's six and
     56 a half, where round one had branch coverage lagging line coverage by
     57 eighteen. That is what the
     58 fault scenarios bought: the lines were already being executed, and what was
     59 missing was the arm taken when the backend misbehaves.
     60 
     61 ## What moved, and why
     62 
     63 ### A phone-sized emulator
     64 
     65 Five of the terminal's screens choose their layout at runtime on
     66 `smallestScreenWidthDp >= 720` -- the order grid, the payment screen, the
     67 refund URI screen, the QR config tab and the amount keypad (the last on
     68 `>= 600`, with a third arm for a short screen). Round one ran a tablet only,
     69 so the phone half of each was never executed, and in three of those files it is
     70 the larger half.
     71 
     72 The device profile does not decide this: `emu.sh` writes the LCD geometry into
     73 the AVD and that is what the app sees, so a `medium_phone` AVD still came up
     74 2560x1600 at 320dpi -- 1280x800dp, a tablet. `POS_LCD_*` settles it, and
     75 1920x1080 at 420dpi is 731x411dp.
     76 
     77 ### Twister: a real backend made to go wrong
     78 
     79 `driver/faults.py` puts `taler-twister` -- the fault-injecting proxy the C test
     80 suites use -- in front of `backend.demo.taler.net`, and `driver/suite.py` gains
     81 thirteen `fault` scenarios. Everything stays real except the one field, status
     82 code or byte count that was armed. Two things had to be bridged:
     83 
     84 * **TLS.** Twister is a plain HTTP proxy and the terminal hard-codes `https://`.
     85   `faults.TlsFront` terminates TLS with the certificate the mock already uses
     86   and relays bytes -- a byte relay, not an HTTP proxy, so keep-alive, chunked
     87   bodies and uploads pass through untouched.
     88 * **One mutation, one request.** A twister mutation is consumed when it fires,
     89   which suits a test script and not a screen that polls: the insecure-pay-URI
     90   dialog opens on one poll of the order status and the next poll closes it.
     91   `Twister.sustain()` re-arms in a loop.
     92 
     93 `TlsFront` also injects what twister has no notion of because it is below HTTP:
     94 a body that stops halfway, or a reset while the request is still going up.
     95 
     96 ### A mock backend that demands a two-factor code
     97 
     98 Round one reported the two-factor login path as unreachable: the demo backend
     99 has `mandatory_tan_channels: ["email"]` and mails the code. It is reachable
    100 after all -- a mock can be that backend with a code the harness knows, and the
    101 terminal cannot tell the difference. The whole dance is four requests and one
    102 header, and `ChallengeRequiredException`,
    103 `ConfigFragment.fetchLimitedAccessTokenWithMfa` and `ConfigManager`'s challenge
    104 calls are now covered.
    105 
    106 Three scenarios walk it: one channel chosen from two; three wrong codes and
    107 then the right one, which covers both statuses the terminal treats as
    108 recoverable (409 "wrong code" and 429 "a new code is on its way"); and
    109 `combi_and`, where both channels must be answered and no chooser is shown.
    110 
    111 ## Findings
    112 
    113 | | Finding | Severity |
    114 | --- | --- | --- |
    115 | 10 | [A connection that dies mid-response is reported in the HTTP engine's words](transport-error-shows-the-library-wording.md) | low-medium |
    116 | 11 | [A missing field is reported to the cashier by its Kotlin type name](serialization-error-shown-to-the-cashier.md) | low-medium |
    117 
    118 Both are the same arm of `Response.getFailureString` -- the one that shows
    119 `exception.message` -- and both are reachable only through a proxy over a real
    120 backend. A cut connection produces OkHttp's "unexpected end of stream"; a
    121 deleted field produces kotlinx.serialization's "Field 'orders' is required for
    122 type with serial name 'net.taler.merchantlib.OrderHistory'". Round one's nine
    123 stand.
    124 
    125 Also observed, and not promoted to a finding because it has not been checked on
    126 a real device:
    127 
    128 * **The login form does not fit a phone in landscape.** At 731x411dp the form
    129   ends below the bottom edge: Password is clipped, and Connect and the
    130   "No instance?" help card are off-screen, with nothing to say the screen
    131   scrolls. The terminal is landscape-locked, so turning the device is not
    132   available. The driver now scrolls; a person would have to work it out.
    133 
    134 ## What the terminal got right
    135 
    136 * **A sold-out product.** A 410 carrying `product_id` and the quantities is the
    137   one backend error the terminal translates rather than quotes, and it does:
    138   "Error: Not enough inventory available / Inventory stock unavailable for
    139   product ...". It reloads the inventory afterwards, as it should.
    140 * **The insecure payment link**, from all three sides. Twister handing out a
    141   `taler+http://` URI raises "Payment link problem", and "Try fixed link"
    142   produces a `taler://` URI, "Continue as is" keeps the insecure one, and
    143   "Cancel order" leaves the payment screen. The wording names no scheme, which
    144   is the right call for a cashier.
    145 * **Two-factor login**, including three wrong codes in a row: the terminal
    146   asked again each time, requested a fresh code when the backend rate-limited
    147   it, and sent the code hyphenated as `0000-0000` the way the backend expects.
    148 * **An order whose reply was truncated.** The order really was created; the
    149   terminal reported the failure and left no second order behind.
    150 
    151 ## False positives, found and removed
    152 
    153 Four this round, each confirmed by re-running the scenario against the
    154 corrected harness:
    155 
    156 | Reported | What it really was |
    157 | --- | --- |
    158 | `zero-amount-accepted-silently` | at 0.00 the charge button is *disabled*, which is better than a dialog; the oracle insisted on the dialog |
    159 | `keypad-overflow-blank` | the keypad groups thousands, so its largest amount reads `999,999,999,999.99` and the parser only knew the ungrouped shape |
    160 | `insecure-uri-not-honoured` | the URI was read after `sustain` stopped re-arming, so the backend was healthy again and the terminal had correctly re-read it |
    161 | `insecure-uri-dialog-says-nothing` | the dialog says "payment link" rather than "http", deliberately; the oracle was looking for the jargon |
    162 
    163 Four harness bugs behind them, all fixed:
    164 
    165 * **Back dismisses a Compose dialog**, and `tap_button` used Back to put the
    166   keyboard away before every tap -- so the custom-product `Add` and the
    167   two-factor `OK` disappeared before they could be pressed. The keyboard is now
    168   only put away when the dump's own root bounds say it covers the control.
    169 * **One wallet shared by three workers.** They spent each other's coins; the
    170   symptom was one worker topping up to 60 and another failing with
    171   "insufficient balance" in whatever scenario came next. One wallet and one
    172   bank account per worker now.
    173 * **A dialog covering the next tap.** A scenario that arms a fault, reads the
    174   dialog and arms the next one has to dismiss it first, or it waits out its
    175   timeout looking for a button behind a modal.
    176 * **Scrolling a control out of existence.** `_scroll_into_view` could move a
    177   dialog's own list and carry the target off screen; losing it is worse than
    178   not having moved it, so that is undone.
    179 
    180 ## What round three should do
    181 
    182 1. **The refund form on a phone**, which is the one open question this round
    183    leaves. `refund_full` and `refund_amount_edges` both fail there, twice each,
    184    and the screen they fail on carries only its title and the order summary --
    185    no amount field, no buttons -- while the same scenarios pass on a tablet.
    186    Either the form clips its controls on a short screen, which is a finding, or
    187    the driver is still mishandling the keyboard, which is not. A list of labels
    188    cannot tell those apart, so `Pos.start_refund` now photographs the screen
    189    when it happens and the next run settles it. `RefundUriFragmentKt` at 45.3%
    190    is the largest single remainder and sits behind the same door.
    191 2. **The config package**, the largest remaining gap at 81.1%: the QR
    192    configuration tab is most of it, and it crashes (round one, finding 1).
    193 3. ~~**`fault_login_connection_cut` is flaky through the proxy.**~~ Settled in
    194    round three: it was not the proxy. A change to the driver -- putting the
    195    keyboard away only when it is over the control -- stopped it being put away
    196    on the login form, which does not resize under the IME, so the tap on
    197    Connect landed on a key. With the keyboard handled from the window
    198    manager's own inset the scenario passes and finding 10 reproduces.
    199 4. **More chaos.** `fault_chaos_walk` runs the terminal under a 12% failure
    200    rate and it came through clean; one walk is not many, and it is the only
    201    scenario where a fault arrives at a moment nobody chose.