# Table of Contents - [inputText | Maestro](#inputtext-maestro) - [Maestro Documentation | Maestro](#maestro-documentation-maestro) - [macOS | Maestro](#macos-maestro) - [Build and Install your App | Maestro](#build-and-install-your-app-maestro) - [Linux | Maestro](#linux-maestro) - [Installing Maestro | Maestro](#installing-maestro-maestro) - [Android | Maestro](#android-maestro) - [Windows | Maestro](#windows-maestro) - [Run a Sample Flow | Maestro](#run-a-sample-flow-maestro) - [iOS | Maestro](#ios-maestro) - [Maestro MCP | Maestro](#maestro-mcp-maestro) - [Cloud Quickstart | Maestro](#cloud-quickstart-maestro) - [Run Maestro tests in the cloud | Maestro](#run-maestro-tests-in-the-cloud-maestro) - [CI Integration | Maestro](#ci-integration-maestro) - [Maestro GitHub Action for Android | Maestro](#maestro-github-action-for-android-maestro) - [Maestro GitHub Action for iOS | Maestro](#maestro-github-action-for-ios-maestro) - [Maestro GitHub Action for Flutter | Maestro](#maestro-github-action-for-flutter-maestro) - [GitHub Actions | Maestro](#github-actions-maestro) - [Bitbucket Pipelines | Maestro](#bitbucket-pipelines-maestro) - [Bitrise | Maestro](#bitrise-maestro) - [CircleCI | Maestro](#circleci-maestro) - [Writing Your First Flow | Maestro](#writing-your-first-flow-maestro) - [Maestro Studio Desktop - Beta | Maestro](#maestro-studio-desktop-beta-maestro) - [Maestro Studio (CLI) | Maestro](#maestro-studio-cli-maestro) - [Running Flows on CI | Maestro](#running-flows-on-ci-maestro) - [Integration with any CI platform | Maestro](#integration-with-any-ci-platform-maestro) - [Pull Request Integration | Maestro](#pull-request-integration-maestro) - [Cloud Reference | Maestro](#cloud-reference-maestro) - [Build your app for the cloud | Maestro](#build-your-app-for-the-cloud-maestro) - [Configuring OS Version | Maestro](#configuring-os-version-maestro) - [Configuring device locale | Maestro](#configuring-device-locale-maestro) - [Device timezones | Maestro](#device-timezones-maestro) - [Email Notifications | Maestro](#email-notifications-maestro) - [Email Protection | Cloudflare](#email-protection-cloudflare) - [Slack Notifications | Maestro](#slack-notifications-maestro) - [Webhook Integration | Maestro](#webhook-integration-maestro) - [IP Allowlist | Maestro](#ip-allowlist-maestro) - [Managing Secrets | Maestro](#managing-secrets-maestro) - [Supported Platforms | Maestro](#supported-platforms-maestro) - [Limits | Maestro](#limits-maestro) - [Android - Views | Maestro](#android-views-maestro) - [Reusing App Binary | Maestro](#reusing-app-binary-maestro) - [Web (Desktop Browser) | Maestro](#web-desktop-browser-maestro) - [Web Views | Maestro](#web-views-maestro) - [Android - Jetpack Compose | Maestro](#android-jetpack-compose-maestro) - [Cloud | Maestro](#cloud-maestro) - [Test Output Directory | Maestro](#test-output-directory-maestro) - [Android contacts flow automation | Maestro](#android-contacts-flow-automation-maestro) - [Facebook signup flow automation | Maestro](#facebook-signup-flow-automation-maestro) - [iOS - UIKit | Maestro](#ios-uikit-maestro) - [iOS - SwiftUI | Maestro](#ios-swiftui-maestro) - [Continuous Mode | Maestro](#continuous-mode-maestro) - [Start Device | Maestro](#start-device-maestro) - [View Hierarchy | Maestro](#view-hierarchy-maestro) - [React Native Support | Maestro](#react-native-support-maestro) - [Record Your Flow | Maestro](#record-your-flow-maestro) - [Page Object Model | Maestro](#page-object-model-maestro) - [Tags | Maestro](#tags-maestro) - [Advanced: Wikipedia Android | Maestro](#advanced-wikipedia-android-maestro) - [Test Suites & Reports | Maestro](#test-suites-reports-maestro) - [Flutter | Maestro](#flutter-maestro) - [Common command arguments | Maestro](#common-command-arguments-maestro) - [Configure Maestro Driver Timeout for Reliable Tests | Maestro](#configure-maestro-driver-timeout-for-reliable-tests-maestro) - [Loops | Maestro](#loops-maestro) - [Nested Flows | Maestro](#nested-flows-maestro) - [Contributions | Maestro](#contributions-maestro) - [Detect Maestro in your app | Maestro](#detect-maestro-in-your-app-maestro) - [Configuration | Maestro](#configuration-maestro) - [Maestro Hooks: onFlowStart and onFlowComplete | Maestro](#maestro-hooks-onflowstart-and-onflowcomplete-maestro) - [Rollback Maestro | Maestro](#rollback-maestro-maestro) - [Bug Report | Maestro](#bug-report-maestro) - [Get the last matching element | Maestro](#get-the-last-matching-element-maestro) - [Clean a device | Maestro](#clean-a-device-maestro) - [AI configuration | Maestro](#ai-configuration-maestro) - [Wait Commands in Maestro for Reliable Tests | Maestro](#wait-commands-in-maestro-for-reliable-tests-maestro) - [Arranging your repository for Maestro tests | Maestro](#arranging-your-repository-for-maestro-tests-maestro) - [Case Studies | Maestro](#case-studies-maestro) - [Conditions | Maestro](#conditions-maestro) - [Access Element Text in Maestro JavaScript | Maestro](#access-element-text-in-maestro-javascript-maestro) - [Flow configuration | Maestro](#flow-configuration-maestro) - [Specify a Device | Maestro](#specify-a-device-maestro) - [Articles & Tutorials | Maestro](#articles-tutorials-maestro) - [Downloading and opening a file | Maestro](#downloading-and-opening-a-file-maestro) - [Selectors | Maestro](#selectors-maestro) - [Checking clipboard contents | Maestro](#checking-clipboard-contents-maestro) - [Using JavaScript in Maestro | Maestro](#using-javascript-in-maestro-maestro) - [Parameters & Constants | Maestro](#parameters-constants-maestro) - [Debug Output | Maestro](#debug-output-maestro) - [Logging | Maestro](#logging-maestro) - [Recipes | Maestro](#recipes-maestro) - [Choosing images from the gallery | Maestro](#choosing-images-from-the-gallery-maestro) - [Permissions Setup for iOS and Android Apps | Maestro](#permissions-setup-for-ios-and-android-apps-maestro) - [Outputs | Maestro](#outputs-maestro) - [Frequently Asked Questions | Maestro](#frequently-asked-questions-maestro) - [Commands | Maestro](#commands-maestro) - [Generating Random Data | Maestro](#generating-random-data-maestro) - [scrollUntilVisible for fragments | Maestro](#scrolluntilvisible-for-fragments-maestro) - [addMedia | Maestro](#addmedia-maestro) - [Make HTTP requests | Maestro](#make-http-requests-maestro) - [Known Issues | Maestro](#known-issues-maestro) - [GraalJS Support in Maestro Scripts | Maestro](#graaljs-support-in-maestro-scripts-maestro) - [back | Maestro](#back-maestro) - [assertTrue | Maestro](#asserttrue-maestro) - [assertVisible | Maestro](#assertvisible-maestro) - [hideKeyboard | Maestro](#hidekeyboard-maestro) - [Run JavaScript in Maestro Flows | Maestro](#run-javascript-in-maestro-flows-maestro) - [extendedWaitUntil | Maestro](#extendedwaituntil-maestro) - [clearState | Maestro](#clearstate-maestro) - [clearKeychain | Maestro](#clearkeychain-maestro) - [setAirplaneMode | Maestro](#setairplanemode-maestro) - [runScript | Maestro](#runscript-maestro) - [assertWithAI | Maestro](#assertwithai-maestro) - [Test in different locales | Maestro](#test-in-different-locales-maestro) - [assertNoDefectsWithAi | Maestro](#assertnodefectswithai-maestro) - [assertNotVisible | Maestro](#assertnotvisible-maestro) - [openLink | Maestro](#openlink-maestro) - [setOrientation | Maestro](#setorientation-maestro) - [copyTextFrom | Maestro](#copytextfrom-maestro) - [evalScript | Maestro](#evalscript-maestro) - [pressKey | Maestro](#presskey-maestro) - [killApp | Maestro](#killapp-maestro) - [eraseText | Maestro](#erasetext-maestro) - [Workspace configuration | Maestro](#workspace-configuration-maestro) - [startRecording | Maestro](#startrecording-maestro) - [takeScreenshot | Maestro](#takescreenshot-maestro) - [scroll | Maestro](#scroll-maestro) - [doubleTapOn | Maestro](#doubletapon-maestro) - [toggleAirplaneMode | Maestro](#toggleairplanemode-maestro) - [pasteText | Maestro](#pastetext-maestro) - [swipe | Maestro](#swipe-maestro) - [waitForAnimationToEnd | Maestro](#waitforanimationtoend-maestro) - [stopRecording | Maestro](#stoprecording-maestro) - [retry | Maestro](#retry-maestro) - [extractTextWithAI | Maestro](#extracttextwithai-maestro) - [scrollUntilVisible | Maestro](#scrolluntilvisible-maestro) - [setLocation | Maestro](#setlocation-maestro) - [stopApp | Maestro](#stopapp-maestro) - [travel | Maestro](#travel-maestro) - [repeat | Maestro](#repeat-maestro) - [longPressOn | Maestro](#longpresson-maestro) - [launchApp | Maestro](#launchapp-maestro) - [runFlow | Maestro](#runflow-maestro) - [tapOn | Maestro](#tapon-maestro) --- # inputText | Maestro Inputs text (regardless of whether any text field is currently focused or not) Copy - inputText: "Hello World" Unfortunately unicode characters are not supported yet in Android platform. Follow the [GitHub issue](https://github.com/mobile-dev-inc/maestro/issues/146) for status updates. ### [](https://docs.maestro.dev/api-reference/commands/inputtext#input-random-text) Input random text There are several convenience methods for entering a random text input: Copy - inputRandomEmail # Enters a random Email address - inputRandomPersonName # Enters a random person name - inputRandomNumber # Enters a random integer number - inputRandomText # Enters random unstructured text - inputRandomCityName # Enters a random city name, worldwide - inputRandomCountryName # Enters the name of a random country - inputRandomColorName # Enters a random colour. Might be multiple words. Note: Since Maestro v2.0, the implementation behind the random commands was changed to use [DataFaker](https://www.datafaker.net/) , which gives a much wider spread of random data than was available in Maestro v1.x. #### [](https://docs.maestro.dev/api-reference/commands/inputtext#length) Length You can pass length as argument for `Number` and `Text` Copy - inputRandomNumber: length: 10 #(default: 8) - inputRandomText: length: 10 #(default: 8) #### [](https://docs.maestro.dev/api-reference/commands/inputtext#re-using-random-input) Re-using random input To access and re-use your random input, you can use the [copyTextFrom](https://docs.maestro.dev/api-reference/commands/copytextfrom) function, as shown in the example below. [PrevioushideKeyboard](https://docs.maestro.dev/api-reference/commands/hidekeyboard) [NextkillApp](https://docs.maestro.dev/api-reference/commands/killapp) Last updated 4 months ago Was this helpful? Was this helpful? Copy - tapOn: id: MyTextInput - inputRandomText - copyTextFrom: id: MyTextInput - tapOn: 'Submit' # Assumes a form where the input will be displayed on the next screen - assertVisible: ${maestro.copiedText} # or with regex - assertVisible: ${'.*' + maestro.copiedText + '$'} # or tapOn - tapOn: ${maestro.copiedText} --- # Maestro Documentation | Maestro πŸš€ **Running in the Cloud** Ready to wire into CI or scale up your testing? Start running your flows on Maestro's enterprise-grade cloud infrastructure: [Run Maestro tests in the Cloud](https://maestro.dev/cloud) and follow the [Quickstart Guide](https://docs.maestro.dev/cloud/cloud-quickstart) to quickly experience the power of Cloud. [](https://docs.maestro.dev/#why-maestro) Why Maestro? ----------------------------------------------------------- Maestro is built on learnings from its predecessors (Appium, Espresso, UIAutomator, XCTest, Selenium, Playwright) and allows you to easily define and test your Flows. **What are Flows?** Think of Flows as parts of the user journey in your app. Login, Checkout and Add to Cart are three examples of possible Flows that can be defined and tested using Maestro. * Built-in tolerance to flakiness. UI elements will not always be where you expect them, screen tap will not always go through, etc. Maestro embraces the instability of mobile applications and devices and tries to counter it. * Built-in tolerance to delays. No need to pepper your tests with `sleep()` calls. Maestro knows that it might take time to load the content (i.e. over the network) and automatically waits for it (but no longer than required). * Blazingly fast iteration. Tests are interpreted, no need to compile anything. Maestro is able to continuously monitor your test files and rerun them as they change. * Declarative yet powerful syntax. Define your tests in a `yaml` file. * Simple setup. Maestro is a single binary that works anywhere. [](https://docs.maestro.dev/#examples) Examples ---------------------------------------------------- #### [](https://docs.maestro.dev/#twitter-mobile) Twitter (Mobile) ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-21170ddb991b54aac54042fe34b89711750c0c0f%252Ftwitter_continuous_v3_fast.gif%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=aace3304&sv=2) #### [](https://docs.maestro.dev/#simple-examples) Simple Examples Android iOS Web [](https://docs.maestro.dev/#platform-support) Platform Support -------------------------------------------------------------------- Platform Supported [Android - Views](https://docs.maestro.dev/platform-support/android-views) βœ… [Android - Jetpack Compose](https://docs.maestro.dev/platform-support/android-jetpack-compose) βœ… [iOS - UIKit](https://docs.maestro.dev/platform-support/ios-uikit) βœ… [iOS - SwiftUI](https://docs.maestro.dev/platform-support/ios-swiftui) βœ… [React Native](https://docs.maestro.dev/platform-support/react-native) βœ… [Flutter](https://docs.maestro.dev/platform-support/flutter) βœ… [Web Views](https://docs.maestro.dev/platform-support/web-views) βœ… [Web (Desktop Browser)](https://docs.maestro.dev/platform-support/web-desktop-browser) βœ… .NET MAUI iOS βœ… .NET MAUI Android βœ… [](https://docs.maestro.dev/#resources) Resources ------------------------------------------------------ * Blog Post: [**Introducing: Maestro β€” Painless Mobile UI Automation**](https://maestro.dev/blog/introducing-maestro-painless-mobile-ui-automation) * GitHub Repository: [**https://github.com/mobile-dev-inc/maestro**](https://github.com/mobile-dev-inc/maestro) * Public Slack Channel: [**Join the workspace**](https://slack.maestro.dev/) [](https://docs.maestro.dev/#get-started) Get Started ---------------------------------------------------------- Get started by installing the Maestro CLI: [NextInstalling Maestro](https://docs.maestro.dev/getting-started/installing-maestro) Last updated 2 months ago Was this helpful? * [Why Maestro?](https://docs.maestro.dev/#why-maestro) * [Examples](https://docs.maestro.dev/#examples) * [Platform Support](https://docs.maestro.dev/#platform-support) * [Resources](https://docs.maestro.dev/#resources) * [Get Started](https://docs.maestro.dev/#get-started) Was this helpful? Copy # flow_contacts_android.yaml appId: com.android.contacts --- - launchApp - tapOn: "Create new contact" - tapOn: "First Name" - inputText: "John" - tapOn: "Last Name" - inputText: "Snow" - tapOn: "Save" Copy # flow_contacts_ios.yaml appId: com.apple.MobileAddressBook --- - launchApp - tapOn: "John Appleseed" - tapOn: "Edit" - tapOn: "Add phone" - inputText: "123123" - tapOn: "Done" Copy url: https://example.com --- - launchApp - tapOn: More information... - assertVisible: Further Reading --- # macOS | Maestro Dependencies: * **Java 17 or higher** - You can verify your Java version with `java -version`. If you need to install Java: * Install via Homebrew: `brew install openjdk@17` * Or download from [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) or [OpenJDK](https://openjdk.org/install/) * Or use [SDKMAN!](https://sdkman.io/) for version management (see our [video guide](https://www.youtube.com/watch?v=yR7BGMjK0vM) ) * [Xcode](https://developer.apple.com/xcode/) (recommended version is 14 or higher) Please make sure that Command Line Tools are installed (Xcode -> Preferences -> Locations -> Command Line Tools) After setting up the macOS dependencies above, follow the default installation instructions: [Installing Maestro](https://docs.maestro.dev/getting-started/installing-maestro) [PreviousInstalling Maestro](https://docs.maestro.dev/getting-started/installing-maestro) [NextWindows](https://docs.maestro.dev/getting-started/installing-maestro/windows) Last updated 4 months ago Was this helpful? Was this helpful? --- # Build and Install your App | Maestro Currently maestro supports emulator and device builds for Android (**.apk**) and iOS Simulator (**.app**). Maestro will work with any app, but our experience has been: * If you want to build the confidence to ship your app, test the app that's most production-like * If you want better performance, don't use debug builds - Maestro inherently needs to be chatty, and this can be slower on debug builds. More details on how to build an app for Maestro are in the following platform sections: [PreviousLinux](https://docs.maestro.dev/getting-started/installing-maestro/linux) [NextAndroid](https://docs.maestro.dev/getting-started/build-and-install-your-app/android) Last updated 8 months ago Was this helpful? Was this helpful? --- # Linux | Maestro [](https://docs.maestro.dev/getting-started/installing-maestro/linux#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------ Maestro requires **Java 17 or higher**. You can verify your Java version with: Copy java -version [](https://docs.maestro.dev/getting-started/installing-maestro/linux#installation) Installation ---------------------------------------------------------------------------------------------------- Follow the default install instructions [Installing Maestro](https://docs.maestro.dev/getting-started/installing-maestro) [PreviousWindows](https://docs.maestro.dev/getting-started/installing-maestro/windows) [NextBuild and Install your App](https://docs.maestro.dev/getting-started/build-and-install-your-app) Last updated 4 months ago Was this helpful? * [Prerequisites](https://docs.maestro.dev/getting-started/installing-maestro/linux#prerequisites) * [Installation](https://docs.maestro.dev/getting-started/installing-maestro/linux#installation) Was this helpful? --- # Installing Maestro | Maestro [](https://docs.maestro.dev/getting-started/installing-maestro#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------ Maestro requires **Java 17 or higher** to be installed on your system. You can verify your Java version by running: Copy java -version If you don't have Java 17 or higher installed, you can download it from: * [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) * [OpenJDK](https://openjdk.org/install/) * Or use a version manager like [SDKMAN!](https://sdkman.io/) [](https://docs.maestro.dev/getting-started/installing-maestro#installing-the-cli) Installing the CLI ---------------------------------------------------------------------------------------------------------- **Using Windows?** Follow this guide to get set up on a Windows machine: [Installing Maestro on Windows](https://docs.maestro.dev/getting-started/installing-maestro/windows) Run the following command to install Maestro on macOS, Linux or Windows (WSL): Copy curl -fsSL "https://get.maestro.mobile.dev" | bash If you're on macOS, you can use Homebrew instead of the install script above: Copy brew tap mobile-dev-inc/tap brew install mobile-dev-inc/tap/maestro [](https://docs.maestro.dev/getting-started/installing-maestro#upgrading-the-cli) Upgrading the CLI -------------------------------------------------------------------------------------------------------- Simply run the installation script again: [](https://docs.maestro.dev/getting-started/installing-maestro#installing-a-specific-version-of-maestro) Installing a specific version of Maestro ------------------------------------------------------------------------------------------------------------------------------------------------------ To install a specific version, export the `MAESTRO_VERSION` environment variable and run the same installation command as before: [See the list of available versions](https://github.com/mobile-dev-inc/maestro/releases) . [](https://docs.maestro.dev/getting-started/installing-maestro#installing-a-specific-version-of-maestro-in-a-dockerfile) Installing a specific version of Maestro in a Dockerfile -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Define a variable for the version you want to install: Then download Maestro and add it to your path: [](https://docs.maestro.dev/getting-started/installing-maestro#connecting-to-your-device) Connecting to Your Device ------------------------------------------------------------------------------------------------------------------------ `maestro test` will automatically detect and use any local emulator or USB-connected physical device. _Note: At the moment, Maestro does not support physical iOS devices_ [PreviousMaestro Documentation](https://docs.maestro.dev/) [NextmacOS](https://docs.maestro.dev/getting-started/installing-maestro/macos) Last updated 5 days ago Was this helpful? * [Prerequisites](https://docs.maestro.dev/getting-started/installing-maestro#prerequisites) * [Installing the CLI](https://docs.maestro.dev/getting-started/installing-maestro#installing-the-cli) * [Upgrading the CLI](https://docs.maestro.dev/getting-started/installing-maestro#upgrading-the-cli) * [Installing a specific version of Maestro](https://docs.maestro.dev/getting-started/installing-maestro#installing-a-specific-version-of-maestro) * [Installing a specific version of Maestro in a Dockerfile](https://docs.maestro.dev/getting-started/installing-maestro#installing-a-specific-version-of-maestro-in-a-dockerfile) * [Connecting to Your Device](https://docs.maestro.dev/getting-started/installing-maestro#connecting-to-your-device) Was this helpful? Copy curl -fsSL "https://get.maestro.mobile.dev" | bash Copy export MAESTRO_VERSION={version}; curl -Ls "https://get.maestro.mobile.dev" | bash Copy ENV MAESTRO_VERSION {version} Copy RUN mkdir -p /opt/maestro && \ wget -q -O /tmp/${MAESTRO_VERSION} "https://github.com/mobile-dev-inc/maestro/releases/download/cli-${MAESTRO_VERSION}/maestro.zip" && \ unzip -q /tmp/${MAESTRO_VERSION} -d /opt/ && \ rm /tmp/${MAESTRO_VERSION} ENV PATH=/opt/maestro/bin:${PATH} --- # Android | Maestro This assumes you've got the Android SDK bits already installed. If you haven't, and especially if you happen to be using a Mac, this video will take you all the way from zero, through the prerequisites, to a running emulator. Maestro works with most apps, but there are a few requirements: * APK (AAB not supported) * Compatible with x86\_64 architecture * Requires Android API level 26 or newer * Release and Debug builds both supported (although Release builds are often better) [](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#building-with-gradle) Building with Gradle ------------------------------------------------------------------------------------------------------------------------------ Build your app using one of the commands below. Then find the appropriate APK file in the `build/outputs/apk/` output directory. [](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#building-with-flutter) Building with Flutter -------------------------------------------------------------------------------------------------------------------------------- If you use Flutter to build your app, you can create a build using the following command: You can then find the built APK in the build/app/outputs/ folder. [](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#building-with-other-frameworks) Building with Other Frameworks -------------------------------------------------------------------------------------------------------------------------------------------------- We're not going to attempt to cover all the possible ways you could build an app. React Native and Expo both have their standard ways (and, like Gradle, can be customized by the developers to follow any pattern that suits the team). Some rather refined developers might even provide a makefile. [](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#running-on-an-emulator) Running on an Emulator ---------------------------------------------------------------------------------------------------------------------------------- If you've not already got an emulator running, start one now. You can do that with the Android SDK tools, through Android Studio, or via Maestro's [Start Device](https://docs.maestro.dev/cli/start-device) command. Once that's done, you can either drag and drop the APK onto the running emulator, or run: [PreviousBuild and Install your App](https://docs.maestro.dev/getting-started/build-and-install-your-app) [NextiOS](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios) Last updated 1 month ago Was this helpful? * [Building with Gradle](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#building-with-gradle) * [Building with Flutter](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#building-with-flutter) * [Building with Other Frameworks](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#building-with-other-frameworks) * [Running on an Emulator](https://docs.maestro.dev/getting-started/build-and-install-your-app/android#running-on-an-emulator) Was this helpful? Copy # Release build ./gradlew assembleRelease # Debug build ./gradlew assembleDebug Copy # Release build flutter build apk # Debug build flutter build apk --debug Copy adb install /path/to/app.apk --- # Windows | Maestro **Prerequisites:** Maestro requires **Java 17 or higher**. You can verify your Java version with `java -version`. [](https://docs.maestro.dev/getting-started/installing-maestro/windows#option-1-installation-on-windows) Option 1: Installation on Windows ----------------------------------------------------------------------------------------------------------------------------------------------- 1 **Download the latest Maestro Release** [https://github.com/mobile-dev-inc/maestro/releases/latest/download/maestro.zipgithub.com](https://github.com/mobile-dev-inc/maestro/releases/latest/download/maestro.zip) 2 **Extract the Maestro zip** Extract the zip file you downloaded in the previous step to any location. For instance: Copy C:\Users\jake\maestro 3 **Update your PATH environment variable** Update your PATH environment variable to include the `maestro\bin` folder. You may need to restart your terminal for this to take effect. Copy setx PATH "%PATH%;C:\Users\jake\maestro\bin" 4 **Connect to a device** `maestro test` will automatically detect and use any local emulator or USB-connected physical device. [](https://docs.maestro.dev/getting-started/installing-maestro/windows#option-2-installation-in-wsl2) Option 2: Installation in WSL2 ----------------------------------------------------------------------------------------------------------------------------------------- If you prefer WSL2 for your working environment, this section will walk you through the end-to-end steps for getting started with Maestro on a Windows machine. Note: It's more involved than installing Maestro on Windows directly, and requires passing additional configuration at runtime too. ### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#pre-requisites) Pre-Requisites 1. PowerShell is installed in your Windows system. 2. Install Android Studio on your Windows machine. 3. Add ANDROID\_HOME to your Windows environment variable. 1. To check if your ANDROID\_HOME setup is correctly done, open a PowerShell terminal and run this command `adb --version.` 2. Note down the ADB version. 4. Install Java JDK 17 or higher and set JAVA\_HOME 1. Run `java -version` to check if Java 17+ is installed correctly. ### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#steps) Steps 1. Install WSL2 (Window Subsystem for Linux) 2. Install Java 17 or higher 3. Install Maestro #### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#id-1.-install-wsl-2) 1\. Install WSL 2 With recent Windows 11, Microsoft has made it pretty easy to install Windows Subsystem for Linux, aka WSL. In order to install WSL, open PowerShell as administrator and run the following command: After running the above command, follow through instructions and restart the computer. Install [Windows Terminal](https://github.com/microsoft/terminal) application for refreshing terminal experience. Set your Linux username and password (Something that you will not forget). Run the following two commands to update your Ubuntu system. Enter password when prompted. #### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#id-2.-install-java) 2\. Install Java After restarting the system, open the Terminal application and click on the dropdown to select Ubuntu. Install Java 17 or higher with the following command: Alternatively, you can install a newer version like Java 21: #### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#id-3.-install-maestro) 3\. Install Maestro Installing Maestro is now just a matter of running following one command. **Tada! πŸŽ‰** **You have successfully installed Maestro on your Windows machine** πŸ™Œ Check your Maestro version using the following command: ### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#whats-next) What's Next? #### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#lets-set-you-up-to-use-android-in-your-freshly-installed-wsl2) Let's set you up to use Android in your freshly installed WSL2 * Download the Android command line tools zip file from [Android official site.](https://developer.android.com/studio) * Use the following instructions to set up Android command lines correctly in your WSL2. * Open WSL2 terminal. * Create a new directory in your home directory. * Unzip the Android command line tools zip file in the `android` directory using this command: `unzip ~.zip` * In the `Android` directory perform following actions. **Note:** Last command will probably give you a warning, but you don’t need the worry about that. * Now add the following line to your `~/.bashrc file` * Save your `~/.bashrc` file and exit. * Run `source ~/.bashrc` to reload the bashrc file. * Now, we will install basic Android utilities using the following commands: * Run `sdkmanager --list` to check if everything is working fine. * Run `sdkmanager --install "platform-tools"` to install platform tools. * Finally, add the following into your `~/.bashrc` file * `export PATH=$PATH:$ANDROID_HOME/platform-tools` * Save your `~/.bashrc` file and exit. * Run `source ~/.bashrc` to reload the bashrc file. * To check that everything went well, do the following: * Close and relaunch terminal * Run `adb --version` and see that adb version is shown * Since everything is installed fresh, your WSL 2 adb version should perfectly match with Windows ADB version that we noted down as part of the pre-requisites. Please follow the below steps to setup the ADB and make sure you are able to use Android emulators with your WSL2 correctly: * Launch your Android emulator on Windows. * Once the Android emulator is up and running, open a PowerShell prompt. * Run this command in PowerShell * This will start the adb server in the Windows host. * Note down the IPV4 address of your Windows host PC/machine. TROUBLESHOOTING: * Sometimes you may get `smartsockets..` error when you run `adb -a -P 5037 nodaemon server` command in PowerShell. In that case, you can do the following steps: * Open task manager and kill all `adb` related processes. * If Android Studio is open, close it and **keep only** emulator running. * If you see a message saying `emulator offline`, **ignore it**. * Sometimes, the firewall stops your connection with the host machine. For that, add a firewall rule to allow the connection or check with your organization system admin if using a company machine. * **Note: Don't close the PowerShell terminal!** * Now open your WSL2 terminal and run these commands: * `adb kill-server` * `export ADB_SERVER_SOCKET=tcp::5037` * `adb devices` * `You should see your connected emulator successfully now.` #### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#ready-to-start-using-maestro) Ready to start Using Maestro? Yes, at this point, you are free to start your automation. * [Write your first flow](https://docs.maestro.dev/getting-started/writing-your-first-flow) * How to run **Maestro commands**? * You can run Maestro commands in WSL2 terminal with `--host` flag. eg. * _**maestro --host test flow.yaml**_ * _**maestro --host studio**_ * Check out the [full documentation](https://docs.maestro.dev/) ### [](https://docs.maestro.dev/getting-started/installing-maestro/windows#known-issues) Known Issues * If your Android emulator is not up and running in the Windows host, the Maestro test command fails to find the installed emulator. At this point, it is recommended that you fire up your emulator before running the flow using Maestro. [PreviousmacOS](https://docs.maestro.dev/getting-started/installing-maestro/macos) [NextLinux](https://docs.maestro.dev/getting-started/installing-maestro/linux) Last updated 4 months ago Was this helpful? * [Option 1: Installation on Windows](https://docs.maestro.dev/getting-started/installing-maestro/windows#option-1-installation-on-windows) * [Option 2: Installation in WSL2](https://docs.maestro.dev/getting-started/installing-maestro/windows#option-2-installation-in-wsl2) * [Pre-Requisites](https://docs.maestro.dev/getting-started/installing-maestro/windows#pre-requisites) * [Steps](https://docs.maestro.dev/getting-started/installing-maestro/windows#steps) * [What's Next?](https://docs.maestro.dev/getting-started/installing-maestro/windows#whats-next) * [Known Issues](https://docs.maestro.dev/getting-started/installing-maestro/windows#known-issues) Was this helpful? Copy wsl --install Copy sudo apt update sudo apt upgrade Copy sudo apt install openjdk-17-jdk Copy sudo apt install openjdk-21-jdk Copy curl -Ls "https://get.maestro.mobile.dev" | bash Copy maestro --version Copy ~ $ mkdir Android ~ $ cd Android Copy $ mkdir latest $ mv cmdline-tools/* latest/ $ mv latest/ cmdline-tools/ Copy export ANDROID_HOME=$HOME/Android export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin Copy adb -a -P 5037 nodaemon server --- # Run a Sample Flow | Maestro If you want to get started writing your own Flow right away, skip ahead to the [**next section**](https://docs.maestro.dev/getting-started/writing-your-first-flow) . ### [](https://docs.maestro.dev/getting-started/run-a-sample-flow#download-the-samples) Download the Samples Use the download-samples command to download the samples: Copy maestro download-samples This will download the build-in sample Flows and app into a `samples/` folder in your current directory. ### [](https://docs.maestro.dev/getting-started/run-a-sample-flow#run-the-sample-flow) Run the Sample Flow Install the sample app and then run the associated Flow using the `maestro test` command. iOS Android Copy cd ./samples unzip sample.zip xcrun simctl install Booted Wikipedia.app maestro test ios-flow.yaml Copy cd ./samples adb install sample.apk maestro test android-flow.yaml [PreviousiOS](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios) [NextWriting Your First Flow](https://docs.maestro.dev/getting-started/writing-your-first-flow) Last updated 1 year ago Was this helpful? * [Download the Samples](https://docs.maestro.dev/getting-started/run-a-sample-flow#download-the-samples) * [Run the Sample Flow](https://docs.maestro.dev/getting-started/run-a-sample-flow#run-the-sample-flow) Was this helpful? --- # iOS | Maestro This all assumes you've got Xcode plus Simulator runtimes installed. If you haven't, and want to know how, we've made a video walkthrough: [](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-xcode) Building with Xcode ------------------------------------------------------------------------------------------------------------------------ Maestro currently supports iOS Simulator builds (**.app**), AppStore distribution device builds (**.ipa**) are not currently supported. The easiest way to get an app installed on the simulator is by building and running it from Xcode (make sure that simulator target is selected): ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-1cd5bd52b6d65d3ae7ffbaae05f84e40a7fc4145%252FScreenshot%25202023-02-15%2520at%252013.46.55.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=7b9777d8&sv=2) [](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#default-build-location) Default build location ------------------------------------------------------------------------------------------------------------------------------ If you want to install the .app manually, the file can be found under the Products folder at Xcode Menu: **Product -> Show Build Folder in Finder -> Then go to path Products/Debug-iphonesimulator** The .app file can then be installed on the simulator by simple dragging and dropping the file or via Xcode command line tools by running: [](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-xcode-command-line-tools) Building with Xcode command line tools -------------------------------------------------------------------------------------------------------------------------------------------------------------- To build an app with Xcode command line tools **xcrun xcodebuild** should be used. Here is an example on how to build [Food Truck](https://github.com/apple/sample-food-truck) app for iOS simulator target: The .app file can be then found under **/build** folder [](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-fastlane) Building with Fastlane ------------------------------------------------------------------------------------------------------------------------------ If you use [fastlane](https://fastlane.tools/) for your automation pipelines the script should look the following way: [](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-flutter) Building with Flutter ---------------------------------------------------------------------------------------------------------------------------- If you use Flutter to build your app you can create a debug build for simulators using the following command: You can then find your app file in the `build/ios/iphonesimulator/` directory. [](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#running-on-a-simulator) Running on a Simulator ------------------------------------------------------------------------------------------------------------------------------ Once you've got your .app file, installing it should be as simple as dragging and dropping it onto the running Simulator. [PreviousAndroid](https://docs.maestro.dev/getting-started/build-and-install-your-app/android) [NextRun a Sample Flow](https://docs.maestro.dev/getting-started/run-a-sample-flow) Last updated 9 months ago Was this helpful? * [Building with Xcode](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-xcode) * [Default build location](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#default-build-location) * [Building with Xcode command line tools](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-xcode-command-line-tools) * [Building with Fastlane](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-fastlane) * [Building with Flutter](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#building-with-flutter) * [Running on a Simulator](https://docs.maestro.dev/getting-started/build-and-install-your-app/ios#running-on-a-simulator) Was this helpful? Copy xcrun simctl install $DEVICE_UDID /path/to/your/app Copy xcrun xcodebuild -scheme 'Food Truck' \ -project 'Food Truck.xcodeproj' \ -configuration Debug \ -sdk 'iphonesimulator' \ -destination 'generic/platform=iOS Simulator' \ -derivedDataPath \ build Copy xcodebuild( configuration: build_config[:configuration], scheme: build_config[:scheme], workspace: build_config[:xcode_workspace], xcargs: "-quiet -sdk 'iphonesimulator' -destination 'generic/platform=iOS Simulator'", derivedDataPath: IOS_DERIVED_DATA_PATH # this will contain the .app which we need later on ) Copy flutter build ios --debug --simulator --- # Maestro MCP | Maestro [](https://docs.maestro.dev/getting-started/maestro-mcp#model-context-protocol-mcp) Model Context Protocol (MCP) --------------------------------------------------------------------------------------------------------------------- Maestro supports the [MCP protocol](https://modelcontextprotocol.io/) , which allows it to be used directly by any MCP Client tools (such as Claude, Cursor or Windsurf). ### [](https://docs.maestro.dev/getting-started/maestro-mcp#what-is-mcp) What is MCP? Model Context Protocol (MCP) is a standardized protocol that bridges AI models with various data sources and tools. Think of it as the "USB-C for AI" β€” a universal connector that enables seamless communication between large language models (LLMs) and the resources they need. #### [](https://docs.maestro.dev/getting-started/maestro-mcp#why-mcp-matters) Why MCP Matters MCP solves three critical challenges in AI integration: 1. **Universal Connectivity**: Provides a single protocol for connecting AI systems to diverse data sources and tools 2. **Vendor Independence**: Allows easy switching between different LLM providers without changing integrations 3. **Secure Access**: Implements best practices for safely accessing data within organizational boundaries #### [](https://docs.maestro.dev/getting-started/maestro-mcp#how-mcp-works) How MCP Works MCP uses a simple but powerful architecture: * **MCP Hosts**: Applications (like IDEs or AI assistants) that need access to data through MCP * **MCP Clients**: Protocol handlers that connect hosts to servers * **MCP Servers**: Specialized programs that expose capabilities through the standardized protocol * **Data Sources**: Local files, databases, and services that MCP can securely access * **External Services**: Remote systems (APIs, etc.) that MCP servers can connect to ### [](https://docs.maestro.dev/getting-started/maestro-mcp#installing-maestro-mcp) Installing Maestro MCP The MCP command comes pre-installed as part of the Maestro CLI - you can run it with `maestro mcp` ### [](https://docs.maestro.dev/getting-started/maestro-mcp#configuring-your-mcp-client) Configuring your MCP Client Configuration varies depending on the MCP Client you are using. #### [](https://docs.maestro.dev/getting-started/maestro-mcp#claude-desktop) Claude Desktop For Claude, you can follow the instructions in the [Claude documentation](https://modelcontextprotocol.io/quickstart/user) . The configuration file is typically located at `~/Library/Application Support/Claude/claude_desktop_config.json` on OSX or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Add the following configuration to the file and restart Claude: Replace `maestro` with the full path of your maestro cli, if not on path. Other clients have similar configuration files and the installation processs may vary. Please follow their specific installation instructions: * [Windsurf](https://docs.windsurf.com/windsurf/mcp#adding-a-new-server) * [Cursor](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) * [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) * [JetBrains IDEs](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) [](https://docs.maestro.dev/getting-started/maestro-mcp#what-does-this-look-like) What does this look like? ---------------------------------------------------------------------------------------------------------------- [PreviousRunning Flows on CI](https://docs.maestro.dev/getting-started/running-flows-on-ci) [NextRun Maestro tests in the cloud](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud) Last updated 6 months ago Was this helpful? * [Model Context Protocol (MCP)](https://docs.maestro.dev/getting-started/maestro-mcp#model-context-protocol-mcp) * [What is MCP?](https://docs.maestro.dev/getting-started/maestro-mcp#what-is-mcp) * [Installing Maestro MCP](https://docs.maestro.dev/getting-started/maestro-mcp#installing-maestro-mcp) * [Configuring your MCP Client](https://docs.maestro.dev/getting-started/maestro-mcp#configuring-your-mcp-client) * [What does this look like?](https://docs.maestro.dev/getting-started/maestro-mcp#what-does-this-look-like) Was this helpful? Copy { "mcpServers": { "maestro": { "command": "maestro", "args": [\ "mcp"\ ] } } } --- # Cloud Quickstart | Maestro Before wiring into CI, we recommend uploading a local build from your terminal to see the process working end-to-end. These steps should take you less than 5 minutes. [](https://docs.maestro.dev/cloud/cloud-quickstart#id-1.-install-the-maestro-cli) 1\. Install the Maestro CLI ------------------------------------------------------------------------------------------------------------------ We'll be using the `maestro cloud` command below to run your flows in the cloud, so start by [**installing the Maestro CLI**](https://docs.maestro.dev/getting-started/installing-maestro) if you haven't already: Copy curl -Ls "https://get.maestro.mobile.dev" | bash [](https://docs.maestro.dev/cloud/cloud-quickstart#id-2.-download-the-samples) 2\. Download the Samples ------------------------------------------------------------------------------------------------------------ Use the download-samples command to download a sample app and Flow file: Copy maestro download-samples You can of course choose to upload your own app and Flow file, but we recommend using the samples first to see how it works! [](https://docs.maestro.dev/cloud/cloud-quickstart#id-3.-run-your-flow-in-the-cloud) 3\. Run your Flow in the cloud ------------------------------------------------------------------------------------------------------------------------ Use the `maestro cloud` command to run your flow in the cloud. This command works the same whether you're running it locally or in CI. #### [](https://docs.maestro.dev/cloud/cloud-quickstart#android) Android Copy cd ./samples maestro cloud sample.apk android-flow.yaml If you're a member of multiple organisation, or have multiple projects, you can optionally add `--api-key` and/or `--project-id` respectively to avoid being prompted for selection. Copy cd ./samples maestro cloud sample.apk android-flow.yaml #### [](https://docs.maestro.dev/cloud/cloud-quickstart#ios) iOS If you're a member of multiple organisation, or have multiple projects, you can optionally add `--api-key` and/or `--project-id` respectively to avoid being prompted for selection. To run any flow that depends on other files (like the **advanced** examples) you need to upload the full folder, so that Maestro has all of the files it needs. More information about subflows and what Flows to include can be found [here](https://docs.maestro.dev/cli/test-suites-and-reports#controlling-what-tests-to-include) . [](https://docs.maestro.dev/cloud/cloud-quickstart#id-4.-view-results-in-the-console) 4\. View results in the console -------------------------------------------------------------------------------------------------------------------------- A link to the Maestro console is printed out after your Flow is uploaded successfully. Click on the link to view the results of your upload. It may take a minute or so before your results are ready. [](https://docs.maestro.dev/cloud/cloud-quickstart#congrats) Congrats πŸŽ‰ ----------------------------------------------------------------------------- Congrats, you just ran your first Maestro Flow in the cloud! πŸ™Œ Now that's you've seen how this works locally, let's take a look at how this can be integrated into your CI workflows: [CI Integration](https://docs.maestro.dev/cloud/ci-integration) [PreviousRun Maestro tests in the cloud](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud) [NextCI Integration](https://docs.maestro.dev/cloud/ci-integration) Last updated 25 days ago Was this helpful? * [1\. Install the Maestro CLI](https://docs.maestro.dev/cloud/cloud-quickstart#id-1.-install-the-maestro-cli) * [2\. Download the Samples](https://docs.maestro.dev/cloud/cloud-quickstart#id-2.-download-the-samples) * [3\. Run your Flow in the cloud](https://docs.maestro.dev/cloud/cloud-quickstart#id-3.-run-your-flow-in-the-cloud) * [4\. View results in the console](https://docs.maestro.dev/cloud/cloud-quickstart#id-4.-view-results-in-the-console) * [Congrats πŸŽ‰](https://docs.maestro.dev/cloud/cloud-quickstart#congrats) Was this helpful? Copy cd ./samples maestro cloud sample.app ios-flow.yaml Copy cd ./samples maestro cloud --api-key --project-id sample.zip ios-flow.yaml --- # Run Maestro tests in the cloud | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://maestro.dev/cloud) Ship your apps with confidence by running your tests on Maestro's hosted enterprise-grade cloud infrastructure. [](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#ci-support) CI Support -------------------------------------------------------------------------------------------- You can integrate Maestro into any CI platform via the Maestro CLI, and we're in the process of building out native integrations into the most common platforms. Check out the [**CI Integration docs**](https://docs.maestro.dev/cloud/ci-integration) for details. CI Platform Support via CLI Native Integration [**GitHub Actions**](https://docs.maestro.dev/cloud/ci-integration/github-actions) βœ… βœ… [**Bitrise**](https://docs.maestro.dev/cloud/ci-integration/bitrise) βœ… βœ… [**Bitbucket**](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines) βœ… βœ… [**CircleCI**](https://docs.maestro.dev/cloud/ci-integration/circleci) βœ… βœ… [All other CI platforms](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) βœ… \- [](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#platform-support) Platform Support -------------------------------------------------------------------------------------------------------- Platform Supported [Android - Views](https://docs.maestro.dev/platform-support/android-views) βœ… [Android - Jetpack Compose](https://docs.maestro.dev/platform-support/android-jetpack-compose) βœ… [iOS - UIKit](https://docs.maestro.dev/platform-support/ios-uikit) βœ… [iOS - SwiftUI](https://docs.maestro.dev/platform-support/ios-swiftui) βœ… [React Native](https://docs.maestro.dev/platform-support/react-native) βœ… [Flutter](https://docs.maestro.dev/platform-support/flutter) βœ… [Web Views](https://docs.maestro.dev/platform-support/web-views) βœ… [Web (Desktop Browser)](https://docs.maestro.dev/platform-support/web-desktop-browser) βœ… .NET MAUI iOS βœ… .NET MAUI Android βœ… [](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#getting-started) Getting Started ------------------------------------------------------------------------------------------------------ * If you don't already a Maestro account you can [create your Maestro account here](https://signin.maestro.dev/sign-up) * Maestro cloud testing requires a Cloud Plan, so make sure to start a Cloud Plan Trial before proceeding * Check out the [Quickstart](https://docs.maestro.dev/cloud/cloud-quickstart) guide to get started with running your Maestro Flows in the cloud within minutes * Public Slack Channel: [**Join the workspace**](https://docsend.com/view/3r2sf8fvvcjxvbtk) then head to the `#cloud` channel to discuss anything related to Maestro cloud testing [](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#why-run-in-the-cloud) Why run in the cloud? ----------------------------------------------------------------------------------------------------------------- * Guaranteed Parallelism for Consistent Testing * Unlimited Maestro testing * Unlimited users * Test suite reporting * Automatic CI integration triggers [](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#we-take-security-seriously) We take security seriously ---------------------------------------------------------------------------------------------------------------------------- We are SOC 2 compliant meaning that the security and privacy of your data is our top priority\\ ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-a31e3540d6e167383e92076ccdcd8745e2054222%252F21972-312_SOC_NonCPA.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=a9835dcb&sv=2) [PreviousMaestro MCP](https://docs.maestro.dev/getting-started/maestro-mcp) [NextCloud Quickstart](https://docs.maestro.dev/cloud/cloud-quickstart) Last updated 3 months ago Was this helpful? * [CI Support](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#ci-support) * [Platform Support](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#platform-support) * [Getting Started](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#getting-started) * [Why run in the cloud?](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#why-run-in-the-cloud) * [We take security seriously](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud#we-take-security-seriously) Was this helpful? --- # CI Integration | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) There are two main ways to integrate Maestro cloud testing into your CI workflow: * Option 1: Install the Maestro CLI and use the `maestro cloud` command * Option 2: Use Maestro's native CI integration (if it exists for your CI platform) Follow the link below for your CI platform to learn how to start running your Flows in CI! CI Platform Integration **GitHub Actions** Use the [Maestro Cloud GitHub Action](https://docs.maestro.dev/cloud/ci-integration/github-actions) **Bitrise** Use the [Maestro Cloud Bitrise step](https://docs.maestro.dev/cloud/ci-integration/bitrise) **Bitbucket Pipelines** Use the [Maestro Cloud Upload Pipe](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines) **CircleCI** Use the [Maestro Cloud Upload Job](https://docs.maestro.dev/cloud/ci-integration/circleci) **GitLab CI/CD** [Use the Maestro CLI](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) **TravisCI** [Use the Maestro CLI](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) **Jenkins** [Use the Maestro CLI](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) All other CI platforms [Use the Maestro CLI](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) [PreviousCloud Quickstart](https://docs.maestro.dev/cloud/cloud-quickstart) [NextGitHub Actions](https://docs.maestro.dev/cloud/ci-integration/github-actions) Last updated 7 months ago Was this helpful? Was this helpful? --- # Maestro GitHub Action for Android | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android#full-example) Full Example --------------------------------------------------------------------------------------------------------------------------------- Copy name: Build and run Maestro tests (Native Android) on: push: branches: [ main ] pull_request: branches: [ main ] jobs: maestro-cloud: runs-on: ubuntu-latest outputs: app: app/build/outputs/apk/debug steps: - uses: actions/checkout@v3 - uses: actions/setup-java@v3 with: java-version: 11 distribution: 'temurin' - run: ./gradlew assembleDebug - uses: mobile-dev-inc/action-maestro-cloud@v1 with: api-key: ${{ secrets.MAESTRO_API_KEY }} # note that you can supply the project id any way you like, it is not secret project-id: ${{ secrets.MAESTRO_PROJECT_ID }} app-file: app/build/outputs/apk/debug/app-debug.apk `app-file` should point to an x86 compatible APK file, either directly to the file or a glob pattern matching the file name. When using a pattern, the first matched file will be used. ### [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android#proguard-deobfuscation) ProGuard Deobfuscation Include the ProGuard mapping file to deobfuscate Android performance traces: [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android#specifying-android-api-level) Specifying Android API Level ----------------------------------------------------------------------------------------------------------------------------------------------------------------- You can specify which Android API level to use when running using the `android-api-level` parameter. On Maestro Cloud, the default API level is 33 (Android 13). [Refer to Maestro Cloud docs](https://docs.maestro.dev/cloud/reference/configuring-os-version) for available Android emulator API levels. [PreviousGitHub Actions](https://docs.maestro.dev/cloud/ci-integration/github-actions) [NextMaestro GitHub Action for iOS](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios) Last updated 7 months ago Was this helpful? * [Full Example](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android#full-example) * [ProGuard Deobfuscation](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android#proguard-deobfuscation) * [Specifying Android API Level](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android#specifying-android-api-level) Was this helpful? Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app/build/outputs/apk/release/app-release.apk mapping-file: app/build/outputs/mapping/release/mapping.txt Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.apk android-api-level: 29 --- # Maestro GitHub Action for iOS | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios#full-example) Full Example ----------------------------------------------------------------------------------------------------------------------------- Copy name: Build and run Maestro tests (Native iOS) on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: macOS-latest steps: - uses: actions/checkout@v2 - run: xcodebuild build -scheme 'MyApp' -configuration Debug -project 'MyApp.xcodeproj' -destination 'generic/platform=iOS Simulator' CONFIGURATION_BUILD_DIR=$PWD/build - uses: mobile-dev-inc/action-maestro-cloud@v1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} # note that you can supply the project id any way you like, it is not secret project-id: ${{ secrets.MAESTRO_PROJECT_ID }} app-file: build/MyApp.app `app-file` should point to an .app build (x86 or ARM), either directly to the file or a glob pattern matching the file name. When using a pattern, the first matched file will be used. ### [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios#dsym-file) .dSYM file `mapping-file` should point to generated .dSYM file (unique per build). more info [here](https://developer.apple.com/documentation/xcode/building-your-app-to-include-debugging-information) . [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios#specifying-ios-version-and-device) Specifying iOS version and device ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can specify which iOS Version to use when running in Maestro Cloud using the `device-os` parameter. On Maestro Cloud, the default iOS version is 16. [Refer to Maestro Cloud docs](https://docs.maestro.dev/cloud/reference/configuring-os-version) for available iOS simulator versions. On Maestro Cloud, the default iOS version is 16. [PreviousMaestro GitHub Action for Android](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android) [NextMaestro GitHub Action for Flutter](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter) Last updated 7 months ago Was this helpful? * [Full Example](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios#full-example) * [.dSYM file](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios#dsym-file) * [Specifying iOS version and device](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios#specifying-ios-version-and-device) Was this helpful? Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: .app mapping-file: .app.dSYM Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip device-model: iPhone-16 device-os: iOS-18-2 --- # Maestro GitHub Action for Flutter | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://www.maestro.dev/) [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter#android) Android ----------------------------------------------------------------------------------------------------------------------- Copy name: Build and run Maestro tests (Flutter Android) on: workflow_dispatch: push: branches: [main] pull_request: branches: [main] jobs: upload: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: subosito/flutter-action@v2 with: channel: "stable" - run: flutter build apk --debug - uses: mobile-dev-inc/action-maestro-cloud@v1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} # note that you can supply the project id any way you like, it is not secret project-id: ${{ secrets.MAESTRO_PROJECT_ID }} app-file: build/app/outputs/flutter-apk/app-debug.apk [](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter#ios) iOS --------------------------------------------------------------------------------------------------------------- [PreviousMaestro GitHub Action for iOS](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios) [NextBitrise](https://docs.maestro.dev/cloud/ci-integration/bitrise) Last updated 10 months ago Was this helpful? * [Android](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter#android) * [iOS](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter#ios) Was this helpful? Copy name: Build and run Maestro tests (Flutter iOS) on: workflow_dispatch: push: branches: [main] pull_request: branches: [main] jobs: ios: runs-on: macos-13 steps: - uses: actions/checkout@v3 - uses: subosito/flutter-action@v2 with: channel: "stable" - run: flutter build ios --debug --simulator - uses: mobile-dev-inc/action-maestro-cloud@v1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} # note that you can supply the project id any way you like, it is not secret project-id: ${{ secrets.MAESTRO_PROJECT_ID }} app-file: build/ios/iphonesimulator/Runner.app # replace `Runner` with your app name --- # GitHub Actions | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) Maestro cloud testing is compatible with all CI systems and provides native integrations with a number of common providers including GitHub Actions. You can start running your Flows in CI with just a few lines of configuration using the [Maestro Cloud GitHub Action](http://github.com/mobile-dev-inc/action-maestro-cloud) . [](https://docs.maestro.dev/cloud/ci-integration/github-actions#setup) Setup --------------------------------------------------------------------------------- #### [](https://docs.maestro.dev/cloud/ci-integration/github-actions#add-your-api-key-secret) Add your API key secret The GitHub Action will need to authenticate with your Maestro account. So the first step is to expose your API key as a GitHub β€œRepository Secret”. **Add your API key as a β€œRepository Secret”** 1. Navigate to your GitHub repo and click on Settings in top nav bar. 2. In repository settings page click on `Secrets -> Actions`. It will open Action Secrets page. 3. On Action Secrets page, click on `New Repository Secret` button. Use `MAESTRO_API_KEY` as the secret name and paste your Maestro API key from the previous step into the β€œSecret” value text box. Click β€œAdd Secret” to add the secret. **Add your Project ID** The project ID is not a secret, so you either specify it as `project-id` in your workflow file or you add it as an env variable. **Other setup** Please refer to the Action documentation [here](https://github.com/marketplace/actions/maestro-cloud-upload-action) to see all configuration options. [](https://docs.maestro.dev/cloud/ci-integration/github-actions#example) Example ------------------------------------------------------------------------------------- Copy name: Build and run Maestro tests (Native Android) on: push: branches: [ main ] pull_request: branches: [ main ] jobs: maestro-cloud: runs-on: ubuntu-latest outputs: app: app/build/outputs/apk/debug steps: - uses: actions/checkout@v3 - uses: actions/setup-java@v3 with: java-version: 11 distribution: 'temurin' - run: ./gradlew assembleDebug - uses: mobile-dev-inc/action-maestro-cloud@v1 with: api-key: ${{ secrets.MAESTRO_API_KEY }} # note that you can supply the project id any way you like, it is not secret project-id: ${{ secrets.MAESTRO_PROJECT_ID }} app-file: app/build/outputs/apk/debug/app-debug.apk [](https://docs.maestro.dev/cloud/ci-integration/github-actions#commit-your-maestro-flows-to-your-repository) Commit your Maestro Flows to your repository --------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a `.maestro/` directory at the root of your repository and commit your Flows there: It’s common to have some Flow files that are only meant to be executed as part of another Flow via the `runFlow` command. These "subflows" can be nested under a subdirectory to prevent them from running as a top-level Flow. [](https://docs.maestro.dev/cloud/ci-integration/github-actions#inputs) Inputs ----------------------------------------------------------------------------------- Key Required Description `api-key` Yes Your Maestro Cloud API key `android-api-level` No The Android API level to use when running the Flows `app-file` Yes (or `app-binary-id`) Path to the app file to upload. `app-binary-id` Yes (or `app-file`) The ID of a previously uploaded app-file. `async` No Whether to start the flow and exit the action (defaults to `false`) `env` No Environment variables to pass to the run `exclude-tags` No Comma-separated list of tags to exclude from the run `include-tags` No Comma-separated list of tags to include in the run `mapping-file` No Path to the ProGuard map (Android) or dSYM (iOS) `project-id` Yes Which project to run the tests against `name` No Friendly name of the run `timeout` No How long to wait for the run to complete when not async (defaults to 30 minutes) `workspace` No Path to the workspace directory containing the Flows (defaults to `.maestro`) `device-model` No The [device model](https://docs.maestro.dev/cloud/reference/configuring-os-version#using-a-specific-ios-minor-version-and-device-recommended) to use when running the Flows (eg iPhone-11) `device-os` No The [device OS](https://docs.maestro.dev/cloud/reference/configuring-os-version) to use when running the Flows (eg iOS-16-2) `device-locale` No The [device locale](https://docs.maestro.dev/cloud/reference/configuring-device-locale) to use when running the Flows (eg en\_US) [](https://docs.maestro.dev/cloud/ci-integration/github-actions#custom-workspace-location) Custom workspace location ------------------------------------------------------------------------------------------------------------------------- By default, the action is looking for a `.maestro` folder with Maestro flows in the root directory of the project. If you would like to customize this behaviour, you can override it with a `workspace` argument: [](https://docs.maestro.dev/cloud/ci-integration/github-actions#custom-name) Custom name --------------------------------------------------------------------------------------------- A name will automatically be provided according to the following order: 1. If it is a Pull Request, use Pull Request title as name 2. If it is a normal push, use commit message as name 3. If for some reason the commit message is not available, use the commit SHA as name If you want to override this behaviour and specify your own name, you can do so by setting the `name` argument: [](https://docs.maestro.dev/cloud/ci-integration/github-actions#run-in-async-mode) Run in async mode --------------------------------------------------------------------------------------------------------- If you don't want the action to wait until the Upload has been completed as is the default behaviour, set the `async` argument to `true`: Alternatively, you might want to still wait for the action but would like to configure the timeout period, set `timeout` argument to a number of minutes: [](https://docs.maestro.dev/cloud/ci-integration/github-actions#triggers) Triggers --------------------------------------------------------------------------------------- Trigger this action on (1) pushes to your main branch and (2) pull requests opened against your main branch: If you need to use the `pull_request_target` trigger to support repo forks, check out the HEAD of the pull request to ensure that you're running the analysis against the changed code: For more information on triggering workflows, check out [GitHub's documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) . [](https://docs.maestro.dev/cloud/ci-integration/github-actions#adding-environment-variables) Adding environment variables ------------------------------------------------------------------------------------------------------------------------------- If you want to pass environment variables along with your upload, add a multiline `env` argument: [](https://docs.maestro.dev/cloud/ci-integration/github-actions#using-tags) Using tags ------------------------------------------------------------------------------------------- You can use Maestro [Tags](https://maestro.mobile.dev/cli/tags) to filter which Flows to send: You can either pass a single value, or comma-separated (`,`) values. [](https://docs.maestro.dev/cloud/ci-integration/github-actions#using-an-already-uploaded-app) Using an already uploaded App --------------------------------------------------------------------------------------------------------------------------------- You can use an already uploaded binary in Maestro Cloud using the `app-binary-id` parameter. [](https://docs.maestro.dev/cloud/ci-integration/github-actions#configuring-the-locale-for-the-device-where-the-flows-will-be-executed) Configuring the locale for the device where the flows will be executed ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To switch the device locale on a remote device from a default one (en\_US) `device-locale` parameter should be used. The value is a combination of lowercase ISO-639-1 code and uppercase ISO-3166-1 code, i.e. "de\_DE" for Germany. [](https://docs.maestro.dev/cloud/ci-integration/github-actions#outputs) Outputs ------------------------------------------------------------------------------------- The following output variables are set by the action: * `MAESTRO_CLOUD_CONSOLE_URL` - link to the Maestro Cloud console (if using Maestro Cloud) * `MAESTRO_CLOUD_UPLOAD_STATUS` - status of the Upload (not available in `async` mode) * `MAESTRO_CLOUD_FLOW_RESULTS` - list of Flows and their results (not available in `async` mode) * `MAESTRO_CLOUD_APP_BINARY_ID` - id of the binary uploaded (if using Maestro Cloud) In order to access these variables you can use the following approach: ### [](https://docs.maestro.dev/cloud/ci-integration/github-actions#output-types) Output types * `MAESTRO_CLOUD_UPLOAD_STATUS` Any of the following values: * `MAESTRO_CLOUD_FLOW_RESULTS` An array of objects with at least `name`, `status`, and `errors` fields. ### [](https://docs.maestro.dev/cloud/ci-integration/github-actions#usage-examples) Usage examples Below you can find various examples and additional configuration options for different platforms for how to structure your GitHub action to build and upload your app to Maestro Cloud: [Maestro GitHub Action for Android](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android) [Maestro GitHub Action for iOS](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-ios) [Maestro GitHub Action for Flutter](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter) [](https://docs.maestro.dev/cloud/ci-integration/github-actions#thats-it) That’s it! ----------------------------------------------------------------------------------------- [PreviousCI Integration](https://docs.maestro.dev/cloud/ci-integration) [NextMaestro GitHub Action for Android](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-android) Last updated 7 months ago Was this helpful? * [Setup](https://docs.maestro.dev/cloud/ci-integration/github-actions#setup) * [Example](https://docs.maestro.dev/cloud/ci-integration/github-actions#example) * [Commit your Maestro Flows to your repository](https://docs.maestro.dev/cloud/ci-integration/github-actions#commit-your-maestro-flows-to-your-repository) * [Inputs](https://docs.maestro.dev/cloud/ci-integration/github-actions#inputs) * [Custom workspace location](https://docs.maestro.dev/cloud/ci-integration/github-actions#custom-workspace-location) * [Custom name](https://docs.maestro.dev/cloud/ci-integration/github-actions#custom-name) * [Run in async mode](https://docs.maestro.dev/cloud/ci-integration/github-actions#run-in-async-mode) * [Triggers](https://docs.maestro.dev/cloud/ci-integration/github-actions#triggers) * [Adding environment variables](https://docs.maestro.dev/cloud/ci-integration/github-actions#adding-environment-variables) * [Using tags](https://docs.maestro.dev/cloud/ci-integration/github-actions#using-tags) * [Using an already uploaded App](https://docs.maestro.dev/cloud/ci-integration/github-actions#using-an-already-uploaded-app) * [Configuring the locale for the device where the flows will be executed](https://docs.maestro.dev/cloud/ci-integration/github-actions#configuring-the-locale-for-the-device-where-the-flows-will-be-executed) * [Outputs](https://docs.maestro.dev/cloud/ci-integration/github-actions#outputs) * [Output types](https://docs.maestro.dev/cloud/ci-integration/github-actions#output-types) * [Usage examples](https://docs.maestro.dev/cloud/ci-integration/github-actions#usage-examples) * [That’s it!](https://docs.maestro.dev/cloud/ci-integration/github-actions#thats-it) Was this helpful? Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚ └── Search.yaml Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ subflows/ β”‚ β”‚ └── MySubflow.yaml β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚ └── Search.yaml Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip workspace: myFlows/ Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip name: My Upload Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip async: true Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip timeout: 90 # Wait for 90 minutes Copy on: push: branches: [master] pull_request: branches: [master] Copy on: push: branches: [master] pull_request_target: branches: [master] jobs: upload-to-mobile-dev: name: Run Flows on Maestro Cloud steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # Checkout PR HEAD Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip env: | USERNAME= PASSWORD= Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip include-tags: dev, pull-request exclude-tags: excludeTag Copy - id: upload uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-binary-id: ${{ steps.upload.outputs.MAESTRO_CLOUD_APP_BINARY_ID }} Copy - uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip device-locale: de_DE Copy - id: upload uses: mobile-dev-inc/[emailΒ protected] with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: # ... any other parameters - name: Access Outputs if: always() run: | echo "Console URL: ${{ steps.upload.outputs.MAESTRO_CLOUD_CONSOLE_URL }}" echo "Flow Results: ${{ steps.upload.outputs.MAESTRO_CLOUD_FLOW_RESULTS }}" echo "Upload Status: ${{ steps.upload.outputs.MAESTRO_CLOUD_UPLOAD_STATUS }}" echo "App Binary ID: ${{ steps.upload.outputs.MAESTRO_CLOUD_APP_BINARY_ID }}" Copy PENDING PREPARING INSTALLING RUNNING SUCCESS ERROR CANCELED WARNING STOPPED Copy [{"name":"my-first-flow","status":"SUCCESS","errors":[]},{"name":"my-second-flow","status":"SUCCESS","errors":[]},{"name":"my-cancelled-flow","status":"CANCELED","errors":[],"cancellationReason":"INFRA_ERROR"}] --- # Bitbucket Pipelines | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) [](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#setup) Setup -------------------------------------------------------------------------------------- In order to use the Maestro Cloud Pipe to run Maestro tests in the cloud, you'll need to add the API key and project IDs as secret environment variables in your Bitbucket repository. 1. Go to your Repository -> Repository settings -> Repository Variables 2. Save your API Key and project id as a secured env variables [](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#commit-your-maestro-flows-to-your-repository) Commit your Maestro Flows to your repository -------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a `.maestro/` directory at the root of your repository and commit your Flows there: Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚ └── Search.yaml It’s common to have some Flow files that are only meant to be executed as part of another Flow via the `runFlow` command. These "subflows" can be nested under a subdirectory to prevent them from running as a top-level Flow. Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ subflows/ β”‚ β”‚ └── MySubflow.yaml β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚ └── Search.yaml [](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#add-maestro-cloud-pipe) Add Maestro Cloud Pipe ------------------------------------------------------------------------------------------------------------------------ Once everything is setup, you can integrate the [Maestro Cloud Upload Pipe](https://bitbucket.org/product/features/pipelines/integrations?search=maestro&p=mobiledevinc/maestro-cloud-upload) in your Pipeline build process. Edit your `bitbucket-pipelines.yml` and add an extra step after your app has finished building. _Note: All file paths are relative to the repository source root._ ### [](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#android) Android ### [](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#ios) iOS The pipe will: * Upload your app and flows to be run on Maestro's enterprise-grade cloud infrastructure * Wait for flows to complete (can be configured) * Complete with fail/pass depending on flow results [](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#thats-it) That's it! ---------------------------------------------------------------------------------------------- For more information and configurations, checkout [Maestro Cloud Upload Pipe](https://bitbucket.org/product/features/pipelines/integrations?search=maestro&p=mobiledevinc/maestro-cloud-upload) . [PreviousBitrise](https://docs.maestro.dev/cloud/ci-integration/bitrise) [NextCircleCI](https://docs.maestro.dev/cloud/ci-integration/circleci) Last updated 7 months ago Was this helpful? * [Setup](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#setup) * [Commit your Maestro Flows to your repository](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#commit-your-maestro-flows-to-your-repository) * [Add Maestro Cloud Pipe](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#add-maestro-cloud-pipe) * [Android](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#android) * [iOS](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#ios) * [That's it!](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines#thats-it) Was this helpful? Copy script: - pipe: mobiledevinc/maestro-cloud-upload:1.0.0 variables: MDEV_API_KEY: $MDEV_API_KEY MDEV_PROJECT_ID: $MDEV_PROJECT_ID MDEV_APP_FILE: app/build/outputs/apk/debug/app-debug.apk Copy script: - pipe: mobiledevinc/maestro-cloud-upload:1.0.0 variables: MDEV_API_KEY: $MDEV_API_KEY MDEV_PROJECT_ID: $MDEV_PROJECT_ID MDEV_APP_FILE: .app --- # Bitrise | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) Testing in Maestro Cloud is possible with all CI systems but provides native integrations with a number of common providers, including Bitrise. You can start running your Flows in CI with just a few clicks using the Maestro Cloud Bitrise Step. ### [](https://docs.maestro.dev/cloud/ci-integration/bitrise#setting-up-bitrise) Setting up Bitrise 1. Make sure you have your API key & Project ID. Both of these can be found in your [Maestro Cloud Console](https://app.maestro.dev/) . The API Key is an option on the left. Project IDs can be found in Settings, then clicking on the individual project on the left. 2. Go to your Bitrise account and save your API key into a secret variable, e.g. `CLOUD_API_KEY` (any variable prefixed with `MAESTRO_` will be [added as environment variable](https://docs.maestro.dev/advanced/parameters-and-constants) for your run - this might not be desirable for an authentication key!) 3. Open the Workflow Editor and select your desired workflow 1. To add the Maestro step, you can search for "Maestro" in Bitrise's library of steps. 2. The step should be added after your app binary has been built. ![Screenshot of the configuration of the Maestro Cloud step on Bitrise.io](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252F1oM1QQxXOXqi8twpt2r2%252FScreenshot%25202025-11-27%2520at%252015.38.37.png%3Falt%3Dmedia%26token%3D8a56bd73-c30e-428c-8768-a8fed185d168&width=768&dpr=4&quality=100&sign=d40362b4&sv=2) 4. Lastly, fill out the following information in the step configuration: 1. API Key (as your secret variable from earlier, e.g. `$CLOUD_API_KEY` 2. Project ID 3. Path to your built binary 5. Check the Flow Workspace matches your repo's directory structure 6. That's it! You should now be able to run Maestro tests in the cloud via Bitrise. [PreviousMaestro GitHub Action for Flutter](https://docs.maestro.dev/cloud/ci-integration/github-actions/maestro-github-action-for-flutter) [NextBitbucket Pipelines](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines) Last updated 1 month ago Was this helpful? Was this helpful? --- # CircleCI | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) The following guide will help you setup Maestro cloud testing in CircleCI. #### [](https://docs.maestro.dev/cloud/ci-integration/circleci#save-api-key-and-project-id-in-your-repository) Save API key and project ID in your repository First, you'll need to add the API key and Project DI as a secret ENV in your Project Settings 1. Go to your Project -> Project Settings -> Environment Variables 2. Save your API Key and Project ID ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-69b92606ef8c4b4ed3d259693cf2c62bd3aab6c6%252Fimage.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=f7efe1ad&sv=2) [](https://docs.maestro.dev/cloud/ci-integration/circleci#commit-your-maestro-flows-to-your-repository) Commit your Maestro Flows to your repository --------------------------------------------------------------------------------------------------------------------------------------------------------- Create a `.maestro/` directory at the root of your repository and commit your Flows there: It’s common to have some Flow files that are only meant to be executed as part of another Flow via the `runFlow` command. These "subflows" can be nested under a subdirectory to prevent them from running as a top-level Flow. [](https://docs.maestro.dev/cloud/ci-integration/circleci#add-maestro-upload-job) Add Maestro Upload Job ------------------------------------------------------------------------------------------------------------- Once everything is setup you can integrate maestro by adding another job in your `.circleci/config.yml` _Note: Maestro needs access to your flows and app binary, so make sure to either use_ [_persist\_to\_workspace_](https://circleci.com/docs/workspaces/) _or download the assets when running the upload job._ ### [](https://docs.maestro.dev/cloud/ci-integration/circleci#configure) Configure You can configure the upload parameters by modifying the `maestro cloud` command. For example: You can find all available options by running the Maestro CLI command locally ### [](https://docs.maestro.dev/cloud/ci-integration/circleci#example-android) Example: Android The following `config.yml` will: * Build an android app * Save the workspace and output apk * Upload your flows and apk ### [](https://docs.maestro.dev/cloud/ci-integration/circleci#example-ios) Example: iOS The following `config.yml` will: * Build an iOS app * Save the workspace and output `your_ios_app.app` * Upload your flows and `.app` binary [](https://docs.maestro.dev/cloud/ci-integration/circleci#thats-it) That's it! ----------------------------------------------------------------------------------- If everything was setup correctly, you should be seeing results in your workflow jobs [PreviousBitbucket Pipelines](https://docs.maestro.dev/cloud/ci-integration/bitbucket-pipelines) [NextIntegration with any CI platform](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) Last updated 7 months ago Was this helpful? * [Commit your Maestro Flows to your repository](https://docs.maestro.dev/cloud/ci-integration/circleci#commit-your-maestro-flows-to-your-repository) * [Add Maestro Upload Job](https://docs.maestro.dev/cloud/ci-integration/circleci#add-maestro-upload-job) * [Configure](https://docs.maestro.dev/cloud/ci-integration/circleci#configure) * [Example: Android](https://docs.maestro.dev/cloud/ci-integration/circleci#example-android) * [Example: iOS](https://docs.maestro.dev/cloud/ci-integration/circleci#example-ios) * [That's it!](https://docs.maestro.dev/cloud/ci-integration/circleci#thats-it) Was this helpful? Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚ └── Search.yaml Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ subflows/ β”‚ β”‚ └── MySubflow.yaml β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚ └── Search.yaml Copy maestro-upload: docker: - image: cimg/openjdk:19.0.1 steps: - attach_workspace: at: . - run: name: Download maestro and run in the cloud command: | curl -Ls "https://get.maestro.mobile.dev" | bash export PATH="$PATH":"$HOME/.maestro/bin" maestro cloud \ --apiKey $MDEV_API_KEY \ --projectId $MDEV_PROJECT_ID \ path_to_my_app .maestro Copy maestro cloud \ --apiKey $MDEV_API_KEY \ --projectId $MDEV_PROJECT_ID \ --name "Custom upload name" \ --async \ -e EMAIL="[emailΒ protected]" -e PASSWORD="some-password" /tmp/app.apk /tmp/flows Copy > maestro cloud Copy version: 2.1 orbs: android: circleci/[emailΒ protected] jobs: build-android: executor: name: android/android-docker tag: 2022.08.1 steps: - checkout - android/restore-gradle-cache - run: name: Assemble debug build command: | ./gradlew :app:assembleDebug - persist_to_workspace: root: . paths: - . maestro-upload: docker: - image: cimg/openjdk:19.0.1 steps: - attach_workspace: at: . - run: name: Upload to Maestro Cloud command: | curl -Ls "https://get.maestro.mobile.dev" | bash export PATH="$PATH":"$HOME/.maestro/bin" maestro cloud \ --apiKey $MDEV_API_KEY \ --projectId $MDEV_PROJECT_ID \ app/build/outputs/apk/debug/app-debug.apk .maestro workflows: build-and-upload: jobs: - build-android - maestro-upload: requires: - build-android Copy version: 2.1 jobs: build-ios: macos: xcode: 13.3.1 environment: XCODE_VERSION: "Xcode-13.3.1" steps: - checkout - run: name: Switch xcode command: sudo xcode-select --switch /Applications/$XCODE_VERSION.app - run: name: Build iOS app command: | XCODE_PATH=$(xcode-select -p) SIMULATOR_SDKS_AVAILABLE=$(find "$XCODE_PATH/Platforms/iPhoneSimulator.platform/Developer/SDKs/" -type l -maxdepth 1) SIMULATOR_SDK_PATH=$(echo "$SIMULATOR_SDKS_AVAILABLE" | head -n1) SIMULATOR_SDK=$(basename -s .sdk -a "$SIMULATOR_SDK_PATH" | awk '{print tolower($0)}') mkdir build xcodebuild build \ -sdk "$SIMULATOR_SDK" \ -destination 'platform=iOS Simulator' \ CONFIGURATION_BUILD_DIR=build - persist_to_workspace: root: . paths: - . maestro-upload: docker: - image: cimg/openjdk:19.0.1 steps: - attach_workspace: at: . - run: name: Download and run maestro command: | curl -Ls "https://get.maestro.mobile.dev" | bash export PATH="$PATH":"$HOME/.maestro/bin" maestro cloud \ --apiKey $MDEV_API_KEY \ --projectId $MDEV_PROJECT_ID \ build/MyApp.app .maestro workflows: build-and-upload: jobs: - build-ios - maestro-upload: requires: - build-ios --- # Writing Your First Flow | Maestro Write a test in a YAML file Copy # flow.yaml appId: your.app.id --- - launchApp - tapOn: "Text on the screen" Make sure an Android device/emulator or iOS simulator is running ([instructions](https://docs.maestro.dev/getting-started/installing-maestro#android) ) and app is correctly installed on a selected device ([instructions](https://docs.maestro.dev/getting-started/build-and-install-your-app) ). Run it! Copy maestro test flow.yaml [PreviousRun a Sample Flow](https://docs.maestro.dev/getting-started/run-a-sample-flow) [NextMaestro Studio Desktop - Beta](https://docs.maestro.dev/getting-started/maestro-studio-desktop) Last updated 7 months ago Was this helpful? Was this helpful? --- # Maestro Studio Desktop - Beta | Maestro Maestro Studio is all-in-one **desktop app** for end-to-end automated testing on Mobile and Web. [Download for Mac](https://studio.maestro.dev/MaestroStudio.dmg) [Download for Windows](https://studio.maestro.dev/MaestroStudio.exe) [Download for Linux](https://studio.maestro.dev/MaestroStudio.AppImage) ### [](https://docs.maestro.dev/getting-started/maestro-studio-desktop#b415) No CLI needed Skip the terminal πŸ™…β€β™‚οΈ * **Zero CLI** - Launch Maestro tests with a click * **No IDE setup** - Forget VS Code extensions, Android Studio, or Xcode boot-ups. * **Instant device connect** - Connect a device (Android, iOS, or Web). * **Runs on every OS** - Native installers for macOS (Apple Silicon & Intel), Windows, and Linux. ### [](https://docs.maestro.dev/getting-started/maestro-studio-desktop#id-2508) Quick Start 1. **Download & install** for your OS (⬆ buttons above). 2. **Connect a device** 3. **Create a new test** 4. **Click \[β–ΆοΈŽ Run Locally\]** (or \[☁️ Run on Cloud\]) ### [](https://docs.maestro.dev/getting-started/maestro-studio-desktop#trusted-by-the-worlds-best-teams) _Trusted by the worlds best teams:_ ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-352917e014f418808bdd0e9703555bd7e4aabe33%252FScreenshot%25202025-06-16%2520at%252012.18.54%2520-%2520Editado.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=e8e49bfa&sv=2)![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-3800cea68775a009b9d27c1b5523f0c48b901488%252FUntitled%2520design%2520%281%29.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=45e04f6a&sv=2) [Join our Slack for support & feedback β†’](https://mobiledev.typeform.com/to/FelIEe8A?typeform-source=maestro.dev) [PreviousWriting Your First Flow](https://docs.maestro.dev/getting-started/writing-your-first-flow) [NextMaestro Studio (CLI)](https://docs.maestro.dev/getting-started/maestro-studio-cli) Last updated 1 month ago Was this helpful? * [No CLI needed](https://docs.maestro.dev/getting-started/maestro-studio-desktop#b415) * [Quick Start](https://docs.maestro.dev/getting-started/maestro-studio-desktop#id-2508) * [Trusted by the worlds best teams:](https://docs.maestro.dev/getting-started/maestro-studio-desktop#trusted-by-the-worlds-best-teams) Was this helpful? --- # Maestro Studio (CLI) | Maestro Use Maestro Studio to instantly discover the exact commands needed to interact with your app. Here’s how it works: ### [](https://docs.maestro.dev/getting-started/maestro-studio-cli#b415) Launch Maestro Studio Maestro Studio is built right into the Maestro CLI. Upgrade your CLI to the latest version, and run the command below to launch Maestro Studio in your browser: Here’s what you’ll see: ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-dcfb6e94937707c8e72aa33e80e884d2f998d320%252FScreenshot%25202023-07-13%2520at%252018.54.53.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5567de92&sv=2) You can either visually select UI elements in order to receive suggestions on how to interact with the element in your Flow, or enter Maestro commands in the REPL and run them by pressing `Run`. ### [](https://docs.maestro.dev/getting-started/maestro-studio-cli#id-2508) Visually Select a UI Element Click on the device screenshot to select a UI element, e.g. Settings icon on the iOS simulator. ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-0ab0796aca87450640d18b5f3227af071f524ca8%252FScreenshot%25202023-07-13%2520at%252018.58.06.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=6ceb8e02&sv=2) #### [](https://docs.maestro.dev/getting-started/maestro-studio-cli#id-725d) Automatically Generated Examples Maestro Studio automatically generates examples of how you can interact with the selected element in your Flows. You can double click on the example to execute it directly, or use the hotkeys to copy it to the clipboard or open the relevant documentation. ### [](https://docs.maestro.dev/getting-started/maestro-studio-cli#executing-commands-in-the-repl) Executing commands in the REPL You can execute Maestro commands inline in Studio in the REPL view. The commands are written in YAML in the same way as you would write any normal Flow. ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-43c9e5a8427ddf8237f63480c143c70daa22077d%252FScreenshot%25202023-07-17%2520at%252019.12.37.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=3d53a5c4&sv=2) [PreviousMaestro Studio Desktop - Beta](https://docs.maestro.dev/getting-started/maestro-studio-desktop) [NextRunning Flows on CI](https://docs.maestro.dev/getting-started/running-flows-on-ci) Last updated 7 months ago Was this helpful? * [Launch Maestro Studio](https://docs.maestro.dev/getting-started/maestro-studio-cli#b415) * [Visually Select a UI Element](https://docs.maestro.dev/getting-started/maestro-studio-cli#id-2508) * [Executing commands in the REPL](https://docs.maestro.dev/getting-started/maestro-studio-cli#executing-commands-in-the-repl) Was this helpful? Copy maestro studio --- # Running Flows on CI | Maestro ### [](https://docs.maestro.dev/getting-started/running-flows-on-ci#running-in-the-cloud) Running in the Cloud The easiest way to test your flows in CI is to run your flows on Maestro's enterprise-grade hosted cloud infrastructure. Since your flows run in the cloud there's no need to configure any simulators or emulators on your end. Check out the docs to get started in less than 5 minutes: [Run Maestro tests in the cloud](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud) ### [](https://docs.maestro.dev/getting-started/running-flows-on-ci#alternatives) Alternatives Maestro CLI can run flows on any Android device/emulator that supports ADB connections and any iOS simulator that supports Facebook's IDB. You can manually orchestrate your flow execution against any provider that supports these protocols. Just use the Maestro CLI to run your flows like you would locally. [PreviousMaestro Studio (CLI)](https://docs.maestro.dev/getting-started/maestro-studio-cli) [NextMaestro MCP](https://docs.maestro.dev/getting-started/maestro-mcp) Last updated 10 months ago Was this helpful? * [Running in the Cloud](https://docs.maestro.dev/getting-started/running-flows-on-ci#running-in-the-cloud) * [Alternatives](https://docs.maestro.dev/getting-started/running-flows-on-ci#alternatives) Was this helpful? --- # Integration with any CI platform | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) You can use the Maestro CLI to run your Flows in the cloud from any CI platform. [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------------------- **API Key** Reach out to your mobile.dev representative to obtain your Maestro API key Project ID The id of the project you want to upload your app and Flows to. You can retrieve this from the Maestro console. **iOS** Provide a path that points to an x86-compatible `*.app` simulator build directory, or a zipped file that contains the `*.app` build. **Android** You APK must be x86-compatible. [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-1.-organize-your-flows) 1\. Organize your Flows ----------------------------------------------------------------------------------------------------------------------------------------- Add all of your Flows under a single directory in your repo. We recommend naming this directory `.maestro/` as this is the naming convention our native integrations expect by default. (Note the "." at the beginning of `.maestro/`) Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚Β Β  └── Search.yaml All of the flows directly under the `.maestro/` directory will be executed as top-level flows. #### [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#subflows) Subflows It's common to have some Flow files that are only meant to be executed as part of another Flow via the `runFlow` command. These "subflows" can be nested under a subdirectory to prevent them from running as a top-level Flow. In the example above, `MySubflow.yaml` will not be executed as a top-level Flow, but still can be referenced by other Flows using the `runFlow` command. [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-2.-run-flows-in-the-cloud) 2\. Run Flows in the cloud ----------------------------------------------------------------------------------------------------------------------------------------------- #### [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-1.-install-the-maestro-cli) 1\. Install the Maestro CLI First, ensure that the [Maestro CLI is installed](https://docs.maestro.dev/getting-started/installing-maestro) on your CI machine: #### [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-2.-run-the-maestro-cloud-command) 2\. Run the "maestro cloud" command Add a step in your CI workflow that executes the `maestro cloud` command: **** Maestro API Key Maestro Project ID **** The APK file or .app directory ([instructions](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud) ) **.maestro/** The directory that contains your Flows To set a name for your upload, use the `--name` option: Note that you can also define your API key as an environment variable in your shell with the name `MAESTRO_CLOUD_API_KEY` and Maestro will automatically read it for you [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-3.-detect-flow-failures) 3\. Detect Flow Failures ------------------------------------------------------------------------------------------------------------------------------------------- The `maestro cloud` command and our native CI integrations will wait for your Flows to finish executing before returning. If any Flow failures are detected, the exit code is set to 1. On success, the exit code will be set to 0. This allows you to leverage any existing test alerting you have in place. [](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-4.-view-result-details) 4\. View Result Details ----------------------------------------------------------------------------------------------------------------------------------------- A link to the current upload will be printed out to your logs. You can view any ongoing or past uploads in the Maestro console. [PreviousCircleCI](https://docs.maestro.dev/cloud/ci-integration/circleci) [NextPull Request Integration](https://docs.maestro.dev/cloud/pull-request-integration) Last updated 7 months ago Was this helpful? * [Prerequisites](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#prerequisites) * [1\. Organize your Flows](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-1.-organize-your-flows) * [2\. Run Flows in the cloud](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-2.-run-flows-in-the-cloud) * [3\. Detect Flow Failures](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-3.-detect-flow-failures) * [4\. View Result Details](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform#id-4.-view-result-details) Was this helpful? Copy β”œβ”€β”€ .maestro/ β”‚ β”œβ”€β”€ subflows/ β”‚Β Β  β”‚Β Β  └── MySubflow.yaml β”‚ β”œβ”€β”€ Login.yaml β”‚ β”œβ”€β”€ Add to Cart.yaml β”‚Β Β  └── Search.yaml Copy curl -Ls "https://get.maestro.mobile.dev" | bash Copy maestro cloud --apiKey --project-id .maestro/ Copy maestro cloud --apiKey --project-id --name \ --branch \ --repoOwner \ --repoName \ --pullRequestId \ --commitSha \ .maestro/ **branch** Set to the name of the git branch the app was built on and the pull request is based on (i.e. feature-foo) **repoOwner** Set to the owner of the repository (i.e. "mobile-dev-inc") **repoName** Set to the name of the repository (i.e. "fenix") **pullRequestId** Set to the unique identifier of the pull request. Only set when triggered by a Pull Request. (i.e. 1234) **commitSha** Set to the commit hash. Only set when triggered by a Pull Request. (i.e. 586e1c690891d20568976c78f06fbec9b94a3b32) 1. Ensure that uploads are triggered on every pull request. Exactly how this is accomplished depends on your CI setup. 2. Add the following values to the JSON data in the upload API request: **repoOwner** Set to the owner of the repository (i.e. "mobile-dev-inc") **repoName** Set to the name of the repository (i.e. "fenix") **branch** Set to the name of the git branch the app was built on and the pull request is based on (i.e. feature-foo) **pullRequestId** Set to the unique identifier of the pull request. Only set when triggered by a pull request. (i.e. 1234) **commitSha** Set to the commit hash. Only set when triggered by a Pull Request. (i.e. 586e1c690891d20568976c78f06fbec9b94a3b32) ### [](https://docs.maestro.dev/cloud/pull-request-integration#id-2.-grant-access-to-pull-requests) 2\. Grant access to pull requests In order to update the status of pull requests, you'll need to grant Maestro permissions to do so. * [Install the Maestro Cloud GitHub App](https://github.com/apps/maestro-cloud-app) ### [](https://docs.maestro.dev/cloud/pull-request-integration#id-3.-test-the-integration) 3\. Test the integration Lastly, open a pull request and ensure that the Maestro Cloud check shows up on your pull request. GitHub / GitHub Enterprise ![Successful check on Github PR page](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-76cb7fc8d4a5f42ff61b79c2a46c278b2c7add21%252Fimage.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5c911858&sv=2) [PreviousIntegration with any CI platform](https://docs.maestro.dev/cloud/ci-integration/integration-with-any-ci-platform) [NextCloud Reference](https://docs.maestro.dev/cloud/reference) Last updated 7 months ago Was this helpful? * [1\. Trigger uploads on every pull request](https://docs.maestro.dev/cloud/pull-request-integration#id-1.-trigger-uploads-on-every-pull-request) * [2\. Grant access to pull requests](https://docs.maestro.dev/cloud/pull-request-integration#id-2.-grant-access-to-pull-requests) * [3\. Test the integration](https://docs.maestro.dev/cloud/pull-request-integration#id-3.-test-the-integration) Was this helpful? --- # Cloud Reference | Maestro [Build your app for the cloud](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud) [Configuring OS Version](https://docs.maestro.dev/cloud/reference/configuring-os-version) [Configuring device locale](https://docs.maestro.dev/cloud/reference/configuring-device-locale) [Device timezones](https://docs.maestro.dev/cloud/reference/device-timezones) [Email Notifications](https://docs.maestro.dev/cloud/reference/email-notifications) [Slack Notifications](https://docs.maestro.dev/cloud/reference/slack-notifications) [Webhook Integration](https://docs.maestro.dev/cloud/reference/webhook-integration) [Managing Secrets](https://docs.maestro.dev/cloud/reference/managing-secrets) [Limits](https://docs.maestro.dev/cloud/reference/limits) [Reusing App Binary](https://docs.maestro.dev/cloud/reference/reusing-app-binary) [IP Allowlist](https://docs.maestro.dev/cloud/reference/ip-allowlist) [System Status](https://status.mobile.dev/) [PreviousPull Request Integration](https://docs.maestro.dev/cloud/pull-request-integration) [NextBuild your app for the cloud](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud) Last updated 10 months ago Was this helpful? Was this helpful? --- # Build your app for the cloud | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) Before running your flows on Maestro Cloud, you'll need an app binary to upload along with your tests. We've included build instructions for some of the most common platforms below. After building your app, run on Maestro Cloud: Maestro Studio Maestro CLI * **Run all flows on Maestro Cloud -** Click on the `Run on Cloud` button in the sidebar and then select your app binary. * **Run a single flow on Maestro Cloud -** Open the flow file and click on the `Run on Cloud` button on at the top of the file and then select your app binary. Copy maestro cloud [your-app-binary] [your-flow-directory] [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#ios) iOS ---------------------------------------------------------------------------------- ### [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-xcode-command-line-tools) Building with Xcode command line tools To build an app with Xcode command line tools **xcrun xcodebuild** should be used. Here is an example on how to build an app called `MyApp` for iOS simulator target: Copy xcodebuild -project MyApp.xcodeproj \ -scheme MyApp \ -configuration Debug \ -destination 'generic/platform=iOS Simulator' \ CONFIGURATION_BUILD_DIR=$PWD/build The `.app file` will then be located `build/` folder, which can be modified via the last parameter of the script. ### [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-fastlane) Building with Fastlane If you use [fastlane](https://fastlane.tools/) for your automation pipelines the script should look the following way: ### [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-flutter) Building with Flutter If you use Flutter to build your app you can create a debug build for simulators using the following command: You can then find your app file in the `build/ios/iphonesimulator/` directory. [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#android) Android ------------------------------------------------------------------------------------------ Android app binary requirements: * APK (AAB not supported) * Compatible with x86\_64 architecture * Release and Debug builds both supported [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-gradle) Building with Gradle -------------------------------------------------------------------------------------------------------------------- Build your app using one of the commands below. Then find the appropriate APK file in the `build/outputs/apk/` output directory. [](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-flutter-1) Building with Flutter ------------------------------------------------------------------------------------------------------------------------ If you use Flutter to build your app you can create a debug build using the following command: You can then find the built apk in the `build/app/outputs/`folder. [PreviousCloud Reference](https://docs.maestro.dev/cloud/reference) [NextConfiguring OS Version](https://docs.maestro.dev/cloud/reference/configuring-os-version) Last updated 27 days ago Was this helpful? * [iOS](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#ios) * [Building with Xcode command line tools](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-xcode-command-line-tools) * [Building with Fastlane](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-fastlane) * [Building with Flutter](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-flutter) * [Android](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#android) * [Building with Gradle](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-gradle) * [Building with Flutter](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud#building-with-flutter-1) Was this helpful? Copy xcodebuild( configuration: build_config[:configuration], scheme: build_config[:scheme], workspace: build_config[:xcode_workspace], xcargs: "-quiet -sdk 'iphonesimulator' -destination 'generic/platform=iOS Simulator'", derivedDataPath: IOS_DERIVED_DATA_PATH # this will contain the .app which we need later on ) Copy flutter build ios --debug --simulator Copy # Release build ./gradlew assembleRelease # Debug build ./gradlew assembleDebug Copy # Release build flutter build apk # Debug build flutter build apk --debug --- # Configuring OS Version | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) ### [](https://docs.maestro.dev/cloud/reference/configuring-os-version#android) Android You can configure your Flows to run on a specific Android OS version (API level) using the `android-api-level` parameter when running the `maestro cloud` command: Copy maestro cloud --android-api-level 30 myapp.apk myflows/ If you're using one of the CI integrations, please refer to the CI documentation for your specific integration: [CI Integration](https://docs.maestro.dev/cloud/ci-integration) #### [](https://docs.maestro.dev/cloud/reference/configuring-os-version#emulator-specs) Emulator specs * x86\_64 architecture * Android API 33 (Google APIs) **(Default)** * 606x1280, 244 dpi\\ **Supported API levels:** Android Version API Level Android 14 Upside Down Cake 34 (Google APIs) Android 13 Tiramisu 33 (Google APIs) (default) Android 12 Snow Cone 31 (Google APIs) Android 11 Red Velvet Cake 30 (Google APIs) Android 10 Quince Tart 29 (Google APIs) ### [](https://docs.maestro.dev/cloud/reference/configuring-os-version#ios) iOS Flows will be run on iOS simulators #### [](https://docs.maestro.dev/cloud/reference/configuring-os-version#simulator-specs) Simulator Specs * ARM or x86 architecture (via Rosetta) * iOS version 16 (default) * iPhone 11 (default) * 828x1792, 326 ppi (iPhone 11) ### [](https://docs.maestro.dev/cloud/reference/configuring-os-version#using-the-ios-version-parameter-deprecated) Using the `ios-version` parameter (deprecated) You can configure your Flows to run on a specific iOS major version using the `ios-version` parameter when running the `maestro cloud` command: Maestro will automatically select an appropriate minor version, meaning that if you specify iOS 16 your Flows will for example be run on 16.2. If you happen to specify a minimum deployment target version that is below the selected minor version (for example 16.0), an error message will be surfaced with instructions on how to recover. Notice this mode is deprecated and will be removed in a future release. Current supported values are `16`, `17` and `18`. If you use this flag, your tests will always run with an iPhone 11 simulator. ### [](https://docs.maestro.dev/cloud/reference/configuring-os-version#using-a-specific-ios-minor-version-and-device-recommended) Using a specific iOS minor version & device (recommended) You can configure your Flows to run on a specific iOS runtime and device using the `--device-os` and `--device-model` flags when running the `maestro cloud` command. The following values are supported: * \--device-model - `iPhone-11`, `iPhone-13-mini`, `iPhone-16-Pro`, `iPhone-16`, `iPhone-16-Pro`, `iPhone-16-Pro-Max`, `iPad-10th-generation` * \--device-os - `iOS-16-2`, `iOS-17-5`, `iOS-18-2` Please note that not all runtimes are available for all devices. This table covers the available combinations: Device Model iOS Version iPhone-11 iOS-16-2, iOS-17-5, iOS-18-2 iPhone-13-mini iOS-18-2 iPhone-16-Pro iOS-18-2 iPhone-16-Pro-Max iOS-18-2 iPhone-16 iOS-18-2 iPad-10th-generation iOS-16-2, iOS-17-5, iOS-18-2 For example, to run your Flows on iOS 18.2 with an iPhone 16 Pro, you would use: [PreviousBuild your app for the cloud](https://docs.maestro.dev/cloud/reference/build-your-app-for-cloud) [NextConfiguring device locale](https://docs.maestro.dev/cloud/reference/configuring-device-locale) Last updated 3 months ago Was this helpful? * [Android](https://docs.maestro.dev/cloud/reference/configuring-os-version#android) * [iOS](https://docs.maestro.dev/cloud/reference/configuring-os-version#ios) * [Using the ios-version parameter (deprecated)](https://docs.maestro.dev/cloud/reference/configuring-os-version#using-the-ios-version-parameter-deprecated) * [Using a specific iOS minor version & device (recommended)](https://docs.maestro.dev/cloud/reference/configuring-os-version#using-a-specific-ios-minor-version-and-device-recommended) Was this helpful? Copy maestro cloud --ios-version 17 myapp.app myflows/ Copy maestro cloud --device-os iOS-18-2 --device-model iPhone-16-Pro myapp.app myflows/ --- # Configuring device locale | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) `maestro cloud` supports testing different app locales by changing a device locale for a given upload automatically by setting `--device-locale` parameter. The parameter `--device-locale` is a combination of [`ISO-639-1`](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) `+` [`ISO-3166-1`](https://en.wikipedia.org/wiki/ISO_3166-1) with using underscore `_` symbol in between them. If the parameter is omitted default `en_US` locale will be used. Here are some example usages: Copy // sets device locale to German(Germany) maestro cloud --device-locale de_DE // sets device locale to Japanese(Japan) maestro cloud --device-locale ja_JP Full list of supported locales can be found [here](https://docs.maestro.dev/advanced/testing-in-different-locales) . [PreviousConfiguring OS Version](https://docs.maestro.dev/cloud/reference/configuring-os-version) [NextDevice timezones](https://docs.maestro.dev/cloud/reference/device-timezones) Last updated 7 months ago Was this helpful? Was this helpful? --- # Device timezones | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) Android emulator instances and macOS instances (iOS flows are executed on iOS simulators) are located in following regions and timezones. Device type Region\*\* Timezone Android us-west1-a ([gcloud](https://cloud.google.com/compute/docs/regions-zones) ) UTC iOS vegas GMT -7 \*\* In here region represents a physical location of an emulated (linux instance with hosted Android emulator) / simulated (macOS instance with iOS simulator) environment. Device has an ability to override some of those settings, i.e. timezone of an Android emulator is UTC by default. [PreviousConfiguring device locale](https://docs.maestro.dev/cloud/reference/configuring-device-locale) [NextEmail Notifications](https://docs.maestro.dev/cloud/reference/email-notifications) Last updated 7 months ago Was this helpful? Was this helpful? --- # Email Notifications | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) You can set up Maestro to notify you and your team when a Flow in the cloud. That's useful to easily keep track if your app is working as expected. In the `config.yaml` file add the list of emails that should receive the notifications: Copy # .maestro/config.yaml notifications: email: enabled: true recipients: - [emailΒ protected] - [emailΒ protected] ... any other emails you want to send notifications to Note that the `config.yaml` file should be present in the root of your workspace along with your Flows, which by default is `.maestro` if you do not explicitly pass another folder as the workspace. When a Flow fails, you will receive an email like this: ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-f3fbcecc154ac086fda691f693566d32506de6f9%252Fimage.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=119d9236&sv=2) ### [](https://docs.maestro.dev/cloud/reference/email-notifications#receiving-notifications-on-success) Receiving notifications on success By default, emails are only sent when a failure is detected. If you want to be notified on successful runs as well, add `onSuccess: true` to your config: ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-f3aa40f9103d39a9bd0769b67c2c3475e0c5e8b9%252Fimage.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=e8a72724&sv=2) [PreviousDevice timezones](https://docs.maestro.dev/cloud/reference/device-timezones) [NextSlack Notifications](https://docs.maestro.dev/cloud/reference/slack-notifications) Last updated 7 months ago Was this helpful? Was this helpful? Copy # .maestro/config.yaml notifications: email: enabled: true onSuccess: true recipients: - [emailΒ protected] - [emailΒ protected] ... any other emails you want to send success notifications to --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address docs.maestro.dev ------------------------------------------------------------ The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/) * [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/) Cloudflare Ray ID: **9bb2f0876cf581e1** β€’ Your IP: Click to reveal 54.237.218.47 β€’ Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) --- # Slack Notifications | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) You can set up Maestro to notify you and your team about results from **a specific project when** [running in the cloud](https://docs.maestro.dev/cloud/run-maestro-tests-in-the-cloud) . That's useful to easily keep track if your app is working as expected. 1. Go to the settings in your Maestro Console ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-daf65bd1d8e5a797f51cf05a54a38cf7ccd1203e%252Frobin-console-settings.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=52430f98&sv=2) 1. Click on the `Connect Slack` button Then you are going to be redirected to the slack page, where you need to authorize the integration and select the channel you want to receive the notifications. ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-a875b8bc7743363fdeb17beb3f8be7401a8789d9%252Fslack-integration-redirect.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=a2c7a675&sv=2) 1. After you have authorized the integration, you will be redirected back to the Maestro Console, and the integration will be enabled. ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-cc1a976f86f42e2d3881315c94713b389f6d3a0f%252Fslack-bot-onboarding.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=c8e1c831&sv=2) 1. That's it! When an upload finishes a message will be posted in your channel. ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-67b192790b2300481255e8dae793157bfca4f6d8%252Fslack-bot-successful-upload.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=bcfb53e3&sv=2) ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-222b9a10210a1ab0a5d3c424512c02a079bd9590%252Fslack-bot-failure-upload.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=2d6796d5&sv=2) 1. If you want to disable the integration or change the channel that receives the notifications, you can easily do it in the settings page. ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-e21d0580143fe69e5edf24b444e912d89f3c4ef3%252Fsettings-update-slack-bot.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=3e808850&sv=2) Our original YouTube intro to this feature can be found here: **Coming soon:** * Customize the message that is sent to the channel * Receive notifications only for failed uploads * AI integration [PreviousEmail Notifications](https://docs.maestro.dev/cloud/reference/email-notifications) [NextWebhook Integration](https://docs.maestro.dev/cloud/reference/webhook-integration) Last updated 7 months ago Was this helpful? Was this helpful? --- # Webhook Integration | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) You can set up Maestro to send webhook notifications about upload results from **a specific project**. This allows you to integrate upload events with your custom workflows, monitoring systems, or other external services. 1. Go to the settings in your Maestro Console Webhooks provide a flexible way to receive real-time notifications about upload events programmatically. 1. Navigate to the Project Settings page 2. Configure your Webhook URL * Enter the full URL where you want to receive webhook notifications ![Webhook Settings](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-846055e10138c2654f7fd474e69dff01346a90f1%252Fwebhook-management-settings.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=2b38e412&sv=2) 3. Get your Webhook Token Copy the token provided in the settings page, to use it in your webhook endpoint as the Bearer Token. ![Webhook URL Configuration](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-bc80d4c9aa8c2cfdef20e7ce8e3aaa8b4a7f116e%252Fwebhook-management-token.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=e3601a7b&sv=2) 4. Verify and Enable the Webhook 1. Webhook Payload Example When an upload event occurs, a POST request will be sent to your configured URL with a JSON payload: 1. Manage Webhook Integration * You can update or disable the webhook at any time in the settings * You can have multiple webhooks configured for the same project * Test your webhook configuration with a sample payload [PreviousSlack Notifications](https://docs.maestro.dev/cloud/reference/slack-notifications) [NextManaging Secrets](https://docs.maestro.dev/cloud/reference/managing-secrets) Last updated 7 months ago Was this helpful? Was this helpful? Copy Ensure your webhook endpoint can handle POST requests and is publicly accessible. Copy { "id": "mupload_123456", "name": "TestApp Release 1.2.3", "url": "https://app.maestro.dev/project/project-abc123/maestro-test/app/com.example.testapp/upload/upload-123456", "platform": "ANDROID", "appId": "com.example.testapp", "githubBranch": "main", "envVariables": { "API_ENDPOINT": "https://api.example.com", "FEATURE_FLAG_ENABLED": "true" }, "startTime": 1659312000000, "endTime": 1659315600000, "flows": [\ {\ "id": "run_789012",\ "name": "Login Flow Test",\ "url": "https://app.maestro.dev/project/project-abc123/maestro-test/flow/run-789012",\ "status": "SUCCESS",\ "failureReason": null,\ "startTime": 1659312000000,\ "endTime": 1659312300000\ },\ {\ "id": "run_789013",\ "name": "Checkout Flow Test",\ "url": "https://app.maestro.dev/project/project-abc123/maestro-test/flow/run-789013",\ "status": "FAILURE",\ "failureReason": "Element with ID 'checkout_button' not found",\ "startTime": 1659312600000,\ "endTime": 1659312900000\ },\ {\ "id": "run_789014",\ "name": "User Profile Flow",\ "url": "https://app.maestro.dev/project/project-abc123/maestro-test/flow/run-789014",\ "status": "SUCCESS",\ "failureReason": null,\ "startTime": 1659313200000,\ "endTime": 1659313500000\ }\ ] } --- # IP Allowlist | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) If your network requires external services to be on an allowlist (formerly called a whitelist) to allow access, you can use the following lists to update your ACLs. * 207.254.42.234 * 34.127.79.8 * 35.247.62.137 * 34.83.16.33 These IPs addresses will not change, but we reserve the right to add more IPs in the future. Contact us to join a mailing list to be notified of future changes. [PreviousReusing App Binary](https://docs.maestro.dev/cloud/reference/reusing-app-binary) [NextSupported Platforms](https://docs.maestro.dev/platform-support/supported-platforms) Last updated 21 days ago Was this helpful? Was this helpful? --- # Managing Secrets | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) There might be cases where you don't want to store certain values in a flow file itself (i.e. user name, password, etc.). Maestro solves that by taking such parameters as [variables](https://docs.maestro.dev/cloud/reference/managing-secrets#using-variables-in-your-flows) . Maestro CLI Github Action Pass in parameters using the `-e` option: Copy maestro cloud \ --api-key --project-id -e USERNAME=$TEST_USERNAME \ -e PASSWORD=$TEST_PASSWORD \ .maestro/ Parameters are provided as multiline `env` field Copy - uses: mobile-dev-inc/action-maestro-cloud@v1 with: api-key: ${{ secrets.MOBILE_DEV_API_KEY }} app-file: env: | USERNAME=${{ secrets.TEST_USERNAME }} PASSWORD=${{ secrets.TEST_PASSWORD }} ### [](https://docs.maestro.dev/cloud/reference/managing-secrets#using-variables-in-your-flows) Using variables in your flows Once you have defined the variables, you can refer to them in your flows: Copy appId: your.app.id --- - launchApp - inputText: ${USERNAME} - tapOn: Next - inputText: ${PASSWORD} [PreviousWebhook Integration](https://docs.maestro.dev/cloud/reference/webhook-integration) [NextLimits](https://docs.maestro.dev/cloud/reference/limits) Last updated 7 months ago Was this helpful? Was this helpful? --- # Supported Platforms | Maestro ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-3a7f68afaa04ae6b31d3567d078fbe7581ae58a6%252FAll%2520Banner%2520%285%29.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=e914fdf1&sv=2) Maestro supports all of the major mobile development platforms as well as desktop browsers. Check out the guides below to learn how to interact with UI elements on each framework. Platform Supported [Android - Views](https://docs.maestro.dev/platform-support/android-views) βœ… [Android - Jetpack Compose](https://docs.maestro.dev/platform-support/android-jetpack-compose) βœ… [iOS - UIKit](https://docs.maestro.dev/platform-support/ios-uikit) βœ… [iOS - SwiftUI](https://docs.maestro.dev/platform-support/ios-swiftui) βœ… [React Native](https://docs.maestro.dev/platform-support/react-native) βœ… [Flutter](https://docs.maestro.dev/platform-support/flutter) βœ… [Web Views](https://docs.maestro.dev/platform-support/web-views) βœ… [Web (Desktop Browser)](https://docs.maestro.dev/platform-support/web-desktop-browser) βœ… .NET MAUI iOS βœ… .NET MAUI Android βœ… [PreviousIP Allowlist](https://docs.maestro.dev/cloud/reference/ip-allowlist) [NextAndroid - Views](https://docs.maestro.dev/platform-support/android-views) Last updated 10 months ago Was this helpful? Was this helpful? --- # Limits | Maestro πŸš€ **Cloud Plan** required - get started for free at [**maestro.dev**](https://signin.maestro.dev/sign-up) ### [](https://docs.maestro.dev/cloud/reference/limits#execution-limit-soft-limit) Execution limit (soft limit) There is a soft limit of 15 minutes, which means that after 15 minutes of execution your test may be stopped at any time after that. [PreviousManaging Secrets](https://docs.maestro.dev/cloud/reference/managing-secrets) [NextReusing App Binary](https://docs.maestro.dev/cloud/reference/reusing-app-binary) Last updated 7 months ago Was this helpful? Was this helpful? --- # Android - Views | Maestro ![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F2384395183-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fn5KVIOjVkVjYRyVWZ0yT%252Fuploads%252Fgit-blob-291c13ce7e9b39bc1968633586936ea6be6ba94f%252Fandroid.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=54e242d4&sv=2) Maestro fully supports native Android apps. Maestro tests can also run on real hardware devices. [https://github.com/mobile-dev-inc/maestro-docs/blob/main/platform-support/broken-reference/README.md](https://github.com/mobile-dev-inc/maestro-docs/blob/main/platform-support/broken-reference/README.md) [](https://docs.maestro.dev/platform-support/android-views#interacting-with-views-by-text) Interacting with views by text ------------------------------------------------------------------------------------------------------------------------------ Any view with a `text` property can be tapped on: Can be tapped in the following way: [](https://docs.maestro.dev/platform-support/android-views#interacting-with-views-by-id) Interacting with views by id -------------------------------------------------------------------------------------------------------------------------- Views can be accessed by their ids. For example: Can be tapped in the following way: [](https://docs.maestro.dev/platform-support/android-views#interacting-with-views-by-contentdescription) Interacting with views by contentDescription ---------------------------------------------------------------------------------------------------------------------------------------------------------- `contentDescription` field is surfaced as text property and can be interacted in the same way as any view containing `text`: This view can then be tapped using the following command: [](https://docs.maestro.dev/platform-support/android-views#known-limitations) Known Limitations ---------------------------------------------------------------------------------------------------- 1. Unicode text **input** is not yet currently supported. Though views that have unicode in them can still be interacted with. [PreviousSupported Platforms](https://docs.maestro.dev/platform-support/supported-platforms) [NextAndroid - Jetpack Compose](https://docs.maestro.dev/platform-support/android-jetpack-compose) Last updated 1 year ago Was this helpful? * [Interacting with views by text](https://docs.maestro.dev/platform-support/android-views#interacting-with-views-by-text) * [Interacting with views by id](https://docs.maestro.dev/platform-support/android-views#interacting-with-views-by-id) * [Interacting with views by contentDescription](https://docs.maestro.dev/platform-support/android-views#interacting-with-views-by-contentdescription) * [Known Limitations](https://docs.maestro.dev/platform-support/android-views#known-limitations) Was this helpful? Copy