Running Maestro Tests on BrowserStack: Complete Guide

Maestro testing is gaining adoption among QA teams because of how easy it is to create and maintain reliable mobile app automation flows.

This article explains how to run Maestro tests on BrowserStack and why it adds value for mobile testing.

What is Maestro Mobile Testing Framework?

Maestro is an open-source mobile UI automation framework for Android and iOS apps. It removes the complexity of traditional automation tools by allowing testers to define test flows in YAML. This makes test scripts more readable and easier to maintain.

The framework replicates real user interactions such as taps, swipes, text input, and scrolling. It can handle dynamic UI elements and delays without breaking test execution. Its flow-oriented design organizes tests around user journeys rather than individual actions.

Why is Maestro Framework Popular Among Testers?

Maestro has gained rapid adoption because it allows teams to create stable, maintainable test flows without requiring extensive coding skills. Testers spend less time fixing fragile test scripts and more time validating core functionality.

Here are some reasons why it is considered important in modern mobile testing:

• Reliable handling of dynamic elements: Maestro can detect and interact with UI elements even when their positions, animations, or properties change, reducing flaky test failures.

• Cross-platform consistency: A single test flow works on Android and iOS, saving effort in maintaining separate test suites and ensuring feature parity across platforms.

• Readable and maintainable test flows: YAML structure allows teams to document test logic in a human-readable format, making it easy for QA engineers, developers, and product managers to understand and update tests.
• User journey-focused automation: Tests are structured around real-world workflows rather than isolated actions, ensuring critical user paths are validated end-to-end.
• Integration with CI/CD pipelines: Maestro tests can be automated to run with every code change, providing fast feedback and supporting continuous delivery practices.

• Open-source adaptability and community support: Teams can extend the framework, contribute enhancements, and leverage community-driven plugins or best practices.

Maestro Framework Architecture

Maestro is designed with a modular, flow-based architecture that focuses on simplicity, readability, and scalability. Its structure separates test definition, execution, and device interaction into distinct layers. This allows teams to build automation that is both maintainable and adaptable to changes in the app or platform.

The main components of Maestro’s architecture include:

• Test Flow Layer: This is where YAML-based test flows are defined. Each flow represents a sequence of user interactions and validations, organized around real-world workflows. Testers can break flows into reusable segments for better maintainability.
• Action Engine: Responsible for interpreting each step in the test flow and executing it on the target device. It handles gestures, text input, scrolling, and navigation, ensuring that tests mimic real user behavior.
• Locator and Selector System: Maestro identifies UI components using a combination of accessibility IDs, labels, and hierarchies. This system allows tests to remain stable even when UI layouts change and reduces the chances of flaky tests.

• Platform Abstraction Layer: Provides a consistent interface for both Android and iOS. Testers can write one flow that runs across platforms, while Maestro handles platform-specific interactions behind the scenes.
• Execution and Reporting Layer: Handles the execution of test flows and provides structured feedback. It logs each action, records failures, and enables integration with CI/CD tools, making debugging and test monitoring more efficient.

Maestro vs Other Mobile Testing Frameworks

Understanding how Maestro differs from traditional frameworks like Appium, Espresso, and XCUITest helps teams choose the right tool for mobile automation. The table below highlights key differences in usability, stability, and scalability.

Does BrowserStack App Automate Support Maestro?

Yes, BrowserStack App Automate supports running Maestro tests on a wide range of real Android and iOS devices. This allows teams to validate apps in conditions that closely resemble real-world usage, including different OS versions, screen sizes, and network conditions.

Using the Maestro API, testers can integrate their existing test flows into BrowserStack’s infrastructure. The API follows standard REST conventions, enabling automation at scale and seamless connection with CI/CD pipelines.

This reduces the need to manage physical devices in-house while providing reliable, consistent test results across multiple devices simultaneously.

Setting Up Maestro Testing on BrowserStack

Setting up Maestro tests on BrowserStack involves preparing your app, organizing your test suite correctly, and ensuring your test environment is configured for smooth execution.

Step 1: Prepare Your Mobile App

Before running any tests, your Android (.apk) or iOS (.ipa) app must be uploaded to BrowserStack. This ensures that the app is available on real devices for execution. Make sure you have your BrowserStack username and access key ready for authentication.

Example cURL command to upload an app:

curl -u “username:accessKey” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/app”

-F “file=@/path/to/app/file/debug.apk”

-F “custom_id=SampleApp”

After uploading, note the app_url returned by BrowserStack. This URL uniquely identifies your uploaded app for test execution.

Step 2: Structure Your Maestro Test Suite

A correctly structured test suite is essential for successful execution. All your test files, subfolders, and related assets must be placed inside a single parent folder. Then zip this parent folder for upload. Even if you only have one flow file, it must reside inside a parent folder.

Step 3: Upload Your Maestro Test Suite

Once your suite is correctly structured, upload it to BrowserStack. The suite should be a single .zip file containing your parent folder. Make sure the .zip includes only the parent folder, not loose files.

Example cURL command:

curl -u “username:accessKey” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/test-suite”

-F “file=@/path/to/test-suite.zip”

-F “custom_id=SampleTest”

After upload, note the test_suite_url returned by BrowserStack.

Step 4: Configure Your Test Environment

