Build your app for the cloud
Build Android APKs and iOS .app bundles for Simulator to run on Maestro Cloud.
Before you can execute tests on Maestro Cloud, you must provide a mobile application binary (APK or .app directory). This page provides the specific technical requirements and build instructions for the most common development environments to ensure your app is compatible with Maestro's cloud infrastructure.
Project-specific build requirements
The instructions on this page cover typical ways to build mobile applications. However, your project may have unique pipelines, specific command-line switches, or environment configurations (e.g., specialized Expo or React Native build scripts).
We recommend checking your project's README, internal developer documentation, or the official documentation for your chosen framework for exact build steps.
This feature requires a Cloud plan. Start for free at maestro.dev.
Android build instructions
Maestro Cloud now uses ARM architectures for Android. Ensure your app binary meets the following requirements:
Format: APK only. Android App Bundles (.aab) are not currently supported.
Architecture: Must be compatible with ARM or be a multi-architecture build. x86-only APKs will fail to launch in the cloud environment.
Build Type: Both Release and Debug builds are supported.
To build your app, use one of the following approaches:
Run the following commands from your project root to generate the APK.
# To generate a Debug build
./gradlew assembleDebug
# To generate a Release build
./gradlew assembleReleaseOnce finished, find the file in the app/build/outputs/apk/ directory.
Use the Flutter CLI to create a compatible APK. You can use anyone of the following commands:
# Debug build (Recommended for initial testing)
flutter build apk --debug
# Release build
flutter build apkThe result will be located in the build/app/outputs/flutter-apk/ folder.
iOS build instructions
Maestro Cloud runs iOS tests on Simulators. Do not upload binaries built for physical iOS devices.
Format:
.appbundle.Target: Must be built for the iOS Simulator.
To build your app, use one of the following options:
Use the xcodebuild command to create a simulator build. The following example builds a project named MyApp and saves the output to a build/ folder:
The .app bundle will be available in the build/ directory.
If you use Fastlane for automation, the script should look the following one to generate the app file:
Use the following command to create a simulator-compatible debug build:
The app bundle is located in the build/ios/iphonesimulator/ directory.
Run the build
Once your binary is ready, you can upload it to Maestro Cloud using the Maestro CLI or Maestro Studio:
Use the command:
You can choose to run all or a single Flow on Maestro Cloud:
Run all Flows: Click on the Run on Cloud button in the sidebar and then select your app binary.
Run a single Flow: Open the Flow file, click on the Run on Cloud button at the top of the file, and then select your app binary.
Next steps
Now that you know how to build your app, you can explore one of the following guide categories to improve your use of Maestro Cloud:
CI/CD integration: Move your tests out of your local terminal and into your deployment pipeline.
Environment configuration: Customize the cloud hardware to match your users' real-world conditions.
Notifications: Set up Slack, Email, or Webhooks to keep your team informed of every pass or failure.
Advanced features: Use binary reuse to speed up iterations and manage secrets via environment variables.
If you haven’t tested the Maestro CLI yet, check the Run tests on Maestro Cloud guide.
Last updated