Running Maestro on BrowserStack: Guide (+

Maestro has become the go-to framework for teams tired of flaky mobile UI tests. Simple YAML syntax, built-in retry logic, and cross-platform support make it appealing—especially when compared to traditional frameworks like Appium (see our Maestro vs Appium comparison). So when you need to run tests at scale, BrowserStack’s Maestro support seems like a natural choice.

Before you commit, here’s what you should know.

It’s Still in Beta

For a deep dive on the version gap specifically, see BrowserStack Maestro Version Gap & iOS Reality.

BrowserStack’s Maestro support is marked as Beta in their documentation:

“Maestro support on BrowserStack App Automate is currently in Beta.”

This isn’t hidden—it’s right on their getting started page. But it’s easy to miss when you’re focused on getting tests running.

What does Beta mean in practice? Expect:

• Features that may change without notice
• Limited support options compared to their stable products
• Potential gaps in documentation
• Commands that work locally but fail in their environment

If your team needs production-grade stability, factor this into your decision.

Version Lock: 1.39.13

BrowserStack supports Maestro version 1.39.13.

The current Maestro release is 2.0.10.

That’s not a minor version gap. Maestro 2.0 introduced:

• GraalJS engine: Modern JavaScript support replacing the outdated Rhino engine
• Java 17 requirement: Better performance and security
• New commands: assertWithAI, setOrientation, improved sharding
• Bug fixes: Months of stability improvements

If you’re writing Maestro tests locally with version 2.x, you may encounter compatibility issues when running on BrowserStack. Features you rely on locally might not exist in their environment.

Check your local version:

maestro --version

If it shows 2.x, you’re writing tests against a newer API than BrowserStack supports.

Three API Calls Minimum

Running Maestro tests on BrowserStack isn’t maestro test flow.yaml. It’s a multi-step process:

Step 1: Upload Your App

curl -u "username:accessKey" \
  -X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/app" \
  -F "file=@/path/to/app.apk" \
  -F "custom_id=MyApp"

Response includes an app_url like bs://c8ddcb5649a8280ca800075bfd8f151115bba6b3.

Step 2: Upload Your Test Suite

Your flows need to be zipped with a specific folder structure (more on that below):

curl -u "username:accessKey" \
  -X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/test-suite" \
  -F "file=@/path/to/tests.zip" \
  -F "custom_id=MyTests"

Response includes a test_suite_url like bs://89c874f21852ba57957a3fdc33f47514288c4ba1.

Step 3: Execute the Build

curl -u "username:accessKey" \
  -X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "bs://c8ddcb5649...",
    "testSuite": "bs://89c874f21...",
    "devices": ["Samsung Galaxy S23-13.0"]
  }'

Compare this to running Maestro locally:

maestro test flow.yaml

The orchestration overhead is significant. Every CI run needs to handle uploads, track hashes, and manage the build lifecycle.

The Zip Structure Problem

BrowserStack requires a specific folder structure for your test suite. From their documentation:

“Incorrect folder structure may cause Maestro to fail in locating your flow files, resulting in test execution failures.”

The rules:

1. All files must be inside a single parent folder
2. Even a single flow file needs a parent folder
3. Without a root folder, tests fail

Correct structure:

test_suite/           ← Parent folder required
├── flow1.yaml
├── flow2.yaml
└── common/
    └── login.yaml

Incorrect structure (will fail):

flow1.yaml            ← No parent folder
flow2.yaml
common/
└── login.yaml

Your CI pipeline needs to handle this:

