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.

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

id

runFlow

waitForAnimationToEnd

startRecording

stopRecording

env

• 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

• 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)

• 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

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

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

• 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

• 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)

• tapOn: id: "submit_button"

• tapOn: text: "Submit"

• tapOn: text: "Delete" below: "Shopping Cart"

• tapOn: id: "toggle_switch" enabled: true

**Why good:** id selectors survive text changes, relational selectors disambiguate duplicate labels, state selectors prevent tapping disabled elements

See [examples/core.md](examples/core.md) for all selector types including index, point, and combined selectors.

---

appId: com.example.app

• runFlow: file: subflows/login.yaml env: USERNAME: "test_user@example.com" PASSWORD: "test_password" label: "Log in as test user"
• tapOn: id: "cart_icon"
• runFlow: file: subflows/complete-checkout.yaml label: "Complete purchase flow"
• assertVisible: id: "order_confirmation"

```yaml

appId: com.example.app

• tapOn: id: "email_input"
• inputText: ${USERNAME}
• tapOn: id: "password_input"
• inputText: ${PASSWORD}
• tapOn: id: "login_button"

**Why good:** login sequence defined once and reused across all flows, env parameters make subflows configurable, labels improve test report readability

See [examples/flow-control.md](examples/flow-control.md) for inline subflows, conditional flows, and nested composition.

---

• runFlow: when: platform: Android commands: - tapOn: "Allow"
• runFlow: when: platform: iOS commands: - tapOn: "Allow While Using App"

• runFlow: when: visible: "Rate this app" commands: - tapOn: "Not now"

**Why good:** single flow handles both platforms, visibility conditions handle non-deterministic UI (popups, tooltips), no test failure on missing optional elements

See [examples/flow-control.md](examples/flow-control.md) for JavaScript conditions and combined conditions.

---

• inputText: user_${Date.now()}@test.com

• evalScript: ${output.timestamp = Date.now()}
• inputText: ${output.timestamp}

• runScript: scripts/generate-test-data.js
• inputText: ${output.generatedEmail}

**Why good:** inline expressions handle simple dynamic values, evalScript sets variables without UI interaction, runScript keeps complex logic in testable JS files, output object passes data between steps

See [examples/flow-control.md](examples/flow-control.md) for HTTP requests in scripts, DataFaker, and output namespacing.

</patterns>

---

<decision_framework>

• Using

  text

  selectors for buttons/labels that will be localized - breaks when language changes. Use

  id

  (accessibility identifiers) instead.
• Duplicating login/setup steps in every flow file - extract to subflow and call with

  runFlow

• Missing

  stopRecording

  after

  startRecording

  - produces corrupted or zero-byte video files
• Hardcoding credentials or API keys in YAML flow files - use environment variables with

  -e

  or

  MAESTRO_

  prefix
• Using arbitrary

  sleep

  or

  extendedWaitUntil

  with long timeouts instead of

  waitForAnimationToEnd

  - Maestro's built-in tolerance handles most timing issues automatically

• Not using

  clearState

  or

  clearKeychain

  in setup - test results depend on leftover app state from previous runs
• Not using

  tags

  for flow categorization - makes it impossible to run targeted subsets (smoke, regression, etc.)
• Using

  point

  selectors (coordinates) as primary strategy - breaks on different screen sizes and resolutions
• Not using

  label

  on runFlow calls - test reports show file paths instead of meaningful step descriptions
• Putting all flows in the root directory without subdirectories - becomes unmanageable beyond 20+ flows

• assertVisible

  auto-retries for 7 seconds before failing - this is a feature, not a bug. Don't add explicit waits before assertions.
• CLI parameters are always strings - use

  parseInt()

  or comparison in JavaScript if you need numeric logic

• MAESTRO_

  prefixed shell variables are automatically available in flows but only via CLI, not Maestro Studio
• The string

  "false"

  is truthy in JavaScript - use explicit

  === "true"

  comparison in

  when: true:

  conditions

• onFlowComplete

  runs even when the flow fails - design teardown logic that doesn't assume success

• runFlow

  with

  commands

  (inline) and

  runFlow

  with

  file

  (external) are mutually exclusive - you cannot use both in the same runFlow call
• Template literals (backticks) do not work inside

  evalScript

  because the command is already wrapped in

  ${}

  - use string concatenation instead

• console.log

  in

  evalScript

  writes to

  maestro.log

  , not the terminal - use

  runScript

  for terminal-visible logging

• retry

  maxRetries is capped at 3 - for more attempts, restructure the flow logic
• Maestro Cloud

  --async

  flag returns immediately without waiting for results - poll the API or use webhooks for completion
• FlashList / RecyclerView items may not have stable accessibility IDs - use

  scrollUntilVisible

  with text fallback for list items

All code must follow project conventions in CLAUDE.md

id

runFlow

waitForAnimationToEnd

startRecording

stopRecording

env