Maestro Mobile Testing

Maestro Mobile E2E Testing

Overview

Maestro is a declarative YAML-based mobile E2E testing framework. It provides automatic waiting, built-in retry logic, and fast execution without boilerplate. It's more stable than Detox or Appium for React Native apps.

Key Features

• Declarative YAML — no imperative test code, just steps
• Automatic waiting — no manual sleep() or flaky waits
• Built-in retry — reduces test flakiness
• Fast execution — runs quickly without setup overhead
• Maestro Studio — interactive test builder (maestro studio)
• Sub-flows — reusable YAML sequences for DRY tests
• JavaScript scripting — GraalJS runtime for HTTP calls and data manipulation
• Maestro Cloud — real device testing in CI without local simulators

Quick Start

Install

curl -Ls "https://get.maestro.mobile.dev" | bash
brew install openjdk@17
export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home

Minimal test

appId: com.myapp
---
- launchApp
- tapOn:
    id: "my-button"
- assertVisible: "Expected Text"

Run

maestro test .maestro/smoke-test.yaml
maestro test --debug .maestro/smoke-test.yaml  # step through
maestro studio                                  # interactive builder

---

Core Patterns

1. Selector Strategy: testID vs Text

Choose your selector approach based on project context. Both are valid — the right choice depends on whether your app is localized and your team's testing philosophy.

# testID selector — stable across translations
- tapOn:
    id: "submit-button"

# Text selector — human-readable, self-documenting
- tapOn: "Submit"

When to prefer testIDs:

• App supports multiple languages or will be translated
• UI text is dynamic or frequently changes
• Multiple elements share the same visible text

When to prefer text selectors:

• Single-language app with stable copy
• Readability and self-documentation are a priority
• Testing user-visible behavior exactly as it appears

In React Native, add testID props when using ID-based selectors:

<TouchableOpacity testID="submit-button" onPress={handleSubmit}>
  <Text>{t('submit')}</Text>
</TouchableOpacity>

testID Naming Convention

When using ID-based selectors:

{component}-{action/type}[-{variant}]

Examples:
- auth-prompt-login-button
- product-card-{id}
- otp-input-0
- tab-home
- dashboard-loading

2. Auth Pre-Flight Pattern

Prevent race conditions where Maestro interacts with the UI before auth state resolves. Add a zero-size auth-loaded marker that only renders when auth loading completes:

// In your tab bar or root layout
{!isLoading && <View testID="auth-loaded" style={{ width: 0, height: 0 }} />}

Then in every test:

- launchApp

# Prevent XCTest crash on cold boot (iOS)
- swipe:
    direction: DOWN
    duration: 100

# Wait for auth state to resolve
- extendedWaitUntil:
    visible:
      id: "auth-loaded"
    timeout: 15000

# Now safe to interact
- tapOn:
    id: "tab-home"

3. Adaptive Tests (Handle Both Auth States)

Tests should work regardless of whether the user is authenticated:

# Auth flow — only runs if login prompt is visible
- runFlow:
    when:
      visible: "Sign In"
    file: flows/auth-flow.yaml

# Already authenticated — proceed directly
- runFlow:
    when:
      visible:
        id: "tab-home"
    file: flows/authenticated-action.yaml

4. Testing Optimistic Updates

Use short timeouts to verify UI changes happen before server response:

# Trigger mutation
- tapOn:
    id: "action-button"

# OPTIMISTIC: UI must change within 3s (not waiting for server)
- extendedWaitUntil:
    visible:
      id: "undo-button"
    timeout: 3000

# Verify derived UI state
- extendedWaitUntil:
    visible:
      id: "user-indicator"
    timeout: 5000

5. Dismissing Native Alerts

React Native Alert.alert() creates native dialogs that block the UI:

- tapOn:
    id: "action-button"

# Wait for expected state change first
- extendedWaitUntil:
    visible:
      id: "new-state-element"
    timeout: 5000

