taler-android

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

ROUND4.md (14181B)


      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 # Round four: a different app
     18 
     19 Rounds one to three measured a terminal of about 4,900 lines. Master's
     20 `24f7b249` ("[pos] add support for mixed payments and UI changes") added
     21 **20,753** of them, and the three rounds' findings were all fixed in the same
     22 commit -- so this round starts against an app two and a half times the size
     23 with none of its new surface ever driven:
     24 
     25 | new | what it is |
     26 | --- | --- |
     27 | `checkout/` | 2,843 lines: cash and card taken *before* Taler, change, partial payments, abandoned sales |
     28 | `devices/` | 2,277 lines: a Bluetooth customer display and a USB one |
     29 | `paymentoptions/` | 1,323 lines plus 1,492 for SumUp: which methods a terminal offers |
     30 | `history/OrderDetailsScreen.kt` | 994 lines: an order's products, images, deadlines, refunds |
     31 | `config/ConfigDraftViewModel.kt` | 348 lines: the login form rebuilt around it |
     32 
     33 Five defects were found, each filed with a patch that was built and verified
     34 on the emulator it was found on (the fifth after the round proper, see the end):
     35 
     36 | | severity | filed |
     37 | --- | --- | --- |
     38 | [The terminal dies one second after the session ends on the payment screen](payment-poll-crashes-when-the-session-ends.md) | high | [11973](https://bugs.gnunet.org/view?id=11973) |
     39 | [On a phone, the login form disappears the moment you tap a field](login-form-collapses-under-the-keyboard.md) | high on a phone | [11971](https://bugs.gnunet.org/view?id=11971) |
     40 | [On a phone, the cash keypad's own button is cut in half](cash-keypad-submit-is-cut-off.md) | medium | [11972](https://bugs.gnunet.org/view?id=11972) |
     41 | [Every failed delete says a wallet claimed the order](force-delete-blames-a-wallet.md) | medium to high | [11977](https://bugs.gnunet.org/view?id=11977) |
     42 | ["Paid in full", under a title bar that says "Payment required"](receipt-screen-titled-payment-required.md) | low to medium | [11974](https://bugs.gnunet.org/view?id=11974) |
     43 
     44 ## The crash
     45 
     46 `PaymentManager.checkPayment` dereferences `configManager.merchantConfig!!`,
     47 and the payment screen calls it once a second from a `CountDownTimer`. The
     48 field is set to null the moment any request comes back 401 -- which is what a
     49 session ending *is*. Between the 401 and the next tick there are 869
     50 milliseconds, and then the process is killed in front of a paying customer.
     51 
     52 It is not one line: the same `!!` is in five methods of that file and every one
     53 of them is reachable after the session has gone, including `cancelPayment`,
     54 which is what a cashier presses when the screen stops responding. The patch
     55 routes all of them through one helper that returns null and stops the polling.
     56 
     57 Reproduced twice on two emulators; with the patch the terminal shows the
     58 "Session expired -- please re-enter your credentials" dialog that was always
     59 written for this and never got a chance to appear.
     60 
     61 ## What was *not* wrong
     62 
     63 Rather more than was wrong, and worth recording because each one cost time:
     64 
     65 * **The mixed-payment checkout is correct where it counts.** Ten handed over
     66   for a seven-unit bill records a payment of seven, shows "Received ク10.00,
     67   change ク3.00", and tells the cashier to hand ク3.00 back. Cash plus Taler
     68   splits the way it should: two in cash on a six-unit sale leaves a backend
     69   order whose `contract_terms.amount` is `KUDOS:4`, the wallet pays that, and
     70   the order ends `paid`. A sale settled entirely in cash reaches the backend
     71   as `paid` once the receipt is collected, and a sale abandoned with cash in
     72   it stays in the history list as "Paid: ク2.00" with a way to settle it.
     73 * **Handing cash back works end to end.** The refund screen offers the methods
     74   the order was actually paid with, refuses the ones it was not ("GNU Taler
     75   ク0.00 Unavailable"), asks for confirmation that the money physically moved,
     76   and the backend records it under `refunds_external` -- without counting it
     77   as a Taler refund.
     78 * **The refund form still explains a bad amount.** "Invalid amount", "Needs to
     79   be positive amount", "Greater than order amount of 1.00" are all still
     80   there, and `1.0.0` is refused -- round one's finding 2 stays fixed.
     81 * **The order-details page handles awkward goods.** A product with a real PNG,
     82   one sold by the kilogram, one named in four scripts, one costing a cent and
     83   one costing nothing all render with the right unit price and the right
     84   total.
     85 * **The Bluetooth pairing wizard degrades.** With no display to find it asks
     86   for nearby-device access, walks its steps, scans, stops, and offers "Search
     87   again" -- no spinner, no stack trace.
     88 
     89 ## The harness had to be rebuilt to see any of this
     90 
     91 Six screens were renamed or restructured, and each one failed in a way that
     92 reads like a defect rather than a rename:
     93 
     94 | what changed | what it looked like |
     95 | --- | --- |
     96 | the login form lays out its fields after its tab row | "no text field on screen at all", 11 scenarios out of 11 |
     97 | Settings moved the About rows into a lazy list, and the keyboard survives the move from the form | the terminal reported itself bound to no instance |
     98 | "Approve refund" became "Refund Taler" | five malformed refund amounts "refused in silence" |
     99 | "No instance?" became "No account?" | the demo-credentials button could not be found |
    100 | the checkout's compact layout says "Total: X" where the wide one says "Order total" | the checkout had no amounts on a phone |
    101 | sub-screens have a Back arrow where the drawer button is, and both are unlabelled in the dump | navigation pressed Back and then tapped whatever was underneath |
    102 
    103 And two bugs in the harness itself, both of which had been quietly inventing
    104 findings:
    105 
    106 * **`Screen.tap_target` skipped disabled clickables.** A label inside a
    107   disabled button resolved to the nearest *enabled* neighbour -- for the
    108   keypad's Charge button, a digit key three rows up -- so the caller read that
    109   key's state and reported that charging nothing was allowed. It is not: the
    110   button is correctly disabled, in this build and the last one.
    111 * **`tap_button` could not reach a control a lazy list had not composed yet**,
    112   which is where Connect lives once the keyboard is up.
    113 * **`total_amount` is only in an *unpaid* order's status.** Once an order is
    114   paid the figure moves to `contract_terms.amount`, so the check that the
    115   wallet had been asked for four units rather than six read the correct order
    116   as an order for nothing -- on the one scenario the whole feature exists
    117   for. `_order_amount` now reads whichever field is there.
    118 * **A history entry has no `order_status`.** The same confusion one level
    119   down: `GET /private/orders` returns `paid`, and asking those entries for
    120   `order_status` made every one of them look unpaid. Between this and the
    121   line above, *both* of the suite's "ask the backend what really happened"
    122   checks were reading the wrong field of the right endpoint.
    123 
    124 ## What was added
    125 
    126 * **A driver for the checkout**: payment options and their switches, the cash
    127   keypad and its fraction shortcuts, the change dialog, the payment lines, and
    128   abandoning a sale that already holds money.
    129 * **Fifteen scenarios**, over the checkout, payment options, the external
    130   refund, the display-pairing wizard, and the login form's own geometry.
    131 * **`driver/inventory.py`**, which puts six deliberately awkward products on
    132   the *demo* instance -- a real PNG, a description no column fits, a fraction
    133   of a kilogram, four scripts and an emoji, one cent, and nothing at all. The
    134   mock can answer anything, which is exactly why it cannot settle what the
    135   order grid and the order-details page do with goods a merchant really sold:
    136   the mock's products are never bought, never recorded in a contract and never
    137   read back out of an order.
    138 
    139 ## Coverage
    140 
    141 Against the terminal as it now is -- 11,821 lines where rounds one to three
    142 measured 4,864 -- after the round's own run:
    143 
    144 | | covered |
    145 | --- | --- |
    146 | instruction | 63,432 / 97,974 (**64.7%**) |
    147 | line | 7,827 / 11,821 (**66.2%**) |
    148 | branch | 2,453 / 5,294 (46.3%) |
    149 | method | 1,524 / 2,446 (62.3%) |
    150 | class | 242 / 318 (76.1%) |
    151 
    152 Reachable lines -- discounting the 205 in bodies a `sim` build cannot enter at
    153 all -- are **67.4%**, against a ceiling this report can never read above 98.3%.
    154 The run was 66 scenarios on the tablet worker (47 ok, 17 unreached, 2 harness
    155 errors) plus the mock set across two phones.
    156 
    157 The figure is not comparable with round three's 88.7% of reachable lines:
    158 that was a different, much smaller app. What it says is that two thirds of a
    159 terminal nobody had driven is now driven, and where the remaining third is:
    160 
    161 | package | covered | what is left |
    162 | --- | --- | --- |
    163 | `paymentoptions.sumup` | 19.4% | needs an affiliate key and a card reader |
    164 | `devices` | 37.7% | needs a Bluetooth or USB display to pair with |
    165 | `amount` | 50.0% | the compact-phone keypad arm |
    166 | `paymentoptions` | 58.2% | the card tiles, which need a provider |
    167 | `checkout` | 68.1% | the card dialog and pending-charge recovery |
    168 | `history` | 67.6% | the order-details page's delivery and reorder blocks |
    169 
    170 `devices` went 17.9% -> 37.7%, `checkout` 48.0% -> 68.1% and `refund`
    171 52.1% -> 79.1% over the round, on the back of the pairing-wizard, checkout and
    172 external-refund scenarios.
    173 
    174 ## One thing left half-looked-at
    175 
    176 The terminal fetches the order history in the background, and when that fetch
    177 fails it raises a **modal** error dialog over whatever the cashier is doing --
    178 `payment_options_summary_counts` failed four times in a row at
    179 `Settings`, with
    180 
    181 ```
    182 ['Error fetching the order history', 'Server error (502)', 'OK']
    183 ```
    184 
    185 on screen, in a scenario that never opened the history list. The message
    186 itself is fine; what is questionable is a background refresh the cashier did
    187 not ask for taking the whole screen. The demo backend was answering 502
    188 intermittently all evening under five emulators, which is what exposed it and
    189 also what makes it hard to say exactly when the dialog is raised -- so this is
    190 recorded rather than filed. A mock that answers 502 on `private/orders` and
    191 nothing else would settle it in one scenario.
    192 
    193 ## Two the fault set turned up, both now answered
    194 
    195 Both were investigated after the round proper, one agent each. They came out
    196 opposite ways, which is the useful part.
    197 
    198 ### A fifth defect, filed
    199 
    200 [Every failed delete says a wallet claimed the
    201 order](force-delete-blames-a-wallet.md) --
    202 [11977](https://bugs.gnunet.org/view?id=11977). `tryDeleteOrder` raises the
    203 force-delete prompt on *any* failure and throws the reason away, so a network
    204 error, a 5xx, an expired token and a 404 all tell the cashier "This order has
    205 been claimed by a wallet". The episode now records the backend saying
    206 `order_status='unpaid'` about the very order the dialog claims a wallet has
    207 taken. `HistoryManager.deleteOrder` has the same shape; the correct pattern,
    208 which asks `checkOrder` first, is twenty lines above it in the same file.
    209 
    210 The hypothesis this started from -- that the scenario's sustained twister
    211 mutation had corrupted the DELETE -- was **refuted**. The truth is blunter:
    212 `taler-twister` proxies PUT, POST and GET and closes the connection on
    213 anything else, so no DELETE has ever reached a backend through it. That is
    214 recorded in the finding, because it applies to every `fault_*` scenario that
    215 needs a delete to land.
    216 
    217 ### An own goal, not a defect
    218 
    219 The "unreadable order reply leaves two orders behind" finding was mine. Only
    220 one of the two orders came from the device under test: Cash was not enabled in
    221 that run, so the checkout never engaged, the legacy path ran, and the scenario
    222 contains exactly one `POST /private/orders`. The other, `pos-4438f610-...`,
    223 belonged to **another worker** on the same shared instance -- and it was
    224 *paid*.
    225 
    226 Two harness bugs, both now fixed:
    227 
    228 * `unpaid = [o for o in fresh if o.get("order_status") != "paid"]` asks a
    229   history entry for a field it does not have. `GET /private/orders` returns
    230   `paid`; `order_status` belongs to `GET /private/orders/{id}`. The key is
    231   absent, so `!= "paid"` was true of every order, paid ones included. This is
    232   the same mistake as the `total_amount` one, in the same direction: reading a
    233   field of the per-order endpoint off a list entry.
    234 * `EXCLUSIVE_DEMO` -- the guard that exists to suppress exactly this count --
    235   was never set. `suite.py` said "the campaign sets it"; `campaign.py` set
    236   only `POS_WORKER` and `POS_MOCK_PORT`. It is set now, and only for the one
    237   worker that owns the demo plan.
    238 
    239 A re-run while the other agent was working made it vivid: one device `POST`,
    240 **four** accused orders, two of them carrying a summary that exists nowhere in
    241 this tree.
    242 
    243 ## What is left
    244 
    245 1. **`devices/` is 17.9% covered**, and most of the rest needs hardware: a
    246    Bluetooth display to pair with, a USB one to enumerate. The wizard is
    247    walked as far as a scan that finds nothing.
    248 2. **SumUp is 19.4%**, and the build has no affiliate key, so the option
    249    reports "Setup is unavailable in this build" and its whole charge path is
    250    out of reach. A key would open roughly 1,500 lines.
    251 3. **The `mock` backend does not speak protocol 42**, so every checkout
    252    scenario needs the real demo instance and they cannot be parallelised.
    253    Teaching `mockd.py` the mixed-payment endpoints -- `collect`,
    254    `refund-external` -- would move the whole set onto workers of their own.
    255 4. **Three controls on the tablet's custom-product dialog and two on its
    256    history screen have no accessible name.** Round one's finding 9 was fixed
    257    for the controls that existed then; these are new.