Maestro — Painless E2E Testing for Mobile and Web

Introduction

Maestro is an end-to-end UI testing framework for mobile and web applications. Tests are written as declarative YAML flows that describe user interactions step by step. Maestro handles device communication, element location, and synchronization automatically, removing the flakiness that plagues traditional mobile testing tools. It supports iOS simulators, Android emulators, and real devices.

What Maestro Does

• Runs UI tests defined in YAML against iOS and Android apps with a single command
• Automatically waits for elements to appear, reducing test flakiness from timing issues
• Supports web testing via Chromium-based browsers
• Captures screenshots and video recordings during test execution for debugging
• Integrates with CI/CD pipelines through exit codes and JUnit XML reports

Architecture Overview

Maestro runs a local server that communicates with the target platform via platform-specific drivers: XCTest for iOS and UIAutomator2 for Android. The YAML flow file is parsed into a sequence of commands that the driver executes against the app's accessibility tree. Element matching uses text content, accessibility labels, or resource IDs. The built-in wait mechanism polls for element presence with configurable timeouts.

Self-Hosting & Configuration

• Install with the one-line installer script or via Homebrew on macOS
• Write flows in YAML files with a simple command vocabulary (tapOn, inputText, assertVisible, scroll)
• Organize flows in directories and run entire suites with maestro test directory/
• Configure device targets and timeouts via command-line flags or a maestro.yaml config file
• Use environment variables in flows for dynamic data like credentials or API URLs

Key Features

• Declarative YAML syntax that non-developers can read and write
• Built-in tolerance for UI delays without explicit sleep statements
• Continuous mode that re-runs tests on file change for rapid iteration
• Sub-flow composition for reusable login sequences and setup steps
• Maestro Cloud service for running tests on hosted device farms in parallel

Comparison with Similar Tools

• Appium — flexible but requires complex setup and language-specific bindings; Maestro is YAML-only and simpler
• Detox (Wix) — JavaScript-based React Native testing; Maestro is framework-agnostic
• XCUITest / Espresso — platform-native test frameworks; Maestro provides cross-platform coverage from one flow
• Playwright — browser-focused; Maestro covers native mobile apps
• Cypress — web-only; Maestro adds iOS and Android native app support

FAQ

Q: Does Maestro work with React Native and Flutter? A: Yes. Maestro tests the rendered UI, so it works with any framework that produces standard iOS or Android views.

Q: Can I run Maestro in CI? A: Yes. Run maestro test in any CI environment with an emulator or simulator. JUnit XML output integrates with most CI dashboards.

Q: How does it find elements? A: By text content, accessibility label, or resource ID. You can also use index-based selection or point coordinates.

Q: Is Maestro free? A: The CLI is open source and free. Maestro Cloud (hosted device farm) is a paid service.

Sources

• https://github.com/mobile-dev-inc/Maestro
• https://maestro.mobile.dev