koopa-admin-log/scripts/taler-monitoring/android-test/AUTOMATED-GUI-NOTES.md

Automated GUI notes — Android wallet (vanilla level)

Goal: tests for two systems (GOA / hacktivism and stage TESTPAYSAN) that exercise the wallet graphically in the UI as far as practical, not only CLI/adb deep-links into wallet-core.

Vanilla level (this tree)

Layer	What we do	Tooling
A — Install	Install published F-Droid APK or APK built from taler-android master	adb install
B — Entry (shortcut)	Deliver withdraw / pay as taler://… intents	adb shell am start -a VIEW -d …
C — Graphical UI	Dump hierarchy, tap Confirm / ToS / Pay-like buttons, dismiss ANR	uiautomator dump + input tap (lib_ui.py)
D — Evidence	Screenshots + UI XML + logcat + JSON status	android-test/out-gui/

Scripts:

Script	Role
run-android-pay-smoke.sh	Install + deep-link + light taps (hybrid / CLI-heavy)
run-android-gui-smoke.sh	Vanilla GUI path: deep-link entry + multi-round UI driving
run-android-build-and-smoke.sh	Build latest source APK → same smoke (set GUI=1 to call GUI script)
lib_ui.py	Shared dump/tap/ANR helpers

cd scripts/taler-monitoring/android-test

# Published APK, graphical drive, both stacks
STACK=goa   ./run-android-gui-smoke.sh
STACK=stage ./run-android-gui-smoke.sh

# From-source APK + GUI
APK_PATH=~/taler/taler-android/wallet/build/outputs/apk/fdroid/debug/wallet-fdroid-debug.apk \
  PKG=net.taler.wallet.fdroid.debug \
  STACK=goa ./run-android-gui-smoke.sh

Legitimate shortcuts (document, do not hide)

These are not full human UX, but they are the same contracts as QR scan / paywall open on the landings:

Shortcut	Replaces	Why legitimate
adb VIEW taler://withdraw/…	Camera QR scan of communal / demo withdraw	Identical URI payload as landings (demo-withdraw.json)
adb VIEW taler://pay… / pay-template/…	Scan shop/paywall QR or open “pay with Taler”	Same URI merchant/backend would show
Host-side POST …/templates/{id} then pay URI	Browser shop UI to create order	Stage farmer templates are public; order create is API, pay is still wallet UI
Multi-language label list for taps	Human reading the button	Same visible buttons; brittle if copy changes
Skip full ToS reading	User scrolling long TOS	Tap “Accept” if shown; no legal review automation

Not automated yet (out of vanilla scope):

• Typing personal bank passwords into the wallet webview
• NFC
• Real camera / vision-based QR
• Biometric unlock
• Full onboarding wizard every time (we force-stop + re-intent)

Two systems under test

Stack	Withdraw source	Pay source
GOA (STACK=goa)	https://bank.hacktivism.ch/intro/demo-withdraw.json	taler://pay-template/taler.hacktivism.ch/instances/goa-shop/paivana (Paivana)
stage (STACK=stage)	https://stage.bank.lefrancpaysan.ch/intro/demo-withdraw.json	Public template e.g. fermes-des-collines / panier-legumes → taler://pay/…

Both use the same GUI driver (lib_ui.py); only URLs and package under test differ.

GUI driver behaviour (lib_ui.gui_drive)

1. Every round: uiautomator dump + optional screencap.
2. If “System UI isn’t responding” → tap Wait (prefer over Close).
3. Else try exact taps on Confirm / Withdraw / Accept / Pay / DE/FR synonyms.
4. Else regex partial match on those words.
5. Repeat GUI_ROUNDS times (default 10), GUI_SLEEP seconds apart.

Success signals (layered):

• Intent delivered — am start OK
• wallet-core — logcat prepareBankIntegratedWithdrawal / pay-related ops
• GUI taps — non-empty taps in gui-*-status.json
• Screenshots — human-readable progress under gui-withdraw/ / gui-pay/

A run can be “vanilla-partial” if intents + some taps succeed but final balance/settlement is not asserted (settlement still better covered by taler-monitoring.sh e2e CLI wallet).

Host limits (clementine, 2026-07)

Constraint	Effect
~3.7 GiB RAM	Emulator ANRs; GUI rounds often only dismiss ANR
Prefer physical phone or ≥6–8 GiB host	Real Confirm/Pay taps complete more often
No root required	User SDK + adb + F-Droid/source APK

Relation to CLI e2e

Suite	Strength
taler-monitoring.sh e2e / ladder	Full withdraw+pay settlement via taler-wallet-cli
run-android-gui-smoke.sh	Android app UI surface for the same stacks
Combined	CLI = money path green; GUI = app UX green as far as taps go

