Run tests on Maestro Cloud

Upload and execute your Maestro tests on Cloud infrastructure using the CLI.

Running your tests on Maestro Cloud provides reliable scaling, guaranteed parallelism, and seamless CI integration for your mobile and web applications.

This guide explains how to execute your tests using Maestro Cloud via the Maestro CLI.

Prerequisites

Before running tests on Maestro Cloud, ensure you have the following:

• Maestro account: Sign up for a Maestro account.

• Cloud plan: Maestro Cloud requires a Cloud plan, which you can start as a trial from the Maestro Dashboard.

• Maestro CLI: Install the Maestro CLI on your local machine or CI environment.

Test your app

When testing your app, you also need the app binary for Android (ARM APK) or iOS (simulator .app bundle). If you don’t know how to build your app, check the Build your app for the cloud guide.

Command syntax

Use the maestro cloud command to upload your app and execute your flows. This command can be used both for local testing and within CI pipelines.

maestro cloud [options] --app-file <app-file> --flows <flow-file-or-directory>

Run Flows on the Cloud

The Maestro CLI provides sample files to help you get started quickly. Use the download-samples command to download a sample app and Flow file:

maestro download-samples

You can upload your own app and Flow files, but we recommend using the samples first to understand how it works.

After running the command, the Maestro CLI downloads a folder containing a set of Flows into your current directory. You can use the included app builds to test both Android and iOS apps:

Android

To run an Android test using the sample app and Flow, run the following command:

cd samples
maestro cloud --app-file sample.apk --flows android-flow.yaml

iOS

After a successful upload, the CLI prints a link to the Maestro Console.

1. Click the provided link to open the console.

2. Test processing may take a few minutes depending on your other uploads and how many runners are configured on your account.

3. Review the test results, including videos, logs, and hierarchy data.

Authentication and project selection

If you belong to multiple organizations or projects, use the following flags to avoid interactive prompts:

• --api-key: Your Maestro Cloud API key.

• --project-id: The specific project ID for the upload.

The following example demonstrates how to use these flags:

maestro cloud --api-key <YOUR_API_KEY> --project-id <YOUR_PROJECT_ID> --app-file sample.apk --flows flow.yaml

For a complete list of cloud command options, see the Maestro CLI reference.

Next steps

After verifying your cloud execution, learn how to build your app or integrate Maestro Cloud into your development workflow:

• CI/CD Integration: Automate your tests using GitHub Actions, Bitrise, CircleCI, and more.

• Advanced features: Manage secrets, configure locales, and use IP allowlists.