Setting up your test environment ensures tests run reliably across devices. Maestro allows you to define debugging options, organize tests, and control how your app interacts with the UI.

Key configurations to set:

• Organize tests under a single project to simplify management.
• Enable debugging options such as logs, screenshots, and video recordings.
• Ensure devices you intend to test on are supported and available in BrowserStack.

Step 5: Verify Setup Before Execution

Before running your tests, verify:

• Your app is uploaded and accessible via the app_url.
• The test suite is zipped correctly with a parent folder.
• Debugging options and devices are configured properly.

Running Maestro Tests Using BrowserStack API

Once your app and Maestro test suite are uploaded, you can run Maestro tests on BrowserStack. This allows automated execution on real devices directly through App Automate.

Step 1: Initiate a Test Build

To start a build, include the uploaded app URL, test suite URL, and the target devices in your API request. Each build will return a unique build_id, which you can use to track the execution.

Example for Android:

curl -u “USERNAME:ACCESS_KEY” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build”

-H “Content-Type: application/json”

-d ‘{

“app”: “bs://your_app_url”,

“testSuite”: “bs://your_test_suite_url”,

“project”: “Maestro_Test”,

“devices”: [

“Samsung Galaxy S20-10.0”,

“Google Pixel 3-9.0”

]

}’

Example for iOS:

curl -u “USERNAME:ACCESS_KEY” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/ios/build”

-H “Content-Type: application/json”

-d ‘{

“app”: “bs://your_app_url”,

“testSuite”: “bs://your_test_suite_url”,

“networkLogs”: “true”,

“deviceLogs”: “true”,

“devices”: [“iPhone 15-17.0”],

“execute”: [“path/to/flowfile.yml”, “path/to/flowfolder”]

}’

• The execute parameter allows running specific files or entire folders within your test suite. Paths are relative to the parent folder.
• Optional parameters such as networkLogs and deviceLogs enable additional debugging information.

Step 2: Monitor and Manage Builds

After initiating a build, you can monitor the progress via the App Automate dashboard or the API. You can view live test results, video recordings, and debugging logs for each device.

• Each build is associated with a build_id that can be used to query status.
• If a test run stops unexpectedly, builds can be stopped via the dashboard or API.
• Detailed execution logs help trace failures and optimize test flows.

Step 3: Execute Tests Locally (Optional)

If your app is hosted on a local or internal server, configure Local Testing. Start the BrowserStack Local binary before initiating the API request, then include “local”: “true” in your build configuration.

Example for Android with local testing:

curl -u “USERNAME:ACCESS_KEY” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build”

-H “Content-Type: application/json”

-d ‘{

“local”: “true”,

“devices”: [“Samsung Galaxy S8-7.0”],

“app”: “bs://your_app_url”,

“testSuite”: “bs://your_test_suite_url”

}’

Step 4: Parallel Test Execution

To accelerate test runs, you can execute parallel tests across multiple devices. Each device runs the suite independently, reducing total execution time while consuming one license per device.

Example for Android:

curl -u “USERNAME:ACCESS_KEY” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build”

-H “Content-Type: application/json”

-d ‘{

“devices”: [“Google Pixel 3-9.0”, “Samsung Galaxy S10e-9.0”],

“app”: “bs://your_app_url”,

“testSuite”: “bs://your_test_suite_url”

}’

Example for iOS:

curl -u “USERNAME:ACCESS_KEY” -X POST “https://api-cloud.browserstack.com/app-automate/maestro/v2/ios/build”

-H “Content-Type: application/json”

-d ‘{

“devices”: [“iPhone 10-17.0”, “iPhone 15-17.0”],

“app”: “bs://your_app_url”,

“testSuite”: “bs://your_test_suite_url”

}’

• Tests within each device run sequentially.
• Parallelization improves speed and scales test coverage efficiently.

Step 5: View Results and Debug

Once execution is complete, the App Automate dashboard displays:

• Live results for each device
• Network, device, and video logs for debugging
• Detailed execution summary for all flows

Why Choose BrowserStack for Maestro Testing

Using BrowserStack to run Maestro tests adds significant value by simplifying access to real devices, improving test reliability, and enabling scalable automation. It ensures that mobile apps are validated across a wide range of devices and OS versions without the overhead of managing physical hardware.

Key benefits include:

• Real Device Cloud: Run tests on thousands of iOS and Android devices to ensure accurate results across different screen sizes, OS versions, and hardware configurations.
• Parallel Testing: Execute tests in parallel across multiple devices, reducing overall testing time and speeding up release cycles.
• Enhanced Debugging: Access detailed logs, video recordings, and network traces to quickly identify issues and ensure high-quality releases.
• CI/CD Integration: Integrate Maestro tests seamlessly into existing pipelines, enabling continuous testing with immediate feedback on code changes.

Talk to an Expert

Conclusion

Maestro testing on real devices ensures mobile apps work correctly across different devices and OS versions. Testing on actual hardware helps uncover device-specific issues and validate UI interactions reliably.

BrowserStack enhances Maestro testing with instant access to thousands of real iOS and Android devices, scalable parallel execution, detailed logs and videos, and seamless CI/CD integration. This accelerates app delivery while ensuring thorough quality assurance.

Try BrowserStack App Automate