Upstream: taler-android dev/hernani-inference/*

Branch name is hernani-inference (not “inferenced”). Remote: git@git.taler.net:taler-android.git.

Branch	Relevance for automation
dev/hernani-inference/gui-workflows	Primary: macOS emulator helpers + GOA GUI chain (scripts/goa-chain-emu.sh, docs/gui-workflows.md, setup-avds.sh, start-emulators.sh). Deep-link + uiautomator text taps + bank API mint + shop templates.
fix/bank-withdraw-auto-exchange	App fix: resolve exchange when bank omits it (needed for GOA withdraw UI).
fix/withdraw-spinner-fallback	App fix: stop endless withdraw spinner (+ OIM UI work).
experimental-oim / experimental-oim-pos	Experimental cash denomination UI; optional for demos, not required for chain.

Port into this tree (Linux-capable)

Upstream (gui-workflows)	Here (android-test/)
goa-chain-emu.sh	run-goa-gui-chain.sh (goa + stage, Linux paths, explorer secrets as monitoring ladder)
tap_text / click_through	same idea in chain + lib_ui.py
mint_withdraw explorer API	same (Basic → token → POST withdrawals)
mint_pay public templates	same (goa-shop products / stage fermes templates)
android-env.sh Homebrew	use $HOME/Android/Sdk + system adb (see GIT-AUTOMATION-NOTES)
macOS-only docs	Linux supported for chain/smoke; AVD setup still DIY on Linux

Open issues mirrored from upstream ISSUES.md (gui-workflows):

• I-and-gui-001 — taps still best-effort; ToS/confirm may need human
• I-and-gui-003 — EXP_PW_FILE required for mint
• I-and-gui-004 — emulator RAM cost (this host ~3.7 GiB)
• I-and-gui-007 — for reliable withdraw GUI, build/install app from fix/bank-withdraw-auto-exchange or fix/withdraw-spinner-fallback, not plain master alone

Ground rule (ops)

1. Bring it to run first (scripts + live stack).
2. App code changes only if needed, and minimal.
3. Prefer existing dev/hernani-inference/* branches over new ones; extend them rather than forking random trees.

Recommended demo stack (2026-07)

1) taler-android checkout:
     dev/hernani-inference/fix-bank-withdraw-auto-exchange
     (or fix/withdraw-spinner-fallback for spinner + OIM)
2) ./gradlew :wallet:assembleFdroidDebug   # package net.taler.wallet.fdroid.debug
3) Boot emulator / phone  (prefer ≥6–8 GiB host RAM; 4 GiB → System UI ANR)
4) android-test/run-goa-gui-chain.sh   # STACK=goa|stage

run-android-build-and-smoke.sh defaults BRANCH=dev/hernani-inference/fix-bank-withdraw-auto-exchange so source smokes pick up the GOA exchange auto-add fix without manual checkout.

Runtime note (clementine)

On ~3.7 GiB hosts the emulator often shows System UI isn’t responding before Confirm is tappable. Chain script now prioritizes Wait over hunting Confirm. For a green end-to-end GUI path use a physical device or more RAM — the mint + deep-link + fix-branch APK path is otherwise ready.

# GOA chain (explorer mint + GUI taps)
EXP_PW_FILE=$HOME/src/koopa/koopa-admin-secrets/koopa/host-root/taler-bank/bank-explorer-password.txt \
  STACK=goa PKG=net.taler.wallet.fdroid.debug \
  ./run-goa-gui-chain.sh

# Stage TESTPAYSAN (explorer via stagepaysan SSH if EXP_PW_FILE unset)
STACK=stage ./run-goa-gui-chain.sh

Future upgrades (not required for vanilla)

• Maestro / Appium flows with stable resource-ids
• Explicit wait for text “Withdrawal complete” / balance
• Port Paivana unlock scripts (upstream I-and-gui-002)
• Dual AVD wallet+POS (upstream I-and-gui-008)
• Record video (adb shell screenrecord) on failure

Checklist — “vanille erreicht?”

• Two stacks parameterized (goa / stage)
• Published APK path
• Source-build path (same smoke after build)
• Deep-link shortcuts documented
• Multi-round graphical taps (uiautomator)
• GOA-style chain (multi withdraw + multi pay) from inference branch
• Screenshots + UI XML + logcat artifacts
• Inference branch mapping documented
• Fully reliable unattended Confirm→settled on low-RAM emulator (host-limited)
• App built from withdraw-fix branch by default in build script (optional)
• Assert final balance in app UI (optional next step)