# Create proper structure
mkdir -p test_suite
cp -r flows/* test_suite/
zip -r tests.zip test_suite

# Upload
curl ... -F "[email protected]"

# Cleanup
rm -rf test_suite tests.zip

If your tests work locally but fail on BrowserStack with “Maestro to fail in locating your flow files,” this is likely the culprit.

App URLs Expire in 30 Days

When you upload an app to BrowserStack, you receive a bs:// URL. This URL expires in 30 days.

From their API response:

{
  "app_url": "bs://c8ddcb5649a8280ca800075bfd8f151115bba6b3",
  "expiry": "2025-01-25 14:52:54 UTC"
}

Options for handling this:

1. Re-upload on every CI run: Adds time but ensures freshness
2. Use custom_id: Reference by name instead of hash, but still requires periodic refresh
3. Track expiry dates: Build automation to re-upload before expiry

None of these are complex, but they’re additional infrastructure you’ll need to maintain.

Some Commands Aren’t Supported

BrowserStack’s documentation includes this note:

“While some Maestro commands are not supported on BrowserStack, you can achieve the same functionality using BrowserStack’s APIs.”

This means:

• Some Maestro commands require workarounds
• You may need to modify tests specifically for BrowserStack
• Tests that pass locally might need adjustments

Check their supported commands documentation before assuming your test suite will run as-is.

iOS Below Version 15 Not Supported

From their documentation:

“iOS devices below version 15 are not supported.”

If you need to test on iOS 14 or earlier, BrowserStack’s Maestro support won’t cover those devices.

The Local Testing Requirement

If your app talks to staging servers behind a firewall, you’ll need BrowserStack Local:

“Is your web app under test hosted in a local environment? In that case, you have to create a secure tunnel between your web app and BrowserStack first.”

This adds another moving part:

1. Download and run the BrowserStack Local binary
2. Configure the tunnel
3. Add "local": "true" to your API requests
4. Handle tunnel stability in CI

Teams often report tunnel-related flakiness. The tunnel can drop mid-test, DNS resolution behaves differently, and SSL certificates for internal services may fail.

What Works Well

To be fair, BrowserStack’s Maestro support does provide value:

• Real device access: Test on actual Samsung, Pixel, and iPhone hardware
• Parallel execution: Run tests across multiple devices simultaneously
• Logs and video: Debug failures with recordings and detailed logs
• No device maintenance: Skip the overhead of managing physical devices

For teams that need cloud device access and can work within the constraints, it’s a viable option.

Questions to Ask Before Starting

1. Version compatibility: Are you using Maestro 2.x features that don’t exist in 1.39?
2. CI complexity: Can your pipeline handle the upload → zip → execute workflow?
3. Local testing needs: Do your tests hit internal servers that require tunneling?
4. iOS coverage: Do you need devices running iOS 14 or earlier?
5. Beta tolerance: Is your team comfortable with a Beta product in your test pipeline?

Alternatives to Consider

If the constraints above are deal-breakers, consider:

Maestro Cloud (Official)

The official cloud from mobile.dev. Pricing is $250/device/month for iOS/Android. Supports latest Maestro versions since it’s from the Maestro team.

Your Own Devices

Run Maestro on devices you own. No API calls, no zip structures, no version lock. You control the Maestro version and have direct access to your staging environment. Tools like DeviceLab let you connect your own devices and run tests remotely while keeping data on your network. For migration steps, see our Maestro migration guide. Also explore BrowserStack pricing and the hidden costs most teams miss to understand if you’re getting value for money.

AWS Device Farm / Firebase Test Lab

Both support custom test frameworks. Requires more setup but offers flexibility.

Summary

BrowserStack’s Maestro support can work, but go in with realistic expectations:

If these constraints fit your workflow, BrowserStack provides legitimate value with real device access and parallel execution.

If they don’t, explore alternatives before you’ve invested in building pipelines around these limitations.

Frequently Asked Questions

What version of Maestro does BrowserStack support?

BrowserStack supports Maestro version 1.39.13, while the current Maestro release is 2.0.10. This means features like the GraalJS engine, assertWithAI, and other 2.x improvements aren’t available on BrowserStack.

Is BrowserStack Maestro support production-ready?

No. BrowserStack’s Maestro support is marked as Beta in their documentation. Expect features that may change, limited support options, and potential gaps in documentation.

How do I run Maestro tests on BrowserStack?

Running Maestro on BrowserStack requires 3 API calls: upload your app, upload your test suite as a zip with specific folder structure, then execute the build. It’s not as simple as running maestro test flow.yaml locally.

Why do my Maestro tests fail on BrowserStack but work locally?

Common causes: wrong zip folder structure (tests must be inside a parent folder), using Maestro 2.x features not supported in 1.39, or unsupported commands. Check BrowserStack’s supported commands documentation.

Does BrowserStack Maestro support iOS 14?

No. BrowserStack’s Maestro support only works on iOS devices running version 15 or later. iOS 14 and earlier are not supported.

Running Maestro tests? See how DeviceLab handles Maestro — same YAML, your devices, no API orchestration.