Identify the target surface:
- Mobile app: find Android package name or iOS bundle ID.
- Web app: find the URL to open.
- Expo Go: plan to use openLink with the exp:// development URL instead of launchApp with the app's final ID.
Check environment readiness:
- Verify Java 17+, maestro --version, and either Android tooling, Xcode Simulator tooling, or a web target.
- If Maestro is missing, install it with the current official method. See references/running-and-ci.md.
Inspect the app's user journeys:
- Prefer flows that represent user intent: smoke launch, signup, login, 2FA/OTP verification, onboarding, checkout, settings, notifications, permissions, and critical regressions.
- Add or recommend stable accessibility IDs only where visible text is too brittle or not present.
- For email/SMS OTP flows, use references/otp-flows.md and the qa-email-sms-otp skill for Mailpit, SMS Gateway, adb, and polling scripts.
Create a .maestro/ suite:
- Put complete tests in .maestro/flows/.
- Put reusable pieces in .maestro/subflows/.
- Use env vars for app IDs, credentials, URLs, and platform differences.
- Add config.yaml once the suite needs nested discovery, global tags, output dirs, or execution order.
Write flows that are resilient by design:
- Use visible text first when it expresses the UX contract.
- Use id or accessibility identifiers for icons, repeated controls, localization, or unstable copy.
- Use assertions as waits before reaching for explicit wait commands.
- Assert the intended product outcome, not just that taps completed.
- Use scrollUntilVisible, runFlow, when, and repeat instead of brittle coordinate-heavy scripts.
- Use JavaScript only for dynamic data, API setup, custom state, or logic that YAML cannot express cleanly.
Run locally and debug:
- Run maestro test .maestro/ for the suite or maestro test path/to/flow.yaml for one flow.
- Use maestro test -c .maestro/ while iterating.
- Use maestro studio or maestro hierarchy to inspect selectors when a command cannot find an element.
Prepare CI or cloud execution:
- Pin credentials and app IDs via environment variables or CLI -e flags.
- Use tags for smoke/regression/locale/platform subsets.
- Use sharding or Maestro Cloud when local sequential execution becomes slow.

Minimal Flow Skeleton

Use this as the starting point for app flows:

appId: ${APP_ID}
name: Smoke - launch and login
tags:
  - smoke
env:
  USERNAME: ${USERNAME || "test@example.com"}
---
- launchApp:
    clearState: true
- assertVisible: "Login"
- tapOn:
    id: "username_input"
- inputText: ${USERNAME}
- tapOn:
    id: "login_button"
- assertVisible: "Welcome"

For web:

url: ${BASE_URL}
name: Web smoke
tags:
  - smoke
---
- launchApp
- assertVisible: "Home"
- tapOn: "Sign in"

Defect Retest Guardrails

Use these guardrails when testing known defects, flaky auth flows, OTP flows, toast-heavy apps, or user-reported regressions:

Test one defect row per flow where practical: one setup, one action, one expected outcome, one evidence set.
Treat a Maestro flow as incomplete until it asserts the defect-specific postcondition, such as Dashboard visible, OTP screen visible, account chooser visible, saved data persisted after leaving and returning, or a specific error/toast visible.
Capture transient feedback immediately after submit actions. For toast-heavy apps, take evidence at roughly immediate, 1s, 3-4s, and 8-10s, and also collect focused logcat around the action.
Reset logcat before each defect action, then save a short post-action logcat so parser errors, network failures, and backend messages are attributable to that test.
Preserve authenticated state until all authenticated-only defects are tested. Run logout, account-clearing, password-change, external-browser, and destructive state tests late unless they are the target scenario.
Use launchApp: { clearState: true } only for fresh onboarding/auth tests. Avoid clearing state for session restore, minimize/reopen, notification read state, referral routing, saved-data persistence, or profile update scenarios.
Never treat placeholder text, example values, or previously saved account data as entered user data. Focus the field, clear it explicitly when needed, type a fresh marker/value, and use screenshot or hierarchy evidence to verify the entered state.
For persistence defects, do not stop after seeing data on the same screen. Save or perform the closest available commit action, leave the screen, return through the real navigation path, and verify the fresh marker persisted or was rejected.
Prefer selectors over coordinates. If coordinates are necessary, capture a screenshot/hierarchy near the tap and document why a selector was not reliable.
For flaky JSON/network/auth errors, retry the same action twice more with the same setup before classifying the issue. Keep each attempt's screenshot and logcat separate.
For real carrier/backend OTP flows, do not claim emulator SMS simulation proves end-to-end verification. Use backend test numbers, Mailpit/SMS Gateway paths, or a physical SIM; otherwise mark the OTP validation blocked or partially verified.

