taler-android

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

capture-screenshots.py (11224B)


      1 #!/usr/bin/env python3
      2 """Capture POS screenshot subsets and optionally apply the Play Store templates.
      3 
      4 Requires an installed debug APK on an explicitly selected emulator, adb and Pillow.
      5 Outputs images only. Use --plan to inspect the selected captures without a device.
      6 """
      7 import argparse
      8 from dataclasses import dataclass
      9 import io
     10 import json
     11 from pathlib import Path
     12 import shutil
     13 import subprocess
     14 import sys
     15 import time
     16 
     17 from PIL import Image, ImageStat
     18 
     19 ROOT = Path(__file__).resolve().parents[1]
     20 DESIGN = ROOT / 'design/google-play'
     21 APP = 'net.taler.merchantpos'
     22 # Keep this order stable: tutorial filenames are referenced by existing documents.
     23 SCENARIOS = [
     24     'login',
     25     'mfa-select',
     26     'mfa-code',
     27     'camera-rationale',
     28     'camera-blocked',
     29     'navigation',
     30     'order',
     31     'quantity-before',
     32     'quantity-after',
     33     'order-cleared',
     34     'order-custom',
     35     'order-custom-added',
     36     'amount-entry',
     37     'checkout',
     38     'checkout-cash-entry',
     39     'checkout-card-entry',
     40     'checkout-partial',
     41     'checkout-payments',
     42     'checkout-settled',
     43     'checkout-noreader',
     44     'payment',
     45     'payment-claimed',
     46     'payment-external',
     47     'payment-success',
     48     'history',
     49     'history-mixed',
     50     'history-external-refund',
     51     'order-details',
     52     'order-details-partial',
     53     'order-details-minimal',
     54     'order-details-loading',
     55     'order-details-error',
     56     'refund',
     57     'refund-mixed',
     58     'refund-qr',
     59     'settings',
     60     'settings-logout',
     61     'payment-options',
     62     'payment-cash',
     63     'payment-card',
     64     'displays-empty',
     65     'displays-add',
     66     'displays-access',
     67     'displays-settings',
     68     'displays-pair',
     69     'displays-find',
     70     'displays-pairing',
     71     'displays-ready',
     72     'displays-connected',
     73     'displays-test',
     74     'displays-disconnected',
     75     'displays-remove',
     76     'displays-usb',
     77     'displays-repair-android',
     78     'displays-repair-lcd',
     79     'order-details-products',
     80     'settings-about',
     81     'order-catalogue-more',
     82     'payment-partial',
     83 ]
     84 SCROLLED = {
     85     'order-details-products': 'order-details',
     86     'settings-about': 'settings',
     87     'order-catalogue-more': 'order',
     88 }
     89 # wm size, density, rotation, expected PNG size
     90 PROFILES = {
     91     'tutorials': {
     92         'tablet-landscape': ('1600x2560', '320', '1', (2560, 1600)),
     93         'phone-portrait': ('1080x2340', '420', '0', (1080, 2340)),
     94     },
     95     'play-store': {
     96         'tablet-landscape': ('1080x1920', '240', '1', (1920, 1080)),
     97         'phone-portrait': ('1080x2400', '420', '0', (1080, 2400)),
     98     },
     99 }
    100 
    101 
    102 @dataclass(frozen=True)
    103 class Capture:
    104     subset: str
    105     profile: str
    106     locale: str
    107     theme: str
    108     scenario: str
    109     path: Path
    110     card: str | None = None
    111 
    112 
    113 def plan(args, cards):
    114     jobs = []
    115     subsets = list(PROFILES) if args.subset == 'all' else [args.subset]
    116     for subset in subsets:
    117         for profile in args.profiles or PROFILES[subset]:
    118             if subset == 'tutorials':
    119                 choices = [(None, f'{i:02d}-{s}.png', s, theme)
    120                            for i, s in enumerate(SCENARIOS, 1)
    121                            for theme in args.themes or ['light', 'dark']]
    122             else:
    123                 choices = [(name, card['screenshot'], Path(card['screenshot']).stem.split('-', 1)[1], card['theme'])
    124                            for name, card in cards.items()]
    125             for locale in args.locales:
    126                 for card, filename, scenario, theme in choices:
    127                     if args.scenarios and scenario not in args.scenarios:
    128                         continue
    129                     if args.themes and theme not in args.themes:
    130                         continue
    131                     base = args.out / subset
    132                     if subset == 'play-store':
    133                         base = args.from_captures or base / 'captures'
    134                     jobs.append(Capture(subset, profile, locale, theme, scenario,
    135                                         base / locale / profile / theme / filename, card))
    136     return jobs
    137 
    138 
    139 def check_image(data, expected, label):
    140     with Image.open(io.BytesIO(data)) as original:
    141         image = original.convert('RGB')
    142         if image.size != expected:
    143             raise RuntimeError(f'Wrong screenshot size for {label}: {image.size}, expected {expected}')
    144         if max(ImageStat.Stat(image).stddev) < 3:
    145             raise RuntimeError(f'Blank screenshot: {label}')
    146 
    147 
    148 def capture(jobs, args):
    149     def adb(*cmd, binary=False):
    150         return subprocess.check_output([args.adb, '-s', args.serial, *cmd], timeout=45, text=not binary)
    151 
    152     saved = {key: adb('shell', 'settings', 'get', 'system', key).strip()
    153              for key in ['accelerometer_rotation', 'user_rotation', 'font_scale']}
    154     originals = {key: adb('shell', 'wm', key) for key in ['size', 'density']}
    155     active = None
    156     try:
    157         adb('shell', 'settings', 'put', 'system', 'accelerometer_rotation', '0')
    158         adb('shell', 'settings', 'put', 'system', 'font_scale', '1.0')
    159         for job in jobs:
    160             size, density, rotation, expected = PROFILES[job.subset][job.profile]
    161             if args.resume and job.path.exists():
    162                 check_image(job.path.read_bytes(), expected, job.path)
    163                 continue
    164             if active != (job.subset, job.profile):
    165                 adb('shell', 'am', 'force-stop', APP)
    166                 adb('shell', 'wm', 'size', size)
    167                 adb('shell', 'wm', 'density', density)
    168                 adb('shell', 'settings', 'put', 'system', 'user_rotation', rotation)
    169                 active = (job.subset, job.profile)
    170             scenario = SCROLLED.get(job.scenario, job.scenario)
    171             adb('shell', 'am', 'force-stop', APP)
    172             adb('logcat', '-c')
    173             adb('shell', 'am', 'start', '-W', '-n', APP + '/.debug.ScreenshotActivity',
    174                 '--es', 'screenshot_scenario', scenario, '--es', 'screenshot_locale', job.locale,
    175                 '--ez', 'screenshot_dark', str(job.theme == 'dark').lower())
    176             # Activity launch can restore a previous rotation on Android 17.
    177             # Apply the capture orientation once the activity is foregrounded.
    178             adb('shell', 'wm', 'user-rotation', 'lock', rotation)
    179             deadline = time.monotonic() + 25
    180             while True:
    181                 log = adb('logcat', '-d', '-s', 'SCREENSHOT_READY:I', '*:S')
    182                 if any(line.rstrip().endswith(': ' + scenario) for line in log.splitlines()):
    183                     break
    184                 if time.monotonic() > deadline:
    185                     raise RuntimeError(f'No ready signal: {job.path}')
    186                 time.sleep(.2)
    187             time.sleep(8 if scenario in ('payment', 'payment-partial', 'payment-external', 'refund-qr') else 1.5)
    188             if job.scenario in SCROLLED:
    189                 w, h = expected
    190                 start_y = .5 if job.scenario == 'order-catalogue-more' else .65
    191                 adb('shell', 'input', 'swipe', str(w // 2), str(int(h * start_y)),
    192                     str(w // 2), str(int(h * .18)), '700')
    193                 time.sleep(1)
    194             png = adb('exec-out', 'screencap', '-p', binary=True)
    195             check_image(png, expected, job.path)
    196             job.path.parent.mkdir(parents=True, exist_ok=True)
    197             job.path.write_bytes(png)
    198             print(f'Captured {job.path}', flush=True)
    199     finally:
    200         # Attempt every restore even if a disconnected device makes one fail.
    201         commands = [('shell', 'am', 'force-stop', APP)]
    202         for command, original in originals.items():
    203             override = next((line.split(':', 1)[1].strip() for line in original.splitlines()
    204                              if line.startswith('Override')), 'reset')
    205             commands.append(('shell', 'wm', command, override))
    206         for key, value in saved.items():
    207             commands.append(('shell', 'settings', 'delete' if value == 'null' else 'put', 'system', key,
    208                              *([] if value == 'null' else [value])))
    209         errors = []
    210         for command in commands:
    211             try:
    212                 adb(*command)
    213             except (OSError, subprocess.SubprocessError) as error:
    214                 errors.append(error)
    215                 print(f'Could not restore emulator setting: {command}: {error}', file=sys.stderr)
    216         if errors and sys.exc_info()[0] is None:
    217             raise RuntimeError('Could not restore all emulator settings') from errors[0]
    218 
    219 
    220 def render(jobs, args):
    221     selected = [job for job in jobs if job.subset == 'play-store']
    222     # Fail before generating a partial set when reusing incomplete or wrong-size captures.
    223     for job in selected:
    224         check_image(job.path.read_bytes(), PROFILES[job.subset][job.profile][3], job.path)
    225     for job in selected:
    226         profile = 'phone' if job.profile == 'phone-portrait' else 'tablet'
    227         subprocess.run([sys.executable, str(DESIGN / 'render.py'), '--screenshot', str(job.path),
    228                         '--profile', profile, '--card', job.card, '--png-only',
    229                         '--out', str(args.out / 'play-store')], check=True)
    230 
    231 
    232 def main():
    233     parser = argparse.ArgumentParser(description=__doc__)
    234     parser.add_argument('--set', dest='subset', choices=[*PROFILES, 'all'], default='tutorials')
    235     parser.add_argument('--serial', help='Dedicated emulator serial (required for new captures)')
    236     parser.add_argument('--adb', default='adb')
    237     parser.add_argument('--out', type=Path, default=ROOT / 'build/screenshots')
    238     parser.add_argument('--profiles', nargs='+', choices=PROFILES['tutorials'])
    239     parser.add_argument('--themes', nargs='+', choices=['light', 'dark'])
    240     parser.add_argument('--locales', nargs='+', choices=['en', 'de', 'fr'], default=['en'])
    241     parser.add_argument('--scenarios', nargs='+', choices=SCENARIOS)
    242     parser.add_argument('--resume', action='store_true', help='Validate and reuse existing captures')
    243     parser.add_argument('--from-captures', type=Path, help='For play-store: render an existing capture root without adb')
    244     parser.add_argument('--plan', action='store_true', help='Print selected captures without writing files or using adb')
    245     args = parser.parse_args()
    246     if args.from_captures and args.subset != 'play-store':
    247         parser.error('--from-captures requires --set play-store')
    248     if args.subset in ('play-store', 'all') and args.locales != ['en']:
    249         parser.error('Play Store headlines currently support English only; use --locales en')
    250     cards = json.loads((DESIGN / 'cards.json').read_text())
    251     jobs = plan(args, cards)
    252     if not jobs:
    253         parser.error('No screenshots match the selected subset and filters')
    254     if args.plan:
    255         for job in jobs:
    256             print(f'{job.subset}: {job.profile}/{job.locale}/{job.theme}/{job.scenario} → {job.path}')
    257         print(f'{len(jobs)} captures')
    258         return
    259     if any(job.card for job in jobs) and not shutil.which('rsvg-convert'):
    260         parser.error('Play Store templates require rsvg-convert (librsvg) on PATH')
    261     if not args.from_captures:
    262         if not args.serial or not args.serial.startswith('emulator-'):
    263             parser.error('Select a dedicated emulator with --serial emulator-NNNN')
    264         capture(jobs, args)
    265     render(jobs, args)
    266 
    267 
    268 if __name__ == '__main__':
    269     main()