# Maestro documentation Overview of Maestro documentation with links to guides, tutorials, and community resources. Maestro is the simplest and most effective framework for painless mobile and web UI automation using intuitive YAML flows. {% embed url="" %}
Cover image
What is Maestro?Learn what Maestro can do for you when testing applications/pages/yd3YLUukE5M8wZT1CE5D/files/T2fcJCUlI4DlCv5wqrZ4
QuickStartGet up and running with Maestro in just a few minutes/pages/IyVjUYlja4evcymb2uG3/files/oWLVxtnJWEbbqglV5J6e
### Maestro Solutions
Cover image
Maestro StudioCreate tests visually using the Desktop App for zero-IDE setup and instant device connection/spaces/eQi66gxHTt2vx4HjhM9V/files/O7IAFuXOVkyVu2hJGD5U
Maestro CLILearn to Install the CLI, manage devices, and run tests from your terminal/spaces/kq23kwiAeAnHkGJYMGDk/files/toW9PJRilCkCH5SKwfHb
Maestro CloudScale your testing by integrating with CI Platforms like GitHub Actions to run parallel tests/spaces/ky7LkNoLfvcORtXOzzBs/pages/C54ANLVbWffSqhNsoSZU/files/as25p3AxDs1IhAOf7zYn
### Learn How to Test Using Maestro
Cover image
:1:How Maestro worksLearn about Maestro’s architecture-agnostic approach, device control, and how flows simulate real human interactions/pages/P05NwN6Aox1FpJgtQRoy
:2:Maestro FlowsMaster modular testing with Nested Flows, Loops, Conditions, and Hooks/spaces/mS3lsb9jRwfRHqddeRXG
:3:JavaScriptUse JavaScript to handle complex conditions, data manipulation, and external API interactions/spaces/mS3lsb9jRwfRHqddeRXG/pages/N72iCVWiRWYBZ8BruPC7
:4:Manage your workspaceLearn to configure global behaviors with config.yaml, organize repository architectures, and manage test execution and analysis./spaces/mS3lsb9jRwfRHqddeRXG/pages/KFSFrrC0ZCkU35FT0Y7B
### Reference and Resources Explore the technical specifications and community-proven strategies.
API ReferenceA complete guide to every Maestro command/spaces/HqSeOOzxPCLfnK9YzOkb
ExamplesProven recipes and real-world examples for you to explore/spaces/JjfcEdmJ9ojsT3Jtpsi8
TroubleshootingFind answers in the FAQ and review Known Issues/spaces/htfynyR39703f5pJOF1P/pages/79oJhjYKEIqSnUmiko8K
### Join the Community See real workflows from other teams, and join the [Maestro Slack community](https://slack.maestro.dev/) to share and learn best practices.
Cover image
Community ProjectsDiscover VSCode extensions, plugins, and wrappers built by the Maestro community/spaces/htfynyR39703f5pJOF1P/pages/DlkzL5O0WJX77R2QnWF4/files/qK0cXfY4186M2aZxIpz8
ArticlesExplore a list of blog posts, deep dives, and tutorials from industry experts/spaces/htfynyR39703f5pJOF1P/pages/1QHDegQRkO1BKEg341mL/files/pFMymPHQiTRWzoPibNoi
Customer ShowcaseCheck how teams like Doccla, Wahed, and Eneco revolutionized their mobile testing/spaces/htfynyR39703f5pJOF1P/pages/ONBmKZIrglKc4g8863cw/files/1Q0bewRwMiZ2Gs1WdcG9
# What is Maestro? Maestro is an open-source UI automation framework for mobile and web with built-in tolerance, zero-wait intelligence, and declarative YAML syntax. Maestro is the simplest and most effective open-source UI automation framework for mobile and web. It is designed to allow developers and testers to define and automate user journeys with a level of reliability and ease that traditional tools cannot match.
Traditional testing tools often require deep instrumentation, access to the app's source code, and a strong coding ability. Maestro changes this by operating at "[arm's length](/get-started/how-maestro-works#the-arms-length-philosophy)," piloting the device, not the app, scrolling and tapping like a real user would through the same accessibility layer that real users rely on. This eliminates framework dependencies, allowing you to test any app, regardless of whether it was built with React Native, Flutter, or Native code. ### Why choose Maestro?
:shield: Built-in ToleranceMaestro embraces the instability of mobile devices by automatically handling flakiness and UI settling.
:timer: Zero-Wait IntelligenceNo more manual sleep() calls. Maestro automatically waits for network content and animations to load.
:file: Declarative SyntaxTests are defined in human-readable YAML files, removing the need for deep programming knowledge.
:rocket-launch: Blazingly Fast IterationTests run without compilation. Maestro can monitor your files and rerun flows instantly upon saving.
:box: Single Binary SetupMaestro is a single tool that works anywhere, avoiding the "setup hell" associated with legacy drivers.
{% hint style="success" %} πŸš€ **Running in the cloud** Ready to wire into CI or scale up your testing? Start running your flows on [Maestro Cloud](https://maestro.dev/cloud). Check the Cloud documentation to run tests in the cloud and integrate with your CI pipeline. {% endhint %} ### Maestro vs competitors While tools like Appium or Selenium treat testing like unit tests inspecting internal APIs, Maestro treats your app as a black box. By simulating "human thumbs on a screen," Maestro validates the complete user experience stack, including interactions with system settings and notifications. ### Ready to start? Explore the core components of the Maestro ecosystem and begin your journey:
How Maestro worksUnderstand the "arm's length" philosophy and accessibility-first element detection./pages/P05NwN6Aox1FpJgtQRoy
QuickStart guideInstall Maestro Studio and run your first test in under five minutes./pages/IyVjUYlja4evcymb2uG3
Maestro solutionsCompare the Maestro CLI, Maestro Studio (IDE), and Maestro Cloud to find the right tool for your workflow./pages/epPDXejAMuAN8YhVc0iR
Supported platformsView the full list of supported frameworks, including Jetpack Compose, SwiftUI, and Web./pages/Yji3ZRqXunrjvcov0BhZ
# How Maestro works Learn how Maestro simulates user interactions using the accessibility tree and device-level commands. Maestro operates as a black-box testing framework that simulates user interactions at the device level. Unlike traditional tools that require access to an app's source code or internal APIs, Maestro leverages the operating system's built-in accessibility and input interfaces to treat the application as an opaque system. ### The "arm's length" philosophy The central mechanic of Maestro is its "arm's length" operation, meaning the framework pilots the device itself rather than the internal app code. * **Platform Agnostic**: Because Maestro interacts with the Accessibility Tree (the data layer used by screen readers), it provides a consistent experience across heterogeneous stacks like Native iOS/Android, React Native, and Flutter. * **Human Simulation**: Maestro reproduces physical actions, like "thumbs on a screen", by sending low-level device commands for tap events, swipe gestures, and text input. * **System-Wide Control**: Since it controls the device, Maestro can interact with elements outside the app, such as system settings, permission dialogs, and notifications. ### Declarative test definition (YAML) Tests are defined in simple YAML files, allowing user journeys, referred to as Flows, to be readable as English instructions. * **Built-in Intelligence**: Maestro features "idiomatic" commands designed to solve common automation hurdles. For example, `scrollUntilVisible` mimics human visual search by automatically scrolling until it finds an element, rather than requiring brittle coordinate-based logic. * **Built-in Tolerance**: Maestro "embraces instability" by automatically waiting for the screen to "settle" or for content to load, removing the need for manual `sleep()` or artificial wait commands. {% embed url="" %} ### Maestro ecosystem and workflow The Maestro suite provides different interfaces to interact with the same core execution engine. #### Maestro Studio (Visual IDE) Maestro Studio is the recommended entry point for new users to build tests visually: 1. **Connection**: Studio connects to a device and mirrors the screen to your browser. 2. **Visual Interaction**: You click on elements of the mirrored screen, and Studio identifies them and suggests commands. 3. **Real-time Execution**: Commands are inserted into your YAML file and executed on the device instantly, allowing for step-by-step flow construction.
#### Maestro CLI The CLI is the open-source engine that interprets YAML files and sends instructions to the device. On both Android and iOS, it installs and communicates with a small companion driver app on the device to see what's on screen and carry out actions like taps and swipes. The CLI is the primary tool for automated execution in Continuous Integration (CI) systems. #### Maestro Cloud Maestro Cloud acts as the execution backend for large-scale testing. Teams upload their apps and Flows to run in parallel across multiple hosted virtual devices, ensuring deterministic results and faster feedback loops. ### Advanced logic and modularity To handle complex scenarios without code duplication, Maestro utilizes modular logic and scripting: * **Subflows**: Common sequences, such as a "Login" process, can be saved in separate files and called by multiple main tests to facilitate maintenance. * **Hooks**: Commands like `onFlowStart` and `onFlowComplete` manage app state, such as clearing cache before a test or logging out after completion. * **JavaScript**: For dynamic data needs (e.g., generating random emails), you can inject small JavaScript snippets that run in a restricted environment without access to the local file system. ### Next steps To continue your journey with Maestro, choose one of the following options:: * Check the [QuickStart](/get-started/quickstart) guide to learn how to install Maestro Studio and run your first test. * Explore each of the available [Maestro solutions](/get-started/maestro-solutions). # QuickStart Install Maestro Studio, set up your environment, and run your first automated test in five minutes. You are starting your journey with Maestro. This guide will help you install [Maestro Studio](https://docs.maestro.dev/maestro-studio/), set up your environment, and execute your first automated test (called a **Flow**) in just five minutes. {% stepper %} {% step %} #### Platform-specific setup Maestro requires a running target device to execute your tests. Use the tabs below to configure your virtual environment. {% tabs %} {% tab title="Android" %} 1. Download the latest version of Android Studio from the [official site](https://developer.android.com/studio) and install it. 2. Open Android Studio, click **More Actions**, and select **Virtual Device Manager**. 3. Click **Create Virtual Device (+)**, select a modern device (e.g., Pixel 8), and download a system image (API 31 or higher is recommended). {% hint style="info" %} Maestro currently supports **API Levels 29, 30, 31, 33, and 34**. API 35 and 36 support is arriving in Q2 2026. {% endhint %} 4. Finish the wizard and click the **Play** button to start the emulator. {% endtab %} {% tab title="iOS" %} 1. Download Xcode from the [Mac App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12) and install it. 2. Open Xcode, go to `Settings > Locations`, and ensure the **Command Line Tools** are selected. 3. Open Xcode and go to `Xcode > Open Developer Tool > Simulator` to launch the simulator. 4. If no device is available, go to `Xcode > Settings > Platforms` and ensure an iOS runtime (iOS 16, 17, 18, or 24) is installed. {% hint style="warning" %} **Xcode is installed but no iOS simulators appear?** If you installed Xcode without opening it (for example via [`xcodes`](https://github.com/XcodesOrg/xcodes) or a scripted install), macOS may not have installed Xcode's required system components - so the CoreSimulator framework is missing and simulators won't load. In Maestro Studio this shows up as no iOS devices in the device list. Complete the one-time component install: ```bash xcodebuild -runFirstLaunch # If you're prompted to accept the license first, run: sudo xcodebuild -license accept # Then restart Maestro Studio # iOS simulators should now appear. ``` {% endhint %} {% endtab %} {% endtabs %} {% endstep %} {% step %} #### Installation Download the appropriate installer for your operating system: * **Windows:** [MaestroStudio.exe](https://studio.maestro.dev/MaestroStudio.exe) * **macOS:** [MaestroStudio.dmg](https://studio.maestro.dev/MaestroStudio.dmg) * **Linux:** [MaestroStudio.AppImage](https://studio.maestro.dev/MaestroStudio.AppImage) Follow the platform-specific installation prompts: * **Windows:** Double-click the `.exe` and follow the setup wizard. * **macOS:** Open the `.dmg` and drag Maestro Studio to your `Applications` folder. * **Linux:** Make the `.AppImage` executable and run it with the `--no-sandbox` flag: ```bash chmod +x MaestroStudio.AppImage ./MaestroStudio.AppImage --no-sandbox ``` {% endstep %} {% step %} #### Create your first test Once your device is running and Maestro Studio is open, you can create your first Flow. 1. Open Maestro Studio and click **Choose new workspace location** to define the directory on your computer to store your tests.
2. Click the **No device connected** button at the top. Select your running Android Emulator or iOS Simulator from the list. The virtual device will pop up. 3. Click **Create a new test** to open the setup window.
4. On the **Add a new test to your workspace** window, select **Mobile Test** and enter the following: {% tabs %} {% tab title="Android" %} * **Name**: Name for your YAML file. * **App Id**: From the dropdown menu, select the App Id for testing. For this QuickStart, select **com.google.android.contacts** from the dropdown menu.
{% endtab %} {% tab title="iOS" %} * **Name**: Name for your YAML file. * **App Id**: From the dropdown menu, select the App Id for testing. For this QuickStart, select **com.apple.MobileAddressBook** from the dropdown menu.
{% endtab %} {% endtabs %} {% hint style="info" %} You can also use the **Scan file for App Id** option to automatically detect the identifier from an `.apk` (Android) or `.app/.zip` (iOS) file. You can also add tags to keep your tests organized. {% endhint %} 6. Click **Create Test**. Maestro will generate a minimal YAML file to launch the app. {% tabs %} {% tab title="Android" %} ```yaml appId: com.google.android.contacts --- - launchApp: clearState: true ``` {% endtab %} {% tab title="iOS" %} ```yaml appId: com.apple.MobileAddressBook --- - launchApp: clearState: true ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} #### Run your first test With your first YAML file created, let's add a few commands to perform a search. In the Maestro Studio editor, copy and paste the example below for your platform. {% tabs %} {% tab title="Android" %} ```yaml appId: com.google.android.contacts --- - launchApp: clearState: true - tapOn: Allow - tapOn: Create contact - tapOn: First name - inputText: John - tapOn: Last name - inputText: Doe - tapOn: Company - inputText: Maestro - tapOn: "+1" - inputText: 111-111-1111 - tapOn: Save - back - takeScreenshot: All Contacts ``` The test launches the native Contacts app, creates a new entry, saves it, and captures a screenshot. {% hint style="info" %} To learn more about the commands you can use to create tests, access the [API Reference](https://docs.maestro.dev/reference/)page. To learn about how you can structure tests, also referred to in Maestro as Flows, access the [Flows](https://docs.maestro.dev/maestro-flows/). {% endhint %} After pasting, click **Run Locally**. Watch your virtual device execute the steps automatically. Maestro Studio will highlight each step as it succeeds or provide a failure reason if an element cannot be found.
{% endtab %} {% tab title="iOS" %} ```yaml appId: com.apple.MobileAddressBook --- - launchApp - tapOn: All iPhone - tapOn: Add - tapOn: First name - inputText: John - tapOn: Last name - inputText: Doe - tapOn: Company - inputText: Maestro - tapOn: John - tapOn: add phone - inputText: +1 111-111-1111 - tapOn: Done - tapOn: Back - takeScreenshot: All Contacts ``` The test launches the Address Book app, adds a new contact, and saves the result. {% hint style="info" %} To learn more about the commands you can use to create tests, access the [API Reference](https://docs.maestro.dev/reference/) page. To learn about how you can structure tests, also referred to in Maestro as Flows, access the [Flows](https://docs.maestro.dev/maestro-flows/). {% endhint %} After pasting, click **Run Locally**. Watch your virtual device execute the steps automatically. Maestro Studio will highlight each step as it succeeds or provide a failure reason if an element cannot be found.
{% endtab %} {% endtabs %} {% endstep %} {% endstepper %} {% hint style="success" %} **Interactive Flow authoring** While this QuickStart focuses on manual YAML, Maestro Studio offers three interactive ways to build your test: * **Inspect Screen**: Click the **Inspect Screen** button to select elements visually on the device and receive recommended commands. * **Insert Command**: Click the **Insert Command** button in the IDE to choose from a list of standard actions. * **Manual Entry**: Type commands directly into the YAML editor for precise control. :hand-point-right: **Access** [Run tests with Maestro Studio](/maestro-studio/run-tests-with-maestro-studio) **for more information.** {% endhint %} ### Video walkthrough Watch this step-by-step video to see the first test creation process in detail: {% embed url="" %} ### Next steps Now that you’ve seen the power of "arm's length" automation, explore these resources to master the ecosystem: * Visit the [Maestro Studio](https://docs.maestro.dev/maestro-studio/) to learn how to use visual element inspection and the Live REPL to build tests without writing code from scratch. * If you prefer a programmatic approach or need to integrate tests into your CI/CD pipeline, head to the [Maestro CLI](https://docs.maestro.dev/maestro-cli/). * To learn the best practices for logic, modularity, and nesting, or learn how to add JavaScript scripts to your tests check out the [Flows](https://docs.maestro.dev/maestro-flows/). # Maestro solutions Explore Maestro's ecosystem: Studio, CLI, Cloud, and Flows, plus how they fit into local automation and CI/CD workflows. The Maestro ecosystem is a unified platform composed of three interconnected layers. Each tool is designed to solve a specific challenge in the mobile and web automation lifecycle: * **Maestro Studio**: Desktop IDE for writing and running Maestro flows * **Maestro CLI**: Command line tool for running Maestro flows * **Maestro Cloud**: Hosted platform for consistent, parallel Maestro execution ### **Maestro Studio (The IDE)** Maestro Studio is a visual interface built on top of the CLI, designed for rapid test creation and real-time element inspection. By mirroring your device screen and allowing you to build [Flows](https://docs.maestro.dev/maestro-flows/) through simple point-and-click interactions, it serves as the primary tool for zero-code authoring and interactive debugging. You can start building your first Flows today by visiting the [Maestro Studio](https://docs.maestro.dev/maestro-studio/) documentation. ### **Maestro CLI** The CLI is the open-source heart of Maestro and the core engine that powers both Maestro Studio and Maestro Cloud. It serves as the workhorse for developers and DevOps engineers, interpreting your YAML files to orchestrate test execution. Because everything else is built on top of the CLI, it acts as the foundational backbone for all local automation and CI/CD integration. To learn more about its technical capabilities and orchestration features, check out the [Maestro CLI](https://docs.maestro.dev/maestro-cli/) documentation. ### **Maestro Cloud** Maestro Cloud is a managed execution solution designed to scale your testing infrastructure without the overhead of managing local device farms. It leverages the Maestro CLI to run your tests on a distributed cloud of virtual devices, enabling massive parallelization and providing fast and reliable feedback loops for production-ready reliability. Explore how to scale your regression suites in the [Maestro Cloud](/maestro-cloud) documentation. ### Which solution should I use? Use the table below to determine which tool fits your current workflow: | **Feature** | **Maestro Studio** | **Maestro CLI** | **Maestro Cloud** | | --------------- | ----------------------- | ----------------------- | ------------------------------------------------------------------- | | **Best For** | Authoring & Debugging | Local execution & CI/CD | Reliable & scalable parallel test execution | | **Interface** | Visual (GUI) | Terminal (Command Line) | Upload via CLI, see runs via web, notifications via Slack + Webhook | | **Execution** | Real-time / Interactive | Sequential (Local) | Parallel (Simultaneous) | | **Target User** | Testers & Developers | Engineers & DevOps | Growth & Professional Teams | | **Environment** | Local Device/Emulator | Local Device/Emulator | Hosted Virtual Devices | ### The typical learning path Most teams follow a three-stage journey to automation success: 1. **Creation**: Start with [Maestro Studio](https://docs.maestro.dev/maestro-studio/) to visually build and debug your first [Flows](https://docs.maestro.dev/maestro-flows/). 2. **Automation**: Use the[ Maestro CLI](https://docs.maestro.dev/maestro-cli/) to run those Flows locally and integrate them into your basic development workflow. 3. **Scaling**: Once your test suite grows, transition to [Maestro Cloud](/maestro-cloud) to run those same tests in parallel for instant feedback on every Pull Request. ### Next steps If you already know the Maestro solution you are going to use, access the desired documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) If you don't know how to create tests with Maestro, access the [QuickStart](/get-started/quickstart) guide to get up and running in minutes. # Supported platforms Platforms supported by Maestro: Android, iOS, React Native, Flutter, and web applications via UI-layer automation.
Maestro operates on the principle of UI-layer automation rather than code instrumentation. Like a test driver interacting with any vehicle through its controls (steering wheel, pedals), Maestro interfaces with applications through their visual and accessibility layers, regardless of the underlying technology stack. ### Mobile operating systems (core) Maestro provides comprehensive automation support for major mobile platforms: * **Android:** Full support for emulators and physical devices * **iOS:** Full support for simulators Both platforms pass validation at scale by enterprise teams at Microsoft, DoorDash, and others for complex automation scenarios. ### Framework agnosticism Maestro decouples test automation from framework implementation by interacting directly at the UI layer. This removes the need for framework-specific instrumentation, which is a departure from tools like Detox or Appium, which depend on complex native drivers and in-app code injection. Supported technology stacks include: * **Native:** Swift, Kotlin, Java, Objective-C. * **Cross-platform:** React Native, Flutter. * **Other hybrid frameworks.** ### Web automation * **Status:** Functional with ongoing development. * **Approach:** Maestro extends support to web applications, enabling cross-platform test consolidation using consistent automation syntax. * **Use Case:** Unified testing strategy across mobile and web surfaces. ### System-level interaction Maestro supports device-level automation beyond app boundaries: * **System Interaction:** Navigate to Settings, modify permissions, toggle Wi-Fi, and monitor app behavior in response to system state changes. * **Real-world Scenarios:** Automated testing of notification handling, permission flows, and inter-app interactions. ### Next steps Explore the details on how to use Maestro in each one of the supported operating systems and frameworks: * [Android](/get-started/supported-platform/android) * [Android Native](/get-started/supported-platform/android/android-native) * [Jetpack Compose](/get-started/supported-platform/android/jetpack) * [iOS](/get-started/supported-platform/ios) * [SwiftUI](/get-started/supported-platform/ios/swiftui) * [UIKit](/get-started/supported-platform/ios/uikit) * [React Native](/get-started/supported-platform/react-native) * [Flutter](/get-started/supported-platform/flutter) * [Web Browsers](/get-started/supported-platform/web-browser) # Android Configure Maestro for Android app testing with emulators or physical devices.
Maestro provides a high-level abstraction for Android testing by simulating end-user interactions at the presentation layer. Unlike other frameworks, Maestro doesn't live inside your app, it pilots the device from the outside. ### A UI-centric approach Maestro operates through the Android display stack, ensuring your tests are framework-agnostic. Whether you use Kotlin, Java, Flutter, React Native, or Compose, Maestro interacts only with the rendered UI. * **Human-Like Simulation**: Maestro translates declarative commands into system-level inputs, mimicking genuine user behavior on the Android input pipeline. * **Zero Instrumentation**: You don't need to add test dependencies to your `build.gradle` or compile a special "test APK." ### System-level control Maestro drives the entire device, not just your app. If you need to change WIFI settings, read a notification, create contacts, or manage anything else that depends on device state or data, you can do so in exactly the same way a real user would, using "real human thumbs." To manage system settings mid-test, you can interact with the OS directly or use built-in commands: ```yaml - toggleAirplaneMode - tapOn: "Airplane mode" - runFlow: toggle_wifi.yaml # Use a subflow for complex system interactions ``` Android apps often cache data that can lead to flaky tests. The `clearState` command ensures a reproducible environment by clearing app data (the equivalent of`adb shell pm clear `) before the app launches, giving the app a "just installed" state. ```yaml - launchApp: appId: "com.example.app" clearState: true # Resets app data for a clean launch ``` ### Execution and environment setup Maestro connects to your target via ADB (Android Debug Bridge). * **Emulators & Physical Devices**: Maestro automatically detects and connects to running emulators or physical devices. For physical hardware, ensure "USB Debugging" is enabled in Developer Options. * **App Identification**: Maestro targets your application using the **Package** found in your `AndroidManifest.xml` (the `appId`). * **Installation**: Maestro assumes the application is already installed on the target device/emulator before the test begins. ### Cross-platform configuration If your Android and iOS applications use different identifiers, we recommend using [environment variables](/maestro-flows/flow-control-and-logic/parameters-and-constants) to keep your [Flows](https://docs.maestro.dev/maestro-flows/) cross-platform. You can manage these variables in three primary ways: 1. **Maestro Studio**: Configured via the [Environment Manager](/maestro-studio/environments-and-variables). 2. [**Maestro CLI**](/maestro-flows/flow-control-and-logic/parameters-and-constants#passing-parameters-via-cli): Passed as arguments during execution. 3. **Flow Configuration**: Defined directly in the [config matter](/maestro-flows/flow-control-and-logic/parameters-and-constants#constants) at the top of an individual Flow file. To run a single test suite against different platforms where the App ID varies, structure your Flow to use a variable: ```yaml # In your Flow appId: ${APP_ID} --- - launchApp ``` When executing locally with the [Maestro CLI](https://docs.maestro.dev/maestro-cli/), use the `-e` or `--env` flag to inject the correct identifier for that specific run: ```bash maestro test -e APP_ID=com.example.android flow.yaml ## or maestro test --env APP_ID=com.example.android flow.yaml ``` ### Maestro Cloud When your suite grows, local sequential execution becomes a bottleneck. [Maestro Cloud](/maestro-cloud) spins up multiple virtual Android devices to run your tests in parallel. | **Feature** | **Local Android** | **Maestro Cloud** | | ------------------- | ------------------ | ---------------------------------- | | **Parallelization** | 1 device at a time | Scale to as many devices as needed | | **Speed** | Slow (Sequential) | Blazingly Fast (Parallel) | | **Cleanup** | Manual | Automatic Infrastructure Teardown | ### Next steps Explore the dedicated [Android Native](/get-started/supported-platform/android/android-native) and [Jetpack Compose](/get-started/supported-platform/android/jetpack) documentation for platform-specific patterns. If you already know the Maestro solution you are going to use, access the desired documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) If you are new to the platform, follow the [QuickStart](/get-started/quickstart) guide to get up and running in minutes. # Android Native Black-box testing for Android Views and Jetpack Compose via the Accessibility layer. Target elements by text, Resource ID, Content Description, or testTag.
Maestro provides a black-box testing approach for native Android applications. By interacting with the app through the Android Accessibility layer rather than internal code instrumentation, you can test production-ready binaries without modifying your source code. ### Technical advantages * **Zero Instrumentation**: No custom Gradle configurations, `build.gradle` dependencies, or test-specific APK builds are required. You test the exact binary your users receive. * **Refactoring Resilience**: Migrating your UI implementation will not break your tests as long as the user-visible text or semantic IDs remain consistent. * **UI-Layer Interaction**: Maestro interacts with rendered UI elements, ensuring that tests validate the actual user experience rather than internal component states. ### Element interaction strategies In Android development, Maestro leverages the accessibility layer of the device to identify and interact with elements via primary methods: * **Text Selection**: Target any view with a `text` property (e.g., `Button`, `TextView`). ```yaml - tapOn: "Login" ``` * **Resource ID**: Access views by their `android:id`. This is ideal for disambiguating identical text elements. ```yaml - tapOn: id: "login_button" ``` * **Content Description**: The `android:contentDescription` attribute is surfaced as a text property, making it the "gold standard" for automating icons and image-based buttons. ```yaml - tapOn: "Settings Icon" ``` * **Hints**: For input fields that have not yet been filled, the `android:hint` attribute is also exposed to the text selector. #### Handling lists and dynamic content Native Android often uses `RecyclerView` or `LazyColumn` for long lists. Maestro abstracts the complexity of view recycling through intelligent scrolling. Instead of calculating scroll offsets, use the built-in intelligence of Maestro to find elements that are currently off-screen: ```yaml - scrollUntilVisible: element: text: "Item #50" direction: DOWN ``` Maestro will automatically swipe down, wait for the next items to load, and stop only when the target element is detected in the view hierarchy. ### Known limitations While Maestro can detect and tap on views containing Unicode characters, direct inputting (typing) of Unicode text via the `inputText` command is currently not possible. ### Next steps If you don't know how to create tests with Maestro, access the [QuickStart](/get-started/quickstart) guide to get up and running in minutes. To learn how to create tests, refer to the [Flows](https://docs.maestro.dev/maestro-flows/) documentation. If you want to explore Maestro solutions, consult the appropriate documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) # Jetpack Compose Black-box testing for Jetpack Compose via AccessibilityService. Prioritizes text-based matching and semantics over testTag for refactoring resilience.
Maestro follows a fundamental principle: **UI-level automation without framework intrusion**. Unlike instrumentation-based tools such as Espresso or Robolectric, which execute inside the app process and depend on framework-specific APIs, Maestro operates externally using Android’s system automation interfaces. This allows Maestro to perform reliable black-box testing regardless of whether your UI is implemented with XML Views, Jetpack Compose, or other UI frameworks. ### Architecture-agnostic testing philosophy Maestro interacts with your application the same way the Android system and users do, using accessibility metadata and system-level automation. This provides several key advantages: * **Framework independence:** Maestro does not depend on Compose internals such as composition state, recomposition cycles, or render tree structure. Tests remain valid regardless of UI implementation details. * **System-level element discovery:** Maestro locates elements using accessibility metadata, visible text, resource identifiers, and other stable attributes exposed by the Android system. This ensures compatibility with Compose, XML Views, and hybrid applications. * **Stable selector model:** Element identification relies on externally observable properties such as visible text, accessibility labels (`contentDescription`), and resource IDs, rather than internal framework constructs. ### Refactoring resilience Maestro tests are designed to validate user workflows rather than internal implementation details. This provides strong resilience during UI refactoring, including migration from XML-based layouts to Jetpack Compose. * **Semantic stability:** As long as visible text, accessibility metadata, or resource identifiers remain consistent, existing Maestro tests typically continue to work without modification. * **Implementation independence:** Tests verify behavior from the user’s perspective, protecting against failures caused by internal architectural changes that do not affect the user experience. ### Element interaction patterns Maestro interacts with UI elements using selectors based on system-exposed properties rather than framework-specific APIs. #### Element selection strategy Maestro supports multiple stable selector types, including: * **Visible text** ```yaml - tapOn: "Login" ``` Matches elements displaying the specified text. * **Accessibility labels** Elements with accessibility metadata such as: ```kotlin Modifier.semantics { contentDescription = "Login Button" } ``` can be targeted directly: ```yaml - tapOn: description: "Login Button" ``` * **Resource identifiers** When available, resource IDs provide highly stable selectors: ```yaml - tapOn: id: "login_button" ``` These selector strategies work consistently across Compose and View-based interfaces. ### Compatibility with Jetpack Compose semantics Jetpack Compose exposes accessibility metadata through its semantics system. Maestro automatically uses this information when available, including: * Visible text from composables such as `Text` and `Button` * Accessibility descriptions defined with `contentDescription` * Resource identifiers when provided This enables reliable interaction without requiring Compose-specific test APIs or instrumentation. ### Comparative advantages | Aspect | Maestro | Instrumentation Tools | | -------------------------- | ----------------------------------- | ---------------------- | | Execution model | External (black-box) | In-process (white-box) | | Framework dependency | None | High | | Compose internals required | No | Yes | | Test infrastructure in app | Not required | Required | | Refactoring resilience | High (when semantics remain stable) | Moderate to low | | Accessibility usage | Recommended for reliability | Optional | Maestro eliminates the need for app-side test infrastructure code, lowering barriers for QA practitioners lacking native Android development expertise. ### Next steps If you don't know how to create tests with Maestro, access the [QuickStart](/get-started/quickstart) guide to get up and running in minutes. To learn how to create tests, refer to the [Flows](https://docs.maestro.dev/maestro-flows/) documentation. If you want to explore Maestro solutions, consult the appropriate documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) # iOS Black-box iOS testing via the Accessibility layer. Run on Xcode Simulators, handle permissions, test multi-app journeys, and parallelize with Cloud.
Maestro provides a high-level abstraction for iOS testing by simulating end-user interactions at the presentation layer. Unlike traditional testing tools that require deep instrumentation, Maestro interacts with the iOS Accessibility layer, allowing you to test your app exactly as a user would. ### Black-box approach Maestro analyzes the rendered frames of the iOS device, ensuring your tests are framework-agnostic. Whether your app is built with Swift, Objective-C, Flutter, React Native, or SwiftUI, Maestro interacts only with the visual output. * **Physical Input Simulation**: Declarative commands are translated into native touch events. When you use `tapOn`, Maestro triggers the same iOS input pipeline that a physical touch would. * [**Arm's Length**](/get-started/how-maestro-works): Maestro doesn't require access to your source code or bytecode. You test the same `.app` bundle (the Simulator version) that runs on your virtual testing environment. ### System-level control Maestro’s architecture allows it to pilot the entire device, not just your application process. This enables testing for complex real-world scenarios. iOS is known for its strict permission dialogs (Location, Camera). However, Maestro can interact with these system prompts directly: ```yaml - launchApp: appId: "com.example.app" permissions: location: allow notifications: allow ``` Maestro also allows you to create multi-app journeys. You can test flows that leave your app, such as opening a link in Safari or checking an email, and then return to your application: ```yaml - tapOn: "Open Website" # Maestro follows the link into Safari - assertVisible: "Welcome to our site" - tapOn: id: "breadcrumb" # Native iOS 'Back' button to return to your app ``` ### Execution and environment setup Maestro connects to your target via native Apple development tools. * **Simulators**: Run tests on any iOS Simulator managed by Xcode. Ensure you have the Xcode Command Line Tools installed (`xcode-select --install`). * **App Identification**: iOS apps are targeted using the Bundle ID (e.g., `com.example.app`). ### Cross-platform configuration If your Android and iOS applications use different identifiers, we recommend using [environment variables](/maestro-flows/flow-control-and-logic/parameters-and-constants) to keep your [Flows](https://docs.maestro.dev/maestro-flows/) cross-platform. You can manage these variables in three primary ways: 1. **Maestro Studio**: Configured via the [Environment Manager](/maestro-studio/environments-and-variables). 2. [**Maestro CLI**](/maestro-flows/flow-control-and-logic/parameters-and-constants#passing-parameters-via-cli): Passed as arguments during execution. 3. **Flow Configuration**: Defined directly in the [config matter](/maestro-flows/flow-control-and-logic/parameters-and-constants#constants) at the top of an individual Flow file. To run a single test suite against different platforms where the App ID varies, structure your Flow to use a variable: ```yaml # In your Flow appId: ${APP_ID} --- - launchApp ``` When executing locally with the [Maestro CLI](https://docs.maestro.dev/maestro-cli/), use the `-e` or `--env` flag to inject the correct identifier for that specific run: ```bash maestro test -e APP_ID=com.example.app.ios flow.yaml ## or maestro test --env APP_ID=com.example.app.ios flow.yaml ``` ### Parallelization for iOS Scaling iOS tests locally can be difficult due to macOS hardware requirements. [Maestro Cloud](/maestro-cloud) provides instant access to a fleet of iOS Simulators, allowing you to run your entire suite in parallel. * **Speed**: Reduce test time drastically. * **Reliability**: Eliminate "flaky" results caused by local machine resource contention. * **CI/CD Integration**: Automatically trigger parallel iOS runs on every Pull Request. ### Next steps Explore the dedicated [UIKit](/get-started/supported-platform/ios/uikit) or [SwiftUI](/get-started/supported-platform/ios/swiftui) documentation, or access the [QuickStart](/get-started/quickstart) guide to get up and running in minutes if you do not know how to create tests with Maestro. If you already know which Maestro solution you are going to use, access the relevant documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) # SwiftUI Configure SwiftUI apps for Maestro testing with proper accessibility identifiers.
Maestro offers transparent support for SwiftUI applications. Because SwiftUI is declarative and content-centric, Maestro’s architecture-agnostic approach is perfectly suited for itβ€”treating components like `List`, `LazyVStack`, and `Picker` as interactive visual elements rather than complex code objects. ### The SwiftUI workflow While Maestro can find SwiftUI elements by their displayed text, using identifiers is the most resilient way to build your test suite. #### **Implementing accessibility identifiers** For icons, custom controls, or to avoid breaking tests when text is translated, apply the `.accessibilityIdentifier()` modifier in your Swift code. By adding the `.accessibilityIdentifier` modifier, you are explicitly tagging a component in the underlying iOS Accessibility Tree. ```swift // Step 1: In your SwiftUI View NavigationLink(value: Panel.donutEditor) { Label("Donut Editor", systemImage: "slider.horizontal.3") } .accessibilityIdentifier("donut_editor") ``` This ID is invisible to the end-user but is broadcast to any tool interacting with the system's accessibility layer. Thus, Maestro can interact with it using the `id` selector. ```yaml # Step 2: In your Maestro Flow - tapOn: id: "donut_editor" ``` ### Examples These snippets demonstrate how Maestro handles common SwiftUI patterns and system behaviors. #### **Native controls (pickers and toggles)** SwiftUI controls like `Picker` often require specific targeting, especially when multiple options are present. ```yaml appId: com.swiftui.kit --- - launchApp: clearState: true - tapOn: id: "controls_item" - tapOn: point: "84%,23%" # Precise coordinate tap for complex toggles - tapOn: text: "Chocolate" index: 0 - tapOn: id: "flavor_picker_segmented_Strawberry" # Target specific segments by ID ``` The examples above use a mix of IDs, Text, and Coordinates to navigate complex SwiftUI layouts. While the `id` selector is the most reliable way to target elements, you can also use `index` to handle duplicate text or `point` for precise taps on small system controls like Toggles. #### **System navigation and app switching** Maestro can handle "Inter-App" communication, such as following a link into Safari and using the system breadcrumb to return. ```yaml appId: com.swiftui.kit --- - launchApp - tapOn: "link_item" # Maestro follows the link into the Browser... - tapOn: id: "breadcrumb" # Returns to your app via the native iOS 'Back' link ``` #### Refactoring resilience A major advantage of using Maestro with SwiftUI is migration safety. If you rewrite a legacy UIKit screen entirely in SwiftUI, as long as the visual output and accessibility identifiers remain the same, your Maestro tests will require zero changes. #### Tips and known issues * **Hierarchy Quirks**: Some specific styles (like `WheelPickerStyle`) may not return a full hierarchy to the accessibility layer, making text-based selection preferred over ID selection in those cases. * **Merged Elements**: When a `Toggle` is initialized with text, iOS often merges the text and the switch into a single accessibility element. * **Maestro Studio**: Always use [Maestro Studio](https://docs.maestro.dev/maestro-studio/) to inspect SwiftUI views. It helps you see exactly how the nested view composition is resolved by the accessibility tree before you write your YAML. ### Next steps If you don't know how to create tests with Maestro, access the [Quickstart](/get-started/quickstart) guide to get up and running in minutes. To learn how to create tests, refer to the [Flows](https://docs.maestro.dev/maestro-flows/) documentation. If you want to explore Maestro solutions, consult the appropriate documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) # UIKit Black-box testing for UIKit via the accessibility layer. Use accessibilityLabel for text and accessibilityIdentifier (gold standard) for id selectors.
Maestro provides native, transparent support for iOS applications built with UIKit. Operating at the visual interaction layer rather than the implementation layer, Maestro interacts with rendered UI components regardless of underlying class hierarchies such as `UIButton`, `UITableView`, and `UILabel`. ### Technical advantages * **Zero Instrumentation**: Maestro does not require test libraries, delegates, or ViewController exposure. You test the built `.app` binary, nothing else. * **Implementation Agnostic**: Because Maestro validates user-facing features rather than internal code, you can refactor UIKit components to SwiftUI without breaking your tests, provided the visual output remains consistent. * **Black-Box Model**: Maestro adopts an [arm's length](/get-started/how-maestro-works) approach, simulating authentic user interactions with the rendered UI without needing access to internal source code. ### Element interaction strategies Maestro interacts with UIKit components by simulating authentic user interactions through the accessibility layer. #### **Interacting with views by text** Primary interaction in UIKit is often done via visible UI text. Any view with text content (like a `UIButton` title) can be targeted directly. ```swift // In your UIKit Swift code let button = UIButton() button.setTitle("Submit Order", for: .normal) ``` You can tap this button in your Flow using the visible text: ```yml - tapOn: "Submit Order" ``` #### **Using accessibility labels and IDs** For non-textual elements like icons, or for disambiguating duplicate elements, leverage iOS accessibility metadata. Maestro translates these properties into specific selectors: * `accessibilityLabel`: Maestro translates this to the `text` selector. * `accessibilityIdentifier`: Maestro translates this to the `id` selector. This is the gold standard for reliable tests. ```swift // In your UIKit Swift code let button = UIButton() button.accessibilityIdentifier = "login_button_id" ``` The corresponding tap command in your Flow would use the `id`: ```yaml - tapOn: id: "login_button_id" ``` ### Handling lists and complex components Maestro abstracts away the complexity of coordinate calculations and cell enumeration in `UITableView` and `UICollectionView`. #### **Intelligent scrolling** Instead of manual index or offset calculations, use `scrollUntilVisible`. Maestro combines visibility detection with continuous swiping to find elements that are currently off-screen. ```yaml - scrollUntilVisible: element: text: "List Item 50" direction: DOWN ``` ### Known limitations * **Simulators**: Full support for local execution on iOS Simulators. * **Physical Devices**: Executing tests on physical iOS devices is not supported yet. ### Next steps If you don't know how to create tests with Maestro, access the [QuickStart](/get-started/quickstart) guide to get up and running in minutes. To learn how to create tests, refer to the [Flows](https://docs.maestro.dev/maestro-flows/) documentation. If you want to explore Maestro solutions, consult the appropriate documentation: * [Maestro Studio](https://docs.maestro.dev/maestro-studio/) * [Maestro CLI](https://docs.maestro.dev/maestro-cli/) * [Maestro Cloud](/maestro-cloud) # React Native Configure React Native apps for Maestro testing on both Android and iOS platforms.
Maestro provides full support for React Native applications on both Android and iOS. By operating at the accessibility layer, Maestro enables cross-platform testing with a single test suite, requiring zero instrumentation or modifications to your JavaScript/TypeScript source code. ### Technical advantages * **Zero Library Dependencies**: You don't need to install any npm packages (like Detox or Appium drivers) inside your app. Maestro tests the final bundled binary. * **Fast Feedback Loops**: Maestro interacts directly with the native views rendered by React Native, providing faster execution than traditional bridge-based testing tools. * **Expo and EAS Ready**: Full compatibility with Expo Go, development builds, and EAS Workflows for CI/CD integration. ### Element interaction strategies In React Native, you can target components using visible text or unique identifiers. #### **Interacting by Text** Maestro can interact with any component that displays text content, such as `Button` titles or `Text` components. If you have a `Go` button, for example: ```javascript