SCREENSHOTS.md (9068B)
1 # Merchant Terminal screenshots 2 3 This module now has a debug-only screenshot mode for deterministic captures of real app screens. 4 5 ## What it does 6 7 - Launches the app directly into a named scenario using an intent extra. 8 - Seeds fixed merchant config, products, totals, and product thumbnails in-process. 9 - Renders production Compose screens with fixed, inert state for settings, payment options, 10 payment receipts, order details, refunds, and checkout states. 11 - Captures the resulting screen with `adb exec-out screencap`. 12 13 Bundled fixture product images are generated locally by `merchant-terminal/scripts/generate-screenshot-product-images.sh`, so the default workflow does not depend on third-party image licenses. 14 15 ## Supported scenarios 16 17 - `amount-entry` 18 - `order` 19 - `payment` 20 - `payment-claimed` (claimed Taler payment and waiting state) 21 - `payment-external` (zero-balance checkout with local collection action) 22 - `payment-success` 23 - `settings` and `settings-logout` (the first logout confirmation) 24 - `payment-options`, `payment-taler`, `payment-cash`, and `payment-sumup` 25 - `login`, `mfa-select`, and `mfa-code` 26 - `order-custom` and `order-custom-added` 27 - `refund`, `refund-mixed`, and `refund-qr` 28 - `checkout`, `checkout-partial`, `checkout-settled`, and `checkout-noreader` 29 - `navigation` 30 - `history-mixed` (mixed, partially paid and fully external orders) 31 - `history-external-refund` (external refund status and amount) 32 - `order-details` (a fully paid split payment: cash 5.00, card 10.00, Taler 5.40 CHF; rotates with the device) 33 - `order-details-partial` (cash and card paid: 15.00 CHF; Taler balance still due: 5.40 CHF) 34 - `order-details-minimal` (an order without optional contract fields) 35 - `order-details-loading` and `order-details-error` (loading and retry states) 36 - `history-order-details` (tap the history card to open details, then use Back) 37 38 ## Generate fixture product images 39 40 ```bash 41 merchant-terminal/scripts/generate-screenshot-product-images.sh 42 ``` 43 44 The images are written to `merchant-terminal/src/debug/assets/screenshot-products/`. 45 46 ## Capture screenshots 47 48 Use Python 3.10+, Pillow, adb and a dedicated emulator with the debug APK installed. 49 The activity hides Android system bars and uses the prepared café demo with generic 50 Card labels. It does not perform payments or test real Bluetooth/USB hardware. 51 The script requires an explicit emulator serial and never selects the connected 52 physical tablet automatically. 53 54 ```sh 55 python3 -m pip install -r merchant-terminal/design/google-play/requirements.txt 56 merchant-terminal/scripts/generate-screenshot-product-images.sh 57 ./gradlew :merchant-terminal:assembleDebug 58 adb -s emulator-5560 install -r merchant-terminal/build/outputs/apk/debug/merchant-terminal-debug.apk 59 ``` 60 61 Play Store rendering also needs `rsvg-convert` 62 from librsvg on PATH (`brew install librsvg` on macOS). 63 64 ```sh 65 # All tutorial scenarios, both themes, phone and tablet. 66 python3 merchant-terminal/scripts/capture-screenshots.py --set tutorials --serial emulator-5560 67 68 # Eight selected screens per device, with the approved Play Store templates. 69 python3 merchant-terminal/scripts/capture-screenshots.py --set play-store --serial emulator-5560 70 71 # Both subsets in one run. 72 python3 merchant-terminal/scripts/capture-screenshots.py --set all --serial emulator-5560 73 ``` 74 75 `capture-screenshots.sh` forwards the same options to this command. It no longer 76 boots or chooses a device, builds the app, or accepts positional output/scenario 77 arguments. The separate `capture-tutorials.py` has been replaced by this flow. 78 79 Outputs contain only images, with no website, manifests, contact sheets or RST: 80 81 ```text 82 merchant-terminal/build/screenshots/ 83 tutorials/en/{phone-portrait,tablet-landscape}/{light,dark}/*.png 84 play-store/captures/en/{phone-portrait,tablet-landscape}/{light,dark}/*.png 85 play-store/phone/01-products.png ... 08-dark-mode.png 86 play-store/tablet/01-products.png ... 08-dark-mode.png 87 ``` 88 89 Tutorial captures retain their existing numbered filenames and sizes: phone 90 1080 × 2340 and tablet 2560 × 1600. Play Store captures use phone 1080 × 2400 91 and tablet 1920 × 1080 to fit the templates; finished cards are 1080 × 1920 and 92 2560 × 1440 respectively. The eight cards and their themes are defined once in 93 [design/google-play/cards.json](design/google-play/cards.json). 94 95 Narrow any run using `--profiles`, `--themes`, and `--scenarios`, or set `--out`: 96 97 ```sh 98 python3 merchant-terminal/scripts/capture-screenshots.py \ 99 --set tutorials --serial emulator-5560 --scenarios order payment \ 100 --profiles phone-portrait --themes light --locales en de fr \ 101 --out merchant-terminal/build/screenshot-check 102 ``` 103 104 The default locale is English. Tutorial captures also support German and French; 105 Play Store headlines currently support English only. `--plan` lists the selected 106 captures without adb or file writes. `--resume` validates and reuses existing PNGs. 107 `--adb /path/to/adb` selects a custom executable. Display size, density, rotation 108 and font scale are restored even after failure. A missing ready signal, wrong 109 size/orientation or blank screenshot fails the run. 110 111 To apply the templates to an existing set of Play Store captures without adb: 112 113 ```sh 114 python3 merchant-terminal/scripts/capture-screenshots.py \ 115 --set play-store --from-captures /path/to/captures \ 116 --out merchant-terminal/build/store-refresh 117 ``` 118 119 The input root must contain `en/phone-portrait` and `en/tablet-landscape` with the 120 filenames and themes from `cards.json`, at the Play Store capture sizes above. 121 This keeps UI capture and template rendering in one flow while allowing either 122 step to be rerun. Generated outputs do not overwrite Fastlane's published assets. 123 124 For separately captured live-tablet images, hide the status bar, verify the PNGs, 125 and restore the tablet's display settings afterwards. 126 127 Run the capture-flow tests with: 128 129 ```sh 130 python3 -m unittest discover -s merchant-terminal/scripts/tests -v 131 ``` 132 133 ## Intent hook 134 135 The debug hook is activated by `ScreenshotActivity` with: 136 137 ```text 138 --es screenshot_scenario <scenario> 139 ``` 140 141 Example: 142 143 ```bash 144 adb shell am start -W \ 145 -n net.taler.merchantpos/.debug.ScreenshotActivity \ 146 --es screenshot_scenario order --es screenshot_locale en 147 ``` 148 149 ## If you want real photos later 150 151 For external product photos, use sources with clear reuse terms and record the exact asset URLs and license notes alongside the files you import. 152 153 Reasonable options: 154 155 - Pexels license: https://www.pexels.com/license/ 156 - Unsplash license: https://unsplash.com/license 157 - Wikimedia Commons reuse guide: https://commons.wikimedia.org/wiki/Commons:Simple_media_reuse_guide 158 159 For maximum simplicity in a repo, prefer public-domain or CC0 assets, or keep using locally generated fixture images for screenshot automation. 160 161 ## Order details layout checks 162 163 The order details scenarios use `ScreenshotActivity` directly: 164 165 ```bash 166 adb shell am start -W -n net.taler.merchantpos/.debug.ScreenshotActivity \ 167 --es screenshot_scenario order-details --es screenshot_locale en 168 ``` 169 170 Capture phone portrait and landscape and tablet portrait and landscape. The detail 171 screen uses one column below 760 dp of effective width (accounting for font scale), 172 and two columns above that threshold, with a maximum content width of 1200 dp. 173 Check the lower sections by scrolling, long URLs, German labels, and large text. 174 The production history and details routes permit device rotation, including returning 175 from details to history. Verify this flow in both orientations. History cards keep their 176 status badge at the upper right and show total, paid, and remaining amounts. The Order 177 Details action row keeps refund and delete actions compact on narrow screens. Settings, 178 sign-in, payment options, refund forms, and refund QR layouts support both orientations. 179 180 ## Refund and delete checks 181 182 - `refund-mixed` shows cash, card, and Taler refund choices with the original payment limits. 183 Select each method, enter a partial amount, and inspect the confirmation. Screenshot 184 fixtures never execute refunds. Cash/card confirm money already returned outside the app. 185 - `order-details-partial`: tap Delete, check the first warning, Continue, then the final 186 destructive confirmation. Cancel at either step must return without deleting anything. 187 - Paid details show a disabled Delete button. Refund Taler appears only while its portion 188 is still refundable; external payments use the general Refund screen. 189 - Refund forms and refund QR collection rotate with History and Order details. QR collection 190 stacks the QR, amount, order details, and action in portrait, and uses two columns in 191 landscape. Check phone and tablet portrait and landscape, large text, 192 the keyboard, and German translations. External refunds require the matching payment 193 record on this device. Provider-side card refunds remain manual. 194 195 The `order-details` fixture includes a product image. Tap its 48 dp thumbnail to 196 open the larger preview; close it with Back or the close button. 197 Products without images reserve no thumbnail space. Check both orientations.