feat(handbook): Maestro Tier 3 flows + screenshot-driven handbook#441
Merged
Conversation
Setup for the User-Guide + Test-Doku-in-einem handbook, modelled on zk-coins/app/public/handbook but adapted for Flutter / Maestro Tier 3 (deferred Phase 3 of #314 in docs/testing.md). Today: one .maestro flow (01-welcome.yaml) + three screenshots + static HTML page that mirrors the zkCoins layout (sticky TOC, spec sections, callouts). Reproducible locally — no online hosting: flutter build ios --simulator --debug xcrun simctl install booted build/ios/iphonesimulator/Runner.app scripts/run-handbook-flows.sh open docs/handbook/de/index.html Next stages add more flows (Create Wallet, Restore, KYC, Buy, Sell, etc.) — each is a new YAML file + new section block in docs/handbook/de/index.html. README under docs/handbook/ documents the workflow.
Extends the handbook scaffold from one welcome flow to the full
onboarding + settings journey, captured as visual-regression
baselines and rendered into docs/handbook/de/index.html.
Flows (.maestro/handbook/):
01 welcome 02 create-vs-restore 03 sw-wallet-terms
04 seed-hidden 05 seed-revealed 06 verify-seed
07 onboarding-done 08 pin-setup 09 pin-confirm
10 biometric-prompt 11 dashboard 12 settings
13 languages 14 currency 15 network
16 wallet-address 17 backup-pin 18 seed-hidden(s)
19 seed-revealed(s)
Capture pipeline (scripts/run-handbook-flows.sh):
* simctl shutdown/erase/boot/install before the batch — Maestro
clearState does not wipe the iOS Keychain, so a stale wallet+PIN
would survive between runs.
* Per flow: maestro test, then xcrun simctl io booted screenshot.
Maestro's own takeScreenshot renders BackdropFilter layers
(SeedBlurCard) as solid black; xcrun uses the simulator
compositor and captures them correctly.
* Stages PNG in /tmp first to dodge the simctl io TCC restriction
on ~/Documents.
Handbook (docs/handbook/de/index.html):
* TOC + 7 spec sections covering all 19 screens.
* Each test card links its source YAML on GitHub.
* Info callout documents the xcrun + simctl erase choice.
README (docs/handbook/README.md) explains the workflow for adding
a new flow.
The scaffold PR (#439) was squash-merged onto develop while this branch already had the file renamed to .maestro/handbook/01-welcome.yaml. The merge re-introduced the old path from develop's side; remove it so only the handbook/ copy remains.
4 tasks
TaprootFreak
added a commit
that referenced
this pull request
May 18, 2026
## Summary Container image and build workflows that publish the handbook to Docker Hub so it can be served online via Cloudflare Tunnel (target hosts: \`handbook.realuni.app\` / \`dev-handbook.realuni.app\`). The hosting side — compose stack + tunnel ingress + DNS — is a separate PR against \`DFXswiss/server\`. - \`Dockerfile.handbook\` + \`handbook.nginx.conf\`: \`nginx:1.27-alpine\` serving \`docs/handbook/\`, redirects \`/\` → \`/de/\`. - \`.github/workflows/handbook-dev.yaml\`: on push to \`develop\` (paths-filtered to \`docs/handbook/\`, the Dockerfile, or the workflow itself) → build + push \`dfxswiss/realunit-app-handbook:beta\`. - \`.github/workflows/handbook-prd.yaml\`: same for \`:latest\` on \`main\`. - No SSH-deploy step yet. The pull side lives in \`DFXswiss/server\` and gets wired up once the compose stack + tunnel ingress exist for \`realunit-app-handbook\`. ## Why split this from the handbook content PR (#441)? #441 is purely local artefacts (Maestro flows, screenshots, HTML). This PR is hosting infrastructure with org-level secrets (\`DOCKER_USERNAME\` / \`DOCKER_PASSWORD\`) and a different review surface. ## Test plan - [x] Dockerfile builds locally (deferred — OrbStack not running on this machine; CI will validate) - [ ] CI: \`Handbook DEV image\` workflow succeeds on first run via \`workflow_dispatch\` after merge - [ ] Image \`dfxswiss/realunit-app-handbook:beta\` exists on Docker Hub - [ ] \`docker run -p 8080:8080 dfxswiss/realunit-app-handbook:beta\` serves the handbook on http://localhost:8080/de/ ## Follow-ups - \`DFXswiss/server\` PR: \`realuni.app\` Cloudflare zone + DNS, tunnel ingress (\`handbook.realuni.app\` → dfxprd, \`dev-handbook.realuni.app\` → dfxdev), \`dfxdev/realunit-app-handbook/\` + \`dfxprd/realunit-app-handbook/\` compose stacks, \`domains.md\` entry. **Prerequisite for that PR**: \`realuni.app\` zone must exist in the DFX Cloudflare account, NS pointed from Infomaniak to Cloudflare.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds 19 Maestro Tier 3 flows that double as visual-regression baselines for the RealUnit Wallet handbook (
docs/handbook/de/index.html). Each flow navigates to one screen; a wrapper script captures it withxcrun simctl io booted screenshotand writes the PNG intodocs/handbook/screenshots/.scripts/run-handbook-flows.sh):simctl shutdown/erase/boot/installbefore the batch (Keychain wipe —clearStatealone leaves the wallet + PIN behind), then per flowmaestro testfollowed byxcrun simctl io booted screenshotstaged through/tmp.takeScreenshot: FlutterBackdropFilter(SeedBlurCard) renders to GPU layers that the XCUITest screenshot API misses — Maestro's output is solid black. The simulator compositor captures them correctly.docs/handbook/de/index.htmlextended with a 7-section TOC; each test card links its source YAML on GitHub.docs/handbook/README.mddocuments the regeneration workflow.Test plan
scripts/run-handbook-flows.shruns end-to-end, all 19 flows passdocs/handbook/de/index.htmlopens locally without a webserver; all 19 images resolve via relative pathsdocs/handbook/de/index.htmlin a browser and verify the TOC + screenshot grid rendersFollow-ups (separate PRs)
handbook.realuni.app/dev-handbook.realuni.app) —Dockerfile.handbookhere + Cloudflare/Tunnel config inDFXswiss/server. Domainrealuni.appis at Infomaniak; tunnel target isdfxprd.