Field-Tested Retest Lessons

Apply these lessons when another agent needs to rerun a defect log or verify fixes:

Treat every row as a fresh outcome-based retest. A tap completing, a screen opening, or old bad data being visible is not enough evidence.
Name fresh test data so it can be distinguished from old account state, such as RERUNBAD..., timestamps, or scenario-specific markers.
Preserve session state while testing authenticated surfaces. Run force-stop, logout, external link/deep-link, account-clearing, and auth recovery flows after logged-in feature defects.
Set up device prerequisites before testing dependent features: permissions, location services, emulator geo, locale, network, push state, and test account data.
For location-dependent lists, compare categories after prerequisites are enabled and wait long enough for lazy loading. A loading state may hide the real wrong-result defect.
For phone, OTP, and auth normalization tests, explicitly type the exact value under test and capture the entered field before submit. Test local/national and normalized formats only after proving which value was entered.
When auth or network failures appear, separate app failures from emulator/environment failures. Check raw IP reachability, DNS, focused logcat, and repeat attempts before classifying.
Do not mark OTP delivery verified from emulator-injected SMS unless the app's backend path is actually exercised. Without a backend test number, SMS gateway, Mailpit, or physical SIM, mark real OTP delivery blocked or partial.
Isolate AI/chat tests when possible. A stuck generation, retry state, selected tool chip, or unfinished stream can contaminate later chat defects.
Empty states are blockers, not passes. If notifications, history, inboxes, or push-triggered screens have no data, log the missing precondition instead of closing the defect.
Push notification defects need a backend or controlled trigger. Opening the notification shade without a push event only proves the trigger was unavailable.
Keep evidence per defect: screenshots at meaningful waits, hierarchy when selectors/state are ambiguous, and a short logcat captured immediately around the action.

Outcome-focused example:

appId: ${APP_ID}
name: Auth - login reaches dashboard
---
- launchApp
- assertVisible: "Login"
- tapOn:
    id: "phone_input"
- inputText: ${PHONE}
- tapOn:
    id: "password_input"
- inputText: ${PASSWORD}
- tapOn: "Login"
- assertVisible: "Dashboard"
- takeScreenshot: "auth-login-dashboard"

Negative/toast-heavy example:

appId: ${APP_ID}
name: Forgot password - invalid phone fails closed
---
- launchApp
- assertVisible: "Forgot Password"
- tapOn:
    id: "phone_input"
- inputText: ${PHONE}
- tapOn: "Request OTP"
- takeScreenshot: "forgot-submit-immediate"
- waitForAnimationToEnd:
    timeout: 1000
- takeScreenshot: "forgot-submit-after-1s"
- assertVisible:
    text: "Profile is not registered|Network request failed|Phone verification"

Reference Map

Read only the reference file needed for the current task:

references/flow-building.md: selectors, commands, waits, nested flows, conditions, loops, parameters, hooks, and locale patterns.
references/platforms.md: React Native, Expo, Android native, Jetpack Compose, iOS, UIKit, SwiftUI, and Web selector guidance.
references/app-integration.md: launch arguments for detecting Maestro, web window.maestro, permissions, and app-side test-mode behavior.
references/otp-flows.md: integrating Maestro with the qa-email-sms-otp skill for Mailpit email OTP and Android SMS OTP flows.
references/javascript.md: inline expressions, evalScript, runScript, output, logging, faker data, and HTTP requests.
references/workspace-management.md: config.yaml, repository architecture, test discovery, tags, sequential execution, reports, artifacts, recordings, and analysis.
references/locales.md: device locale rules, supported locale examples, and locale/tag run patterns.
references/running-and-ci.md: install checks, device startup, targeting, Studio, CLI, sharding, locale startup, and cloud/CI handoff.

Output Standard

When implementing Maestro coverage in a repo, finish with:

Files created or changed, using absolute paths.
The exact command used to run the flow or suite.
Pass/fail result and the first failing selector or assertion if any.
Any required app-side accessibility ID changes.
Any app-side Maestro detection or permission changes.
Any assumptions about app IDs, device state, credentials, or test data.

When only drafting flows without running them, say so explicitly and include the command the user should run.

maestro-ui-testing

Maestro UI Testing

Default Workflow