taler-android

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

ROUND3.md (7941B)


      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 three: what a merchant fills in, and what a cashier taps
     18 
     19 Round two broke the backend's replies. Round three went the other way and
     20 asked what the terminal does with a backend that is *working* but configured
     21 differently, and with sequences of taps nothing had performed.
     22 
     23 ## Coverage
     24 
     25 ```
     26                 round one      round two      round three
     27 instruction     77.3%          85.0%          85.8%
     28 branch          61.1%          66.6%          68.5%
     29 line            78.7%          85.4%          86.1%
     30 class           87.9%          92.9%          92.9%
     31 ```
     32 
     33 Branch coverage moved three times as far as line coverage this round, which is
     34 what a round of *variations* should do: the same lines, with the other value
     35 in the field.
     36 
     37 ### What the figures leave out
     38 
     39 146 of the 677 missed lines cannot be reached by any run of this build. Eight
     40 `internal fun *ScreenContent` composables render a screen from a fixture, and
     41 the only thing that calls them is `ScreenshotActivity` -- which lives in the
     42 `debug` source set, and `sim` is its own build type and does not include it.
     43 `OrderScreenContent` alone is 73 lines.
     44 
     45 `coverage/gaps.py` now discounts them, so the honest figure is
     46 
     47 ```
     48 reachable lines covered: 4187/4718 (88.7%); the ceiling is 97.0%
     49 ```
     50 
     51 and the ranking points at work that can actually be done.
     52 
     53 ## What a merchant fills in
     54 
     55 Almost everything a product can carry is optional, and the `healthy` mock
     56 profile fills in none of it. The new `rich-catalogue` profile fills in all of
     57 it, one product per thing the terminal does with the metadata:
     58 
     59 | Product | What it is for |
     60 | --- | --- |
     61 | Espresso | a picture, and a name that is not the description -- `displayName` takes the name and `displayDescription` the description, the only case where a card shows two lines |
     62 | Flour | stock as decimal strings (`unit_total_stock` and friends), which is `stockLimit`'s BigDecimal arm; an integer count never reaches it |
     63 | Pastry | six of six sold, so the card says "Out of stock" instead of offering it |
     64 | Tap water | unlimited stock written as `"-1"` rather than `-1` |
     65 | Hamper | a tax, a net price and a delivery location, which only `toContractProduct` looks at |
     66 | Daily paper | no picture at all, so a row mixes products with and without one |
     67 
     68 The pictures are real: `ConfigProduct.image` is a `data:image/png;base64,` URL,
     69 the grid decodes it in two places, and a row lays itself out differently when
     70 any product in it has one.
     71 
     72 Three more things the backend can be:
     73 
     74 * **`token-needs-prefix`** hands out a bare token and then refuses it, which is
     75   the only way to make `ConfigManager.fetchPosConfig` take its retry -- it
     76   sends the token as it has it, and on a 401 sends it again as
     77   `secret-token:<it>`.
     78 * **`mfa-two-channels`** and **`mfa-both-required`** (round two) now also cover
     79   giving up: cancelling the code prompt raises `ChallengeCancelledException`,
     80   which is its own arm of the login.
     81 * Finite stock makes the terminal fetch `/private/products/<id>` per product,
     82   so `enrichProductsWithStockDetails` runs for real; a restart afterwards
     83   exercises `applyCachedStockData`.
     84 
     85 ## What a cashier taps
     86 
     87 Six sequences that nothing had performed:
     88 
     89 * **Select an order line and press +1 and -1.** Adding a product is one tap and
     90   every scenario did it; selecting the resulting *line* and changing its
     91   quantity is three more, and `onSelectProduct`, `onIncrease` and `onDecrease`
     92   were untaken on both layouts. One Coffee at 5.50, +1 to 11.00, -1 back to
     93   5.50.
     94 * **An unparseable price in the custom-product dialog**, which is the arm that
     95   sets the error text rather than adding the product.
     96 * **"Show payment" on an unpaid order in the history**, which rebuilds a
     97   payment from a history entry alone (`PaymentManager.resumePayment`); every
     98   other route to the payment screen comes from having just created the order.
     99 * **"Show refund" after a restart**, when the refund the terminal held is gone
    100   and `resumeRefund` has to say so.
    101 * **A merchant URL pasted whole**, scheme and `/instances/<name>` and all,
    102   which is what `sanitizeMerchantUrlAndUpdateFields` is for.
    103 * **The login help card's other two buttons**, and logging in with "Remember
    104   password" unticked, which is the arm where `restoreCachedRuntimeConfig` has
    105   nothing to restore.
    106 
    107 ## Findings
    108 
    109 [On a phone, a form with a text field loses its buttons to the
    110 keyboard](refund-form-unusable-on-a-phone.md) -- the open question round two
    111 left, now answered with a photograph of each case. The refund form loses both
    112 fields and both buttons; the custom-product dialog keeps reporting its buttons
    113 at coordinates the keyboard is drawing over, so a tap aimed at **Add** presses
    114 the key underneath. Round two's findings 10 and 11 stand.
    115 
    116 ## False positives, found and removed
    117 
    118 | Reported | What it really was |
    119 | --- | --- |
    120 | `scheme-left-in-the-url-field`, `instance-path-not-split-out` | the form is only rewritten when it is submitted; the scenario read the fields before pressing Connect, and the login that followed bound the right instance |
    121 | `bad-custom-amount-unexplained` | the tap meant for **Add** landed on the keyboard, so nothing was submitted and there was nothing to explain -- which is the finding above, arrived at the wrong way round |
    122 
    123 And four harness bugs behind them:
    124 
    125 * **The raw tap action pressed keyboard keys.** `Action("tap_label", …)` taps
    126   wherever the dump says the label is, and for a dialog that can be behind the
    127   IME. It now declines, and `Pos.control_reachable` lets a scenario judge the
    128   app for it instead of tripping over it.
    129 * **The driver could not see the keyboard.** The IME is not in the
    130   accessibility dump and its window frame is the whole screen; the window
    131   manager publishes it as an inset, which is exact.
    132 * **Hiding the keyboard only when it is in the way** -- the fix that made the
    133   dialogs tappable -- broke the login form, which does *not* resize under the
    134   IME, so nothing said the keyboard was over the Connect button. Where the
    135   inset cannot be read, the driver now assumes it is in the way, as it did
    136   before.
    137 * **"Total:" is not the only wording.** The order pane's header says "Total: X"
    138   and the complete button says "Bill X"; the compact layout drops the header,
    139   so a scenario that knew only the first read an order with a total as an order
    140   without one.
    141 
    142 ## What is left
    143 
    144 1. **The QR configuration tab**, about 110 lines of `ConfigFragment` and
    145    `ConfigFragmentKt` -- the camera analyzer, the decode, and the phone half of
    146    the screen. All of it sits behind round one's finding 1, which is that the
    147    tab crashes on the first frame. The patch is written and verified; until it
    148    lands this is unreachable.
    149 2. **The phone and the mock cannot be combined.** A mock scenario has to
    150    provision through the login form, because a `taler-pos://` setup URI loses
    151    the port (round one, finding 7) -- and the login form does not fit a phone.
    152    A mock on port 443, which the harness runs as root and could bind, would
    153    need no port in the URI and would unblock the whole `mock` set on a phone.
    154 3. **`RefundUriFragmentKt` at 45.3%** is the largest single remainder, and it
    155    is the phone half of the refund QR screen, behind the finding above.