Migrate from Maestro Cloud to TestingBot

Maestro flows are plain YAML and are not tied to any one runner. If you already run them on Maestro Cloud, moving them to TestingBot is a change of upload command and device flags, not a rewrite. Your flow files, your tags and your Maestro syntax stay as they are.

This page maps every maestro cloud option to its TestingBot equivalent, so you can port a working pipeline in one sitting.

Before you start

Install the TestingBot CLI and authenticate once:

npm install -g @testingbot/cli
testingbot login

Credentials are stored in ~/.testingbot. In CI, pass --api-key and --api-secret, or set TB_KEY and TB_SECRET as secrets.

Command mapping

The whole migration in one line. On Maestro Cloud:

maestro cloud --app-file app.apk --flows ./flows

On TestingBot:

testingbot maestro app.apk ./flows --device "Pixel 8" --deviceVersion "14"

The app binary and the flows are positional arguments rather than named flags. Everything the flows directory can contain stays the same, and you can pass a directory, several directories, individual flow files, or a pre-zipped bundle:

# A directory of flows
testingbot maestro app.apk ./flows

# Several directories
testingbot maestro app.apk ./flows/smoke ./flows/regression

# Individual flow files
testingbot maestro app.apk login.yaml checkout.yaml

# A pre-zipped bundle
testingbot maestro app.apk flows.zip

Flag mapping

Every maestro cloud option and what to use instead. Flag names that are identical on both sides are marked, so you can leave those parts of your command untouched.

TestingBot adds flags that have no maestro cloud counterpart, including --real-device, --tunnel, --orientation, --timezone, --geo-country-code, --throttle-network, --download-artifacts and --maestro-version. They are documented in Maestro options.

Device and OS selection

Maestro Cloud selects an environment with a single combined string, for example --device-os "android-34", or an OS plus model pair on iOS. TestingBot splits that into a device name and a version:

# Android
testingbot maestro app.apk ./flows --device "Pixel 8" --deviceVersion "14"

# iOS simulator
testingbot maestro app.ipa ./flows --device "iPhone 16" --deviceVersion "18.6" --platform "iOS"

# Physical iPhone
testingbot maestro app.ipa ./flows --device "iPhone 16" --real-device

Add --real-device to run on physical hardware instead of a simulator or emulator. The full list of device names and versions is on Maestro options.

Tags and environment variables

These copy across unchanged, both the flag names and their behaviour:

testingbot maestro app.apk ./flows \
  --device "Pixel 8" \
  --include-tags smoke,checkout \
  --exclude-tags flaky \
  --env USERNAME=demo --env BASE_URL=https://staging.example.com

Tags still come from the tags: block in your flow files, so no flow edits are needed.

Reports and artifacts

Maestro Cloud writes a report with --format and --output. TestingBot uses a report type and an output directory:

testingbot maestro app.apk ./flows --device "Pixel 8" \
  --report junit \
  --report-output-dir ./reports

Video, logs and screenshots can be pulled down in the same run:

testingbot maestro app.apk ./flows --device "Pixel 8" \
  --download-artifacts \
  --artifacts-output-dir ./artifacts

Running flows in parallel

Split a flows directory across concurrent sessions with --shard-split. Your plan's concurrency decides how many run at once:

# Three parallel sessions
testingbot maestro app.apk ./flows \
  --device "Pixel 8" --deviceVersion "14" --shard-split 3

# Everything in one session
testingbot maestro app.apk ./flows \
  --device "Pixel 8" --deviceVersion "14" --shard-split 1

CI/CD

The CI metadata flags keep the same names, so the parts of your pipeline that tag a run with a branch, commit or pull request need no edits:

npx --yes @testingbot/cli@latest maestro app.apk ./flows \
  --device "Pixel 8" \
  --deviceVersion "14" \
  --api-key $TB_KEY \
  --api-secret $TB_SECRET \
  --repo-owner "$GITHUB_REPOSITORY_OWNER" \
  --commit-sha "$GITHUB_SHA"

Ready-made GitHub Actions, GitLab CI, Jenkins, CircleCI and Bitbucket Pipelines examples are on Maestro CI/CD integration. If your app talks to a staging environment that is not reachable from the internet, see local and staging testing.

What differs

Worth knowing before you port a pipeline:

• Two positional arguments. The app and the flows are passed by position rather than through --app-file and --flows.
• Device and version are separate flags. There is no single combined --device-os string.
• Authentication is a key and secret pair, not a single API key.
• Real hardware is opt-in with --real-device.
• Reports are configured by type and directory rather than format and file path.

Frequently asked questions

Do I have to rewrite my Maestro flows to run them on TestingBot?

No. Flows are plain Maestro YAML and run unchanged. What changes is the command that uploads and runs them, and the flags that pick a device. Your flow files, tags and Maestro syntax stay exactly as they are.

What replaces the maestro cloud command on TestingBot?

The TestingBot CLI: testingbot maestro <app> <flows>. See the command mapping for a side-by-side, and the flag mapping for every option.

How do I pick a device and OS version on TestingBot?

With --device and --deviceVersion, instead of a single combined --device-os string. Add --real-device to run on physical hardware rather than a simulator or emulator. See device and OS selection.

Can I keep my --include-tags and --exclude-tags filters?

Yes, both flags exist on the TestingBot CLI under the same names and behave the same way, so tag filters copy across unchanged. See tags and environment variables.

Will my CI pipeline still publish JUnit reports?

Yes. Where Maestro Cloud uses --format and --output, TestingBot uses --report junit and --report-output-dir. The CI metadata flags for branch, commit and pull request keep the same names. See reports and artifacts.

Run your existing Maestro flows on TestingBot with a free trial, or read why teams choose us on the Maestro Cloud alternative page.