# Dismiss alert (optional in case it already closed)
- tapOn:
    text: "OK"
    optional: true

# Brief delay for alert animation
- swipe:
    direction: DOWN
    duration: 300

6. Sub-Flows for Reusability

Break repeated sequences into sub-flow files:

.maestro/
├── flows/
│   ├── auth-and-return.yaml
│   ├── complete-purchase.yaml
│   └── verify-result.yaml
├── smoke-test.yaml
└── feature-test.yaml

# In main test
- runFlow:
    file: flows/auth-and-return.yaml

7. Deep Links (Expo)

Use the Expo scheme from app.json, not the bundle ID:

# WRONG
- openLink: "com.myapp://profile/settings"

# CORRECT
- openLink: "myapp://profile/settings"

Deep links must be registered in your app's deep link handler. Unregistered routes silently fail.

8. Platform-Specific Logic

- runFlow:
    when:
      platform: ios
    file: flows/ios-specific.yaml

- runFlow:
    when:
      platform: android
    file: flows/android-specific.yaml

9. Environment Variables

appId: com.myapp
env:
  TEST_EMAIL: maestro-test@example.com
  API_BASE_URL: http://localhost:3000
---
- inputText: ${TEST_EMAIL}

10. Selector State Properties

Use enabled, selected, checked, and focused to target elements by their current state. This is useful for validating interactive element states before or after actions.

# Only tap the submit button if it's enabled
- tapOn:
    id: "submit-button"
    enabled: true

# Assert a checkbox is checked
- assertVisible:
    id: "terms-checkbox"
    checked: true

# Wait for an input to be focused
- extendedWaitUntil:
    visible:
      id: "email-input"
      focused: true
    timeout: 3000

11. Relative Position Selectors

Distinguish between similar elements by their spatial relationship to other elements. This is more idiomatic and resilient than index-based selection.

# BAD — fragile, breaks if order changes
- tapOn:
    text: "Add to Basket"
    index: 1

# GOOD — contextual, self-documenting
- tapOn:
    text: "Add to Basket"
    below:
      text: "Awesome Shoes"

Available relative selectors:

# Target element below another
- tapOn:
    text: "Buy Now"
    below: "Product Title"

# Target element that is a child of a parent
- tapOn:
    text: "Delete"
    childOf:
      id: "item-card-42"

# Target a parent that contains a specific child
- tapOn:
    containsChild: "Urgent"

# Target by multiple descendants
- tapOn:
    containsDescendants:
      - id: title_id
        text: "Specific Title"
      - "Another descendant text"

# Horizontal positioning
- tapOn:
    text: "Edit"
    rightOf: "Username"

---

Authentication Testing

Architecture

Testing OTP or magic-link authentication in E2E requires capturing emails programmatically. The general pattern:

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Maestro    │────▶│  Auth        │────▶│  Email Capture  │
│  Test       │     │  Provider    │     │  Service        │
└─────────────┘     └──────────────┘     └─────────────────┘
       │                                        │
       │         ┌──────────────────────────────┘
       │         ▼
       │   ┌─────────────┐
       └──▶│  REST API   │ ─── GET /api/v1/messages
           │  (email)    │ ─── Extract OTP code
           └─────────────┘

Common email capture services: Mailpit, MailHog, Ethereal.

OTP Fetch Script

Fetch OTP codes from your email capture service using Maestro's GraalJS runtime:

// CRITICAL: Maestro uses GraalJS — NO async/await, NO fetch()
var email = typeof EMAIL !== "undefined" ? EMAIL : "test@example.com";
var emailServiceUrl = typeof EMAIL_SERVICE_URL !== "undefined"
  ? EMAIL_SERVICE_URL : "http://localhost:8025";

var response = http.get(emailServiceUrl + "/api/v1/messages");
if (!response.ok) {
  throw new Error("Failed to fetch emails: " + response.status);
}

var data = json(response.body);
// Find the latest email and extract OTP code
var body = data.messages[0].Content.Body;
var match = body.match(/(\d{6})/);
output.OTP_CODE = match[1];

OTP Input Strategy

OTP components with auto-focus need individual digit entry. Tap each input before typing:

# Split OTP into digits via helper script
- runScript:
    file: scripts/split-otp.js
    env:
      OTP_CODE: ${output.OTP_CODE}

# Enter each digit by tapping its input
- tapOn:
    id: "otp-input-0"
- inputText: ${output.OTP_0}

- tapOn:
    id: "otp-input-1"
- inputText: ${output.OTP_1}
# ... repeat for all digits

For provider-specific implementations (Supabase + Mailpit, Firebase Auth, Auth0), create a project-level skill that extends this one.

---

GraalJS Script Rules

Maestro uses the GraalJS runtime. These constraints are non-negotiable:

// Script template
var response = http.get("http://localhost:8025/api/endpoint");
if (!response.ok) {
  throw new Error("Request failed: " + response.status);
}
var data = json(response.body);
output.RESULT = data.value;

---

Critical Gotchas

clearState Does NOT Clear iOS Keychain

clearState: true clears the app sandbox (UserDefaults, files, caches) but does NOT clear the iOS Keychain. Auth tokens stored via expo-secure-store (or any Keychain-based storage) persist across clearState resets and even app reinstalls.

# WRONG — user may still be authenticated
- launchApp:
    clearState: true
- assertVisible: "Welcome"  # Fails if Keychain has tokens

# CORRECT — wait for auth resolution, then adapt
- launchApp
- extendedWaitUntil:
    visible:
      id: "auth-loaded"
    timeout: 15000

Rules:

• Never rely on clearState to produce guest state on iOS
• For auth tests: skip clearState, use auth-loaded pre-flight
• For guest tests: use adaptive flows that handle both states
• Never assert guest-only UI after clearState

Note: On Android, clearState: true fully resets app data including credentials. This is an iOS-only gotcha.

XCTest kAXErrorInvalidUIElement Crash (iOS)

The XCTest driver may crash if Maestro interacts with the accessibility tree before the first render cycle completes on cold boot.

Fix: Add a no-op swipe immediately after launchApp:

- launchApp
- swipe:
    direction: DOWN
    duration: 100

API Server Dependency

Mobile apps calling backend APIs on localhost need either the full server or a mock server running. Without it, all API-dependent screens show loading spinners or empty states (queries fail silently).

Fix: Start a mock API server before running Maestro tests:

# Start mock server (serves canned responses on your API port)
npx tsx scripts/mock-api-server.ts &

# Then run tests
maestro test .maestro/my-test.yaml

Create a lightweight mock that returns canned JSON for each endpoint your app calls. This is faster and more deterministic than running your full backend.

Auth-Aware Tab Bars

Tab bars that show different tabs for guest vs authenticated users will cause selector failures:

Only assert tabs that exist in both states, or use adaptive when: conditions.

---

Test File Template

# {Feature} {Action} Test
#
# Tests: {what this validates}
# Prerequisites:
# - Simulator/emulator running with app installed
# - Backend or mock server running (if API-dependent)

appId: com.myapp
env:
  TEST_EMAIL: maestro-{feature}@example.com
  EMAIL_SERVICE_URL: http://localhost:8025
---
# ==========================================
# STEP 1: LAUNCH + AUTH PRE-FLIGHT
# ==========================================

- launchApp

- swipe:
    direction: DOWN
    duration: 100

- extendedWaitUntil:
    visible:
      id: "auth-loaded"
    timeout: 15000

- takeScreenshot: 01-initial-state

# ==========================================
# STEP 2: {ACTION}
# ==========================================

- tapOn:
    id: "target-element"

# ==========================================
# STEP 3: VERIFY
# ==========================================

- extendedWaitUntil:
    visible:
      id: "expected-result"
    timeout: 5000

- takeScreenshot: 02-final-state

---

Folder Structure

.maestro/
├── README.md                    # Quick reference + testID inventory
├── config.yaml                  # Shared configuration
├── flows/                       # Reusable sub-flows
│   ├── auth-and-return.yaml
│   ├── complete-action.yaml
│   └── verify-result.yaml
├── scripts/                     # GraalJS helpers
│   ├── fetch-otp.js
│   └── split-otp.js
├── smoke-test.yaml              # Guest navigation
├── auth-signin.yaml             # OTP sign-in flow
├── feature-screenshots.yaml     # Screenshot capture flows
└── feature-action.yaml          # Feature-specific tests

scripts/
├── mock-api-server.ts           # Lightweight mock for E2E
└── run-e2e.sh                   # Orchestration script

Naming Conventions

---

Infrastructure

Mock Server for API-Dependent Tests

Create a lightweight mock server that serves canned responses for your API layer. This is faster and more deterministic than running your full backend during E2E tests.

# Start mock server before running Maestro tests
npx tsx scripts/mock-api-server.ts &

Orchestration Script

Automate the full E2E setup with a shell script that: 1. Starts backend services (database, auth) 2. Seeds test data 3. Starts mock API server 4. Runs Maestro tests 5. Cleans up all services

bash scripts/run-e2e.sh

Seed Data

Tests that depend on specific data require seeded databases. Keep seed scripts alongside your test infrastructure and run them before each test suite.

---

Android-Specific Patterns

Emulator Setup

Android tests require an emulator or a USB-connected physical device. Maestro auto-detects connected devices.

# List available system images
sdkmanager --list | grep system-images

# Create emulator
avdmanager create avd -n maestro_test \
  -k "system-images;android-34;google_apis;arm64-v8a"

# Start emulator
emulator -avd maestro_test

iOS vs Android Differences

ADB Debugging

adb devices                                    # List connected devices
adb shell am start -n com.myapp/.MainActivity  # Launch app
adb logcat | grep Maestro                      # Filter Maestro logs
adb shell input keyevent 82                    # Unlock screen

Android Permission Handling

Android permissions appear as system dialogs. Dismiss with optional taps:

- tapOn:
    text: "Allow"
    optional: true

- tapOn:
    text: "While using the app"
    optional: true

---

CI/CD Integration

GitHub Actions with Maestro Cloud

Maestro Cloud provides real devices in CI without local simulators. Use the official action:

name: Mobile E2E Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  maestro-e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Build Android APK
      - uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Build Android APK
        run: |
          cd apps/mobile
          npx expo prebuild --platform android --no-install
          cd android && ./gradlew assembleRelease

      - name: Run Maestro Cloud Tests
        id: maestro
        uses: mobile-dev-inc/action-maestro-cloud@v2
        with:
          api-key: ${{ secrets.MAESTRO_API_KEY }}
          app-file: apps/mobile/android/app/build/outputs/apk/release/app-release.apk
          workspace: .maestro
          include-tags: ci

      # Access results
      # ${{ steps.maestro.outputs.MAESTRO_CLOUD_CONSOLE_URL }}
      # ${{ steps.maestro.outputs.MAESTRO_CLOUD_UPLOAD_STATUS }}
      # ${{ steps.maestro.outputs.MAESTRO_CLOUD_FLOW_RESULTS }}

Tag-Based Flow Filtering

Use tags to control which tests run in CI vs locally:

# In your flow file header
appId: com.myapp
tags:
  - ci
  - smoke
---
- launchApp
# ... test steps

# Run only CI-tagged flows locally
maestro test --include-tags ci .maestro/

# Exclude work-in-progress flows
maestro test --exclude-tags wip .maestro/

Local CI with Docker (Android Only)

FROM openjdk:17-slim

RUN curl -Ls "https://get.maestro.mobile.dev" | bash
ENV PATH="/root/.maestro/bin:${PATH}"

COPY .maestro/ /app/.maestro/
WORKDIR /app

CMD ["maestro", "test", ".maestro/"]

Note: iOS tests cannot run in Docker (requires macOS). Use Maestro Cloud for iOS in CI.

---

Maestro Cloud

Maestro Cloud runs tests on real devices without local simulator setup.

Setup

1. Create account at cloud.maestro.dev 2. Generate API key from dashboard 3. Store as MAESTRO_API_KEY secret in your CI provider

Running from CLI

# Upload and run on Maestro Cloud
maestro cloud --api-key $MAESTRO_API_KEY \
  --app-file ./app-release.apk \
  .maestro/

# With tag filtering
maestro cloud --api-key $MAESTRO_API_KEY \
  --app-file ./app-release.apk \
  --include-tags smoke \
  .maestro/

Key Points

• iOS testing: Supported on Maestro Cloud (not on local physical devices)
• Android testing: Both local physical devices and Maestro Cloud
• Results: Dashboard with video recordings, logs, and screenshots
• CI outputs: MAESTRO_CLOUD_CONSOLE_URL, MAESTRO_CLOUD_FLOW_RESULTS

---

Maestro MCP Server

The Maestro MCP server exposes Maestro's full command set as Model Context Protocol tools, letting AI agents execute tests and interact with devices directly — not just write YAML.

How It Complements This Skill

Use both together: this skill ensures the AI writes correct tests; the MCP lets it run them immediately, see failures, and iterate.

Setup

The MCP ships with the Maestro CLI — no extra install needed:

# Verify it's available
maestro mcp

Claude Code — add to project .mcp.json or global settings:

{
  "mcpServers": {
    "maestro": {
      "command": "maestro",
      "args": ["mcp"]
    }
  }
}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "maestro": {
      "command": "maestro",
      "args": ["mcp"]
    }
  }
}

Also supported on Cursor, Windsurf, VS Code, and JetBrains IDEs. See the Maestro MCP docs for IDE-specific setup.

Key Capabilities

The MCP server exposes 47 tools organized by category:

Write-Run-Fix Loop

With both this skill and the MCP active, the AI can:

1. Write a test YAML using patterns from this skill 2. Run it via MCP's runFlow / launchApp + interaction tools 3. See failures via screenshots and assertions 4. Fix the YAML and re-run — all in one conversation

---

Debugging

maestro test --debug .maestro/test.yaml   # Step through interactively
maestro record .maestro/test.yaml          # Record as video
maestro studio                             # Interactive UI builder
maestro hierarchy                          # View element tree

Screenshots saved to ~/.maestro/tests/{timestamp}/.

---

Checklist for New Tests

[ ] Unique test email (maestro-{feature}@example.com)
[ ] Selector strategy chosen (testID for i18n apps, text for single-language — see Pattern 1)
[ ] Selectors use state properties where relevant (enabled, checked — see Pattern 10)
[ ] Similar elements distinguished with relative selectors, not index (see Pattern 11)
[ ] Auth pre-flight pattern used (auth-loaded)
[ ] Post-launch swipe added (iOS crash prevention)
[ ] Both auth states handled (adaptive flows)
[ ] Native alerts dismissed after mutations
[ ] Short timeouts for optimistic updates (3-5s)
[ ] Sub-flows created for reusable sequences
[ ] Descriptive screenshots at key points
[ ] Header comment with prerequisites
[ ] Added to README.md test table
[ ] Mock API server started if backend-dependent
[ ] Tags added for CI filtering (ci, smoke, wip)

---

Common Errors

---

Resources

• Maestro Documentation
• Maestro Selectors Reference
• Maestro Cloud
• Maestro MCP Server
• Maestro GitHub
• GraalJS HTTP Requests
• Conditions & Adaptive Flows
• GitHub Actions Integration
• BrowserStack: Maestro Testing Guide
• DEV.to: Tips & Tricks for Maestro + React Native