Mobile flows maestro

Maestro Mobile Flows

Use Maestro's live surface as the source of truth. CLI flags come from the installed maestro --help and subcommand help. Flow YAML and JavaScript come from current Maestro documentation. When MCP is connected, inspect its actual tool inventory instead of naming remembered tools.

Choose the interface

Use MCP or Studio for interactive hierarchy inspection, authoring, and feedback. Use the CLI for scriptable execution, exit codes, reports, artifacts, and CI. Confirm that the installed version supports maestro mcp, then register it through the active host's MCP mechanism.

Hierarchy and text are cheap; repeated image payloads are not. When a host retains images in the long-lived conversation, keep screenshots in a bounded visual task and return only its text finding.

Select a device deliberately

Inspect booted iOS simulators and connected Android devices. Ignore offline/unauthorized Android entries. When more than one compatible device is available, target one explicitly with the installed CLI's syntax--currently maestro --device <serial-or-udid> test <flow>. Do not silently choose a platform, emulator, or physical device.

Prefer observable selectors

Prefer visible text, then accessible identifiers or descriptions, then coordinates. Maestro text matchers are regular expressions, so escape metacharacters and disambiguate labels that can match multiple elements. An ID works only when the app exposes it to the platform accessibility hierarchy; inspect the live hierarchy rather than assuming a SwiftUI identifier, Android resource ID, Compose tag, React Native testID, or Flutter key is visible.

State and system surfaces

Configure supported iOS and Android permissions through launchApp.permissions or setPermissions; use platform tools only for special cases current Maestro cannot represent.

iOS app-state clearing does not necessarily clear Keychain. For independent authentication flows, use the current clearKeychain command or launchApp.clearKeychain and remember that it is iOS-only.

External authentication and other system-owned surfaces can be unstable in unattended CI. Prefer a test-build-only bypass or seeded identity when authentication itself is not under test. Keep a controlled integration test when the real handoff is the requirement.

Biometric simulation changes across Xcode and device tooling. Check current Maestro docs and xcrun simctl help before suggesting a command; do not preserve old simctl syntax as doctrine.

JavaScript is a separate file

runScript executes a JavaScript file relative to the flow. Keep scripts in the uploaded flow directory for cloud execution.

Maestro JavaScript is not Node: do not assume require, ES modules, filesystem access, or browser fetch. Use the HTTP and output interfaces documented by the installed/current Maestro version.

- runScript: scripts/health.js
- assertTrue: ${output.healthy}

Wait for product behavior

Maestro assertions already retry for a default window. Use extendedWaitUntil when a legitimate outcome exceeds that window, with a timeout tied to expected product behavior rather than a blanket larger value. A larger timeout proving successful establishes timing sensitivity, not its cause.

On failure, classify before editing: app defect, selector problem, timing race, test-state leak, or environment failure. Do not rewrite a flow merely to make the current run pass.

Keep independently meaningful journeys separate when that improves diagnosis or reuse. Combine steps that form one product outcome; do not split files to satisfy a universal one-journey rule.

Load references/maestro-gotchas.md for CI, platform state, system surfaces, and failure diagnosis.