/mobile-testing-maestro

name: mobile-testing-maestro
description: Maestro mobile E2E testing - YAML flows, selectors, flow control, environment variables, JavaScript expressions, device interactions, Maestro Studio, Maestro Cloud CI, tags, test suites

Maestro Mobile UI Testing Patterns

> **Quick Guide:** Write E2E tests as declarative YAML flows. Use `id` selectors for stable element targeting (not text that changes with localization). Use `runFlow` to compose reusable subflows (login, setup). Use `waitForAnimationToEnd` before assertions on animated screens. Use `onFlowStart`/`onFlowComplete` hooks for setup/teardown. Maestro auto-retries assertions for up to 7 seconds before failing. Current stable: CLI 2.4.0.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use `id` selectors (accessibility identifiers) as primary selectors - text selectors break with localization or copy changes)**

**(You MUST use `runFlow` for reusable sequences (login, onboarding) - NEVER duplicate steps across flow files)**

**(You MUST use `waitForAnimationToEnd` before assertions on screens with animations or transitions - assertions on animated elements are flaky)**

**(You MUST pair every `startRecording` with a `stopRecording` - unpaired commands produce corrupted or missing video files)**

**(You MUST use environment variables or `env` blocks for credentials and environment-specific values - NEVER hardcode secrets in YAML flows)**

</critical_requirements>

---

**Auto-detection:** Maestro, maestro, .maestro, maestro test, maestro cloud, maestro studio, launchApp, tapOn, assertVisible, assertNotVisible, inputText, scrollUntilVisible, runFlow, evalScript, runScript, swipe, hideKeyboard, waitForAnimationToEnd, onFlowStart, onFlowComplete, maestro.yaml, config.yaml tags

**When to use:**

• Writing E2E UI tests for iOS and Android mobile apps
• Automating user workflows (login, checkout, onboarding) with YAML flows
• Testing cross-platform behavior from a single flow file
• Running mobile tests in CI with Maestro Cloud
• Recording test execution for debugging or documentation
• Testing deep links, location, permissions, and device interactions

**When NOT to use:**

• Unit testing business logic (use your unit test framework)
• API-only testing without UI (use direct HTTP tests)
• Testing web-only applications without mobile component
• Performance profiling or load testing (Maestro is for functional UI flows)

**Key patterns covered:**

• Flow structure with appId, YAML commands, and selectors
• Selector strategies: id (preferred), text, point, relational, state
• Flow control: runFlow, repeat, retry, conditions (when), hooks
• Environment variables and parameterized flows
• JavaScript expressions: inline `${}`, evalScript, runScript, output object
• Device interactions: swipe, scroll, setLocation, openLink, permissions
• Workspace configuration: tags, test discovery, execution order
• Maestro Studio for visual flow creation and element inspection
• Maestro Cloud for CI integration with GitHub Actions

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Flow structure, selectors, assertions, input, navigation
• [examples/flow-control.md](examples/flow-control.md) - runFlow, repeat, retry, conditions, hooks, JavaScript
• [examples/device-interactions.md](examples/device-interactions.md) - Swipe, scroll, location, links, permissions, recording
• [reference.md](reference.md) - Command reference, CLI commands, workspace config, decision frameworks

---

<philosophy>

Philosophy

Maestro takes a fundamentally different approach from code-based testing frameworks: **tests are declarative YAML, not imperative code**. This makes flows readable by anyone on the team, not just developers. The framework handles the hard parts of mobile testing automatically -- waiting for elements, retrying taps, tolerating animation delays -- so flows focus on _what_ to test, not _how_ to wait.

**Core principles:**

1. **Declarative over imperative** - YAML flows describe user intent, not implementation details 2. **Built-in tolerance** - Maestro auto-waits up to 7 seconds for elements, auto-retries taps, and handles animation delays without explicit waits 3. **Single flow, multiple platforms** - One YAML file can test both iOS and Android with platform conditions for differences 4. **Composition over duplication** - Extract reusable sequences (login, setup, teardown) into subflows with `runFlow` 5. **Stable selectors** - Use accessibility identifiers (`id`) over visible text to survive localization and copy changes

**Mental model:**

Maestro flows are recipes. Each step is an action a user would take. The framework handles timing, retries, and platform differences. You describe the journey, Maestro drives the car.

**When to use Maestro:**

• Smoke tests for critical user journeys (login, purchase, onboarding)
• Regression tests for flows that broke before
• Cross-platform verification with a single flow file
• Visual recording of test runs for stakeholder review

**When NOT to use Maestro:**

• Isolated unit tests for business logic
• API contract testing without UI
• Performance benchmarking or load testing
• Complex data-driven testing requiring heavy programmatic logic (Maestro's JS support is limited compared to full test frameworks)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Flow Structure and Basic Commands

Every flow starts with a configuration block (appId, optional env/tags) separated from commands by `---`. Commands execute sequentially top to bottom.

appId: com.example.app
tags:
  - smoke
  - auth
---
- launchApp
- tapOn:
    id: "email_input"
- inputText: "user@example.com"
- tapOn:
    id: "password_input"
- inputText: "secure_password"
- tapOn:
    id: "login_button"
- assertVisible:
    id: "home_screen"

**Why good:** appId identifies the app under test, tags enable filtering with --include-tags/--exclude-tags, id selectors are stable across l