Skip to content

Commit f75a66c

Browse files
torlando-techtorlando-agent[bot]claudetorlando-agent[bot]
authored
feat: add Maestro UI flows for columba-suite ui-screenshotter (#69)
* feat: add Maestro UI flows for columba-suite ui-screenshotter agent Adds flows/ with 4 deterministic Maestro flows (contacts-list, chats-list, settings, map) plus a README. The columba-suite ui-screenshotter agent captures each flow at BASE_REF and HEAD in both light and dark Simulator appearances on every UI-touching PR, linking the resulting PNG pair from PLAN.md so reviewers see the visual change before merging. This PR exists primarily to land flows/ on main so subsequent PRs have flow coverage at BASE_REF. The screenshotter will fire on this PR itself, but cleanly skip with screenshot_status: skipped_no_flows because the PR's BASE_REF (this branch's parent) doesn't yet have flows/. Voice-call flows are deferred — they need a debug-only lxma://debug/... URL handler that doesn't exist yet. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(greptile): iteration 1 — applied 1, rejected 2 Co-Authored-By: Claude claude-opus-4-7 <noreply@anthropic.com> --------- Co-authored-by: torlando-agent[bot] <217870594+torlando-agent[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: torlando-agent[bot] <281092095+torlando-agent[bot]@users.noreply.github.com>
1 parent 371bb71 commit f75a66c

5 files changed

Lines changed: 177 additions & 0 deletions

File tree

‎flows/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Maestro UI flows
2+
3+
This directory holds [Maestro](https://maestro.mobile.dev/) flows the
4+
columba-suite **ui-screenshotter** agent runs against the iOS Simulator on
5+
each `columba-suite/*` PR that touches UI files. The agent captures
6+
each flow at BASE_REF and HEAD, in both light and dark Simulator
7+
appearances, and links the resulting PNG pair from the PR's PLAN.md so
8+
reviewers can see the visual change before merging.
9+
10+
## Adding a flow
11+
12+
1. New file `flows/<name>.yml`. Use existing flows as templates.
13+
2. Make it deterministic: `clearState: true` + `clearKeychain: true` on
14+
launch, handle the onboarding skip path, no network-state assumptions.
15+
3. End with `takeScreenshot: <name>` (the agent expects the PNG to land
16+
at `./<name>.png`).
17+
4. Don't add voice-call flows yet — they need a debug-only `lxma://debug/...`
18+
URL handler that doesn't exist (Stage 1 limitation).
19+
20+
## Running locally
21+
22+
```sh
23+
export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
24+
export PATH="$JAVA_HOME/bin:$HOME/.maestro/bin:$PATH"
25+
maestro --device <UDID> test flows/contacts-list.yml
26+
```
27+
28+
The `<UDID>` is from `xcrun simctl list devices booted`.
29+
30+
## Stage roadmap
31+
32+
- **Stage 1** (now): capture + write the table to PLAN.md only.
33+
- **Stage 2**: pixel diff column.
34+
- **Stage 3**: regression gating (PR fails if golden flow drifts > N%).
35+
- **Stage 4**: graduate to PR comments + GitHub-attachment uploads.
36+
37+
Plan: `~/.claude/plans/ui-screenshotter.md` (vault `Agent Plans/`).

‎flows/chats-list.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
appId: network.columba.Columba
2+
name: chats-list
3+
tags:
4+
- smoke
5+
- screenshot
6+
---
7+
# Capture the Chats tab — the default landing tab. Stable enough that the
8+
# onboarding-skip path lands here naturally without further taps.
9+
- launchApp:
10+
clearState: true
11+
clearKeychain: true
12+
- waitForAnimationToEnd:
13+
timeout: 5000
14+
- runFlow:
15+
when:
16+
visible: "Skip"
17+
commands:
18+
- tapOn: "Skip"
19+
- waitForAnimationToEnd:
20+
timeout: 3000
21+
- runFlow:
22+
when:
23+
visible: "Get Started"
24+
commands:
25+
- tapOn: "Get Started"
26+
- waitForAnimationToEnd:
27+
timeout: 3000
28+
# Default tab is Chats — no tap needed if onboarding lands there.
29+
- tapOn:
30+
text: "Chats"
31+
optional: true
32+
- waitForAnimationToEnd:
33+
timeout: 3000
34+
- takeScreenshot: "chats-list"

‎flows/contacts-list.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
appId: network.columba.Columba
2+
name: contacts-list
3+
tags:
4+
- smoke
5+
- screenshot
6+
---
7+
# Visit the Contacts tab and capture the list state. This is the most stable
8+
# UI surface that shows in every PR (no network needed beyond app boot — the
9+
# contacts list renders even with no cached announces).
10+
#
11+
# The screenshot lands at <cwd>/contacts-list.png; the orchestrator moves it
12+
# to ~/.claude-runner/screenshots/<pr>/<phase>/contacts-list.png.
13+
- launchApp:
14+
clearState: true
15+
clearKeychain: true
16+
- waitForAnimationToEnd:
17+
timeout: 5000
18+
# Onboarding may show on a fresh install; skip if "Skip" / "Get Started" is visible.
19+
- runFlow:
20+
when:
21+
visible: "Skip"
22+
commands:
23+
- tapOn: "Skip"
24+
- waitForAnimationToEnd:
25+
timeout: 3000
26+
- runFlow:
27+
when:
28+
visible: "Get Started"
29+
commands:
30+
- tapOn: "Get Started"
31+
- waitForAnimationToEnd:
32+
timeout: 3000
33+
- tapOn:
34+
text: "Contacts"
35+
optional: true
36+
- waitForAnimationToEnd:
37+
timeout: 3000
38+
- takeScreenshot: "contacts-list"

‎flows/map.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
appId: network.columba.Columba
2+
name: map
3+
tags:
4+
- smoke
5+
- screenshot
6+
---
7+
# Capture the Map tab. PR #59/#65 changes this view's style URL based on
8+
# system appearance. We screenshot it in the Sim's default light appearance —
9+
# Stage 2 will add a dark-mode capture column.
10+
- launchApp:
11+
clearState: true
12+
clearKeychain: true
13+
- waitForAnimationToEnd:
14+
timeout: 5000
15+
- runFlow:
16+
when:
17+
visible: "Skip"
18+
commands:
19+
- tapOn: "Skip"
20+
- waitForAnimationToEnd:
21+
timeout: 3000
22+
- runFlow:
23+
when:
24+
visible: "Get Started"
25+
commands:
26+
- tapOn: "Get Started"
27+
- waitForAnimationToEnd:
28+
timeout: 3000
29+
- tapOn:
30+
text: "Map"
31+
optional: true
32+
# Maps need a beat to load tile JSON + first-render
33+
- waitForAnimationToEnd:
34+
timeout: 8000
35+
- takeScreenshot: "map"

‎flows/settings.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
appId: network.columba.Columba
2+
name: settings
3+
tags:
4+
- smoke
5+
- screenshot
6+
---
7+
# Open the Settings tab and capture the top of the panel — the most static UI
8+
# surface in the app, ideal for catching unintended typography/theme drift.
9+
- launchApp:
10+
clearState: true
11+
clearKeychain: true
12+
- waitForAnimationToEnd:
13+
timeout: 5000
14+
- runFlow:
15+
when:
16+
visible: "Skip"
17+
commands:
18+
- tapOn: "Skip"
19+
- waitForAnimationToEnd:
20+
timeout: 3000
21+
- runFlow:
22+
when:
23+
visible: "Get Started"
24+
commands:
25+
- tapOn: "Get Started"
26+
- waitForAnimationToEnd:
27+
timeout: 3000
28+
- tapOn:
29+
text: "Settings"
30+
optional: true
31+
- waitForAnimationToEnd:
32+
timeout: 3000
33+
- takeScreenshot: "settings"

0 commit comments

Comments
 (0)