Maestro Mobile Testing
This skill makes an AI agent write Maestro flows - declarative YAML files that drive iOS and Android apps black-box style with built-in waiting, no test harness compiled into the app, and no WebDriver session management. Trigger it when a repository contains a .maestro/ directory or *.yaml flows with appId: headers, or when the user wants fast, low-maintenance smoke tests for a native, React Native, or Flutter app without the weight of Appium.
Core Principles
- Maestro waits by default; do not teach it to sleep. Every
tapOn and assertVisible polls until the element appears or a timeout expires. Reach for extendedWaitUntil for slow screens; never add fixed delays as a first resort.
- One flow per user-visible behavior. A flow named
checkout-with-saved-card.yaml that does exactly that is debuggable. A 200-line regression.yaml is not. Compose bigger journeys from subflows with runFlow.
- Select by accessibility id first, visible text second.
tapOn: id: "submit-button" survives copy changes and localization; text selectors are acceptable for stable, single-language labels only.
- Start from a clean, deterministic state.
launchApp with clearState: true resets the app between flows; tests that inherit the previous flow's logged-in session fail in random orders.
- Parameterize with env, not copies. Credentials and hosts go in
env: blocks or -e KEY=value CLI arguments so the same flow runs against dev, staging, and CI builds.
- Treat flows as code. They live in the repo next to the app, run on every PR via emulator CI, and produce JUnit XML that the pipeline understands.
Setup
# Install the Maestro CLI
curl -fsSL "https://get.maestro.mobile.dev" | bash
export PATH="$PATH:$HOME/.maestro/bin"
maestro --version
# Run one flow against the booted simulator/emulator
maestro test .maestro/login.yaml
# Run the whole suite with JUnit output for CI
maestro test .maestro/ --format junit --output maestro-report.xml
# Interactive selector explorer while authoring
maestro studio
Patterns
1. A complete login flow
# .maestro/login.yaml
appId: com.example.shop
env:
EMAIL: qa@example.com
PASSWORD: Str0ngPass!
---
- launchApp:
clearState: true
- tapOn: 'Log in'
- tapOn:
id: 'email-input'
- inputText: ${EMAIL}
- tapOn:
id: 'password-input'
- inputText: ${PASSWORD}
- hideKeyboard
- tapOn:
id: 'login-submit'
- assertVisible: 'Welcome back'
- assertNotVisible: 'Invalid email or password'
- takeScreenshot: logged-in-home
2. Subflows with runFlow: compose journeys, handle one-off dialogs
# .maestro/subflows/login.yaml -- reusable building block
appId: com.example.shop
---
- launchApp:
clearState: true
- tapOn: 'Log in'
- tapOn:
id: 'email-input'
- inputText: ${EMAIL}
- tapOn:
id: 'password-input'
- inputText: ${PASSWORD}
- tapOn:
id: 'login-submit'
- assertVisible:
id: 'home-screen'
# .maestro/checkout.yaml -- the journey composes the subflow
appId: com.example.shop
env:
EMAIL: qa@example.com
PASSWORD: Str0ngPass!
---
- runFlow: subflows/login.yaml
# Dismiss the push-permission prompt only if it appears
- runFlow:
when:
visible: 'Allow notifications?'
commands:
- tapOn: 'Allow'
- tapOn: 'Deals'
- scrollUntilVisible:
element:
text: 'Wireless Headphones'
direction: DOWN
timeout: 20000
- tapOn: 'Wireless Headphones'
- tapOn:
id: 'add-to-cart'
- tapOn:
id: 'cart-icon'
- assertVisible: 'Wireless Headphones'
- assertVisible:
text: 'Checkout'
enabled: true
3. Waiting, repeats, and assertions with conditions
# .maestro/order-status.yaml
appId: com.example.shop
---
- launchApp
- tapOn:
id: 'tab-orders'
# Wait up to 15s for async content instead of a blind sleep
- extendedWaitUntil:
visible:
id: 'orders-list'
timeout: 15000
# Pull-to-refresh until the order flips to Shipped, max 5 tries
- repeat:
while:
notVisible: 'Shipped'
times: 5
commands:
- swipe:
direction: DOWN
duration: 400
- assertVisible:
text: 'Shipped'
- copyTextFrom:
id: 'order-number'
- assertTrue: ${maestro.copiedText != ''}
4. CI: Android emulator on GitHub Actions
# .github/workflows/maestro-android.yml
name: maestro-android
on: [pull_request]
jobs:
flows:
runs-on: ubuntu-latest
timeout-minutes: 40
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 17
- name: Build debug APK
run: ./gradlew assembleDebug
- name: Install Maestro
run: |
curl -fsSL "https://get.maestro.mobile.dev" | bash
echo "$HOME/.maestro/bin" >> "$GITHUB_PATH"
- name: Run flows on emulator
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 34
arch: x86_64
profile: pixel_7
script: |
adb install app/build/outputs/apk/debug/app-debug.apk
maestro test .maestro/ --format junit --output maestro-report.xml \
-e EMAIL=ci-bot@example.com -e PASSWORD="${{ secrets.TEST_USER_PASSWORD }}"
- name: Publish report
if: always()
uses: actions/upload-artifact@v4
with:
name: maestro-report
path: |
maestro-report.xml
~/.maestro/tests
For hosted device execution, the same suite uploads unchanged: maestro cloud --api-key "$MAESTRO_CLOUD_API_KEY" app-debug.apk .maestro/ runs every flow on cloud devices and returns a pass/fail exit code CI can gate on.
Best Practices
- Use
maestro studio to discover ids and text before writing selectors by hand; it shows exactly what the accessibility tree exposes.
- Add accessibility identifiers in app code (
testID in React Native, accessibilityIdentifier on iOS, contentDescription/resource-id on Android) as part of feature work.
- Keep shared steps in
subflows/ and one top-level flow per journey; flows read top to bottom like a manual test script, keep them that readable.
- Tag smoke flows with YAML
tags: [smoke] and run maestro test --include-tags smoke on every PR, the full suite nightly.
- Capture
takeScreenshot at journey milestones; screenshots plus the JUnit report make CI failures diagnosable without a local repro.
- Pin the emulator API level and profile in CI; device drift is the top source of "passes locally" mysteries.
Anti-Patterns
- Sprinkling
- waitForAnimationToEnd and long extendedWaitUntil timeouts everywhere to paper over an app that never settles; fix the spinner, not the test.
- Selecting by index (
tapOn: point: 50%,30% or index-based taps) for elements that have ids; coordinate taps break on every screen size.
- One giant flow covering login, browse, checkout, refunds, and settings: a failure at step 40 costs a full re-run to debug.
- Hardcoding production credentials in flow files; use
env: plus CI secrets.
- Running flows only on a developer's personal device before release instead of an emulator on every PR.
- Re-implementing Appium-style page objects in JavaScript wrappers around Maestro; the YAML is the abstraction, keep logic out of it.
When to Trigger This Skill
- A repository contains a
.maestro/ directory, YAML files starting with appId:, or maestro commands in CI workflows.
- The user wants mobile UI smoke tests with minimal setup, or asks to test a React Native, Flutter, or native app without Appium infrastructure.
- An existing Appium suite is too slow or flaky for PR-level smoke coverage and the team wants a lighter black-box layer on top.
- Mobile onboarding, login, or checkout journeys need regression coverage that designers and QA can read and edit.
- Choose Maestro for declarative cross-platform flows; recommend Detox when the team needs gray-box React Native synchronization, or Appium when tests must script complex logic in a full programming language.
1---2name: maestro-mobile-testing3description: Black-box mobile UI testing with Maestro YAML flows - launchApp, tapOn, inputText, assertVisible, reusable runFlow subflows, environment parameters, JUnit reporting, and emulator-based CI pipelines.4version: 1.0.05author: thetestingacademy6license: MIT7tags: [maestro, mobile, e2e, ios, android, yaml, flows, ui-testing, flutter, react-native]8testingTypes: [mobile, e2e]9frameworks: [appium]10languages: [typescript]11domains: [mobile]12agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt, gemini-cli, amp]13metadata:14 source: https://skillmd.com/skills/pramoddutta/maestro-mobile-testing15---1617# Maestro Mobile Testing1819This skill makes an AI agent write Maestro flows - declarative YAML files that drive iOS and Android apps black-box style with built-in waiting, no test harness compiled into the app, and no WebDriver session management. Trigger it when a repository contains a `.maestro/` directory or `*.yaml` flows with `appId:` headers, or when the user wants fast, low-maintenance smoke tests for a native, React Native, or Flutter app without the weight of Appium.2021## Core Principles22231. **Maestro waits by default; do not teach it to sleep.** Every `tapOn` and `assertVisible` polls until the element appears or a timeout expires. Reach for `extendedWaitUntil` for slow screens; never add fixed delays as a first resort.242. **One flow per user-visible behavior.** A flow named `checkout-with-saved-card.yaml` that does exactly that is debuggable. A 200-line `regression.yaml` is not. Compose bigger journeys from subflows with `runFlow`.253. **Select by accessibility id first, visible text second.** `tapOn: id: "submit-button"` survives copy changes and localization; text selectors are acceptable for stable, single-language labels only.264. **Start from a clean, deterministic state.** `launchApp` with `clearState: true` resets the app between flows; tests that inherit the previous flow's logged-in session fail in random orders.275. **Parameterize with env, not copies.** Credentials and hosts go in `env:` blocks or `-e KEY=value` CLI arguments so the same flow runs against dev, staging, and CI builds.286. **Treat flows as code.** They live in the repo next to the app, run on every PR via emulator CI, and produce JUnit XML that the pipeline understands.2930## Setup3132```bash33# Install the Maestro CLI34curl -fsSL "https://get.maestro.mobile.dev" | bash35export PATH="$PATH:$HOME/.maestro/bin"36maestro --version3738# Run one flow against the booted simulator/emulator39maestro test .maestro/login.yaml4041# Run the whole suite with JUnit output for CI42maestro test .maestro/ --format junit --output maestro-report.xml4344# Interactive selector explorer while authoring45maestro studio46```4748## Patterns4950### 1. A complete login flow5152```yaml53# .maestro/login.yaml54appId: com.example.shop55env:56 EMAIL: qa@example.com57 PASSWORD: Str0ngPass!58---59- launchApp:60 clearState: true61- tapOn: 'Log in'62- tapOn:63 id: 'email-input'64- inputText: ${EMAIL}65- tapOn:66 id: 'password-input'67- inputText: ${PASSWORD}68- hideKeyboard69- tapOn:70 id: 'login-submit'71- assertVisible: 'Welcome back'72- assertNotVisible: 'Invalid email or password'73- takeScreenshot: logged-in-home74```7576### 2. Subflows with runFlow: compose journeys, handle one-off dialogs7778```yaml79# .maestro/subflows/login.yaml -- reusable building block80appId: com.example.shop81---82- launchApp:83 clearState: true84- tapOn: 'Log in'85- tapOn:86 id: 'email-input'87- inputText: ${EMAIL}88- tapOn:89 id: 'password-input'90- inputText: ${PASSWORD}91- tapOn:92 id: 'login-submit'93- assertVisible:94 id: 'home-screen'95```9697```yaml98# .maestro/checkout.yaml -- the journey composes the subflow99appId: com.example.shop100env:101 EMAIL: qa@example.com102 PASSWORD: Str0ngPass!103---104- runFlow: subflows/login.yaml105106# Dismiss the push-permission prompt only if it appears107- runFlow:108 when:109 visible: 'Allow notifications?'110 commands:111 - tapOn: 'Allow'112113- tapOn: 'Deals'114- scrollUntilVisible:115 element:116 text: 'Wireless Headphones'117 direction: DOWN118 timeout: 20000119- tapOn: 'Wireless Headphones'120- tapOn:121 id: 'add-to-cart'122- tapOn:123 id: 'cart-icon'124- assertVisible: 'Wireless Headphones'125- assertVisible:126 text: 'Checkout'127 enabled: true128```129130### 3. Waiting, repeats, and assertions with conditions131132```yaml133# .maestro/order-status.yaml134appId: com.example.shop135---136- launchApp137- tapOn:138 id: 'tab-orders'139140# Wait up to 15s for async content instead of a blind sleep141- extendedWaitUntil:142 visible:143 id: 'orders-list'144 timeout: 15000145146# Pull-to-refresh until the order flips to Shipped, max 5 tries147- repeat:148 while:149 notVisible: 'Shipped'150 times: 5151 commands:152 - swipe:153 direction: DOWN154 duration: 400155156- assertVisible:157 text: 'Shipped'158- copyTextFrom:159 id: 'order-number'160- assertTrue: ${maestro.copiedText != ''}161```162163### 4. CI: Android emulator on GitHub Actions164165```yaml166# .github/workflows/maestro-android.yml167name: maestro-android168on: [pull_request]169170jobs:171 flows:172 runs-on: ubuntu-latest173 timeout-minutes: 40174 steps:175 - uses: actions/checkout@v4176 - uses: actions/setup-java@v4177 with:178 distribution: temurin179 java-version: 17180 - name: Build debug APK181 run: ./gradlew assembleDebug182 - name: Install Maestro183 run: |184 curl -fsSL "https://get.maestro.mobile.dev" | bash185 echo "$HOME/.maestro/bin" >> "$GITHUB_PATH"186 - name: Run flows on emulator187 uses: reactivecircus/android-emulator-runner@v2188 with:189 api-level: 34190 arch: x86_64191 profile: pixel_7192 script: |193 adb install app/build/outputs/apk/debug/app-debug.apk194 maestro test .maestro/ --format junit --output maestro-report.xml \195 -e EMAIL=ci-bot@example.com -e PASSWORD="${{ secrets.TEST_USER_PASSWORD }}"196 - name: Publish report197 if: always()198 uses: actions/upload-artifact@v4199 with:200 name: maestro-report201 path: |202 maestro-report.xml203 ~/.maestro/tests204```205206For hosted device execution, the same suite uploads unchanged: `maestro cloud --api-key "$MAESTRO_CLOUD_API_KEY" app-debug.apk .maestro/` runs every flow on cloud devices and returns a pass/fail exit code CI can gate on.207208## Best Practices209210- Use `maestro studio` to discover ids and text before writing selectors by hand; it shows exactly what the accessibility tree exposes.211- Add accessibility identifiers in app code (`testID` in React Native, `accessibilityIdentifier` on iOS, `contentDescription`/`resource-id` on Android) as part of feature work.212- Keep shared steps in `subflows/` and one top-level flow per journey; flows read top to bottom like a manual test script, keep them that readable.213- Tag smoke flows with YAML `tags: [smoke]` and run `maestro test --include-tags smoke` on every PR, the full suite nightly.214- Capture `takeScreenshot` at journey milestones; screenshots plus the JUnit report make CI failures diagnosable without a local repro.215- Pin the emulator API level and profile in CI; device drift is the top source of "passes locally" mysteries.216217## Anti-Patterns218219- Sprinkling `- waitForAnimationToEnd` and long `extendedWaitUntil` timeouts everywhere to paper over an app that never settles; fix the spinner, not the test.220- Selecting by index (`tapOn: point: 50%,30%` or index-based taps) for elements that have ids; coordinate taps break on every screen size.221- One giant flow covering login, browse, checkout, refunds, and settings: a failure at step 40 costs a full re-run to debug.222- Hardcoding production credentials in flow files; use `env:` plus CI secrets.223- Running flows only on a developer's personal device before release instead of an emulator on every PR.224- Re-implementing Appium-style page objects in JavaScript wrappers around Maestro; the YAML is the abstraction, keep logic out of it.225226## When to Trigger This Skill227228- A repository contains a `.maestro/` directory, YAML files starting with `appId:`, or `maestro` commands in CI workflows.229- The user wants mobile UI smoke tests with minimal setup, or asks to test a React Native, Flutter, or native app without Appium infrastructure.230- An existing Appium suite is too slow or flaky for PR-level smoke coverage and the team wants a lighter black-box layer on top.231- Mobile onboarding, login, or checkout journeys need regression coverage that designers and QA can read and edit.232- Choose Maestro for declarative cross-platform flows; recommend Detox when the team needs gray-box React Native synchronization, or Appium when tests must script complex logic in a full programming language.