Maestro Test Options

When running Maestro tests on TestingBot, you can customize the test execution using various options. These options are passed when starting a test run via the API.

Options are organized into two categories:

• maestroOptions: Options specific to Maestro execution (version, environment variables, flows, tags)
• capabilities: Device and test configuration options (device, orientation, locale, network, etc.)

Quick Reference

All available options at a glance:

Maestro Options

Capability Options

Set Maestro Version

Unless you pin one, TestingBot runs your flows with Maestro 2.6.0. This is a known-good default rather than the newest release, so pin a version explicitly if you need a specific one.

These versions can be pinned:

• 2.10.0, 2.9.0, 2.8.0, 2.7.0
• 2.6.1, 2.6.0 (default), 2.5.0, 2.4.0
• 2.3.0, 2.0.10

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

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "maestroOptions": {
    "version": "2.0.10"
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Select Specific Flows

By default, TestingBot runs every flow file in your zip archive, one device session per flow. To run only some of them, use the option below. Flows you filter out are not scheduled at all, so they do not consume a session.

Each entry is matched against the path of the flow inside your archive, and can be:

• the full path, for example flows/smoke/login.yml
• just the file name, for example login.yml
• a directory, which selects every flow inside it, for example flows/smoke

Use Cases

• Run a subset of flows for faster feedback during development
• Execute specific test scenarios without modifying your test suite
• Re-run failed flows without running the entire suite

# Run specific flow files
testingbot maestro app.apk login.yml checkout.yml --device "Pixel 8"

# Run flows from a specific directory
testingbot maestro app.apk ./flows/smoke --device "Pixel 8"

# Mix directories and individual files
testingbot maestro app.apk ./flows/smoke login.yml --device "Pixel 8"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "maestroOptions": {
    "flows": ["login.yml", "checkout.yml"]
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Environment Variables

Pass environment variables to your Maestro flows using the env option. This is useful for configuration that varies between environments (staging, production) or for sensitive data like API keys.

Use Cases

• Environment-specific URLs: Point to staging or production backends
• Test credentials: Pass login credentials securely via CI/CD
• Feature flags: Enable or disable features during tests
• App identifiers: Specify package names or bundle IDs dynamically

testingbot maestro app.apk ./flows --device "Pixel 8" \
  -e API_URL=https://staging.example.com \
  -e TEST_USER=testuser@example.com \
  -e TEST_PASSWORD=secret123

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "maestroOptions": {
    "env": {
      "API_URL": "https://staging.example.com",
      "TEST_USER": "testuser@example.com",
      "TEST_PASSWORD": "secret123"
    }
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Using Variables in Your Flows

Reference environment variables in your Maestro flow files using the ${VARIABLE_NAME} syntax:

appId: com.example.app
---
- launchApp
- inputText:
    text: "${TEST_USER}"
- tapOn: "Next"
- inputText:
    text: "${TEST_PASSWORD}"
- tapOn: "Login"

Include Tags

Run only flows that have specific tags. This is equivalent to Maestro's --include-tags option.

Adding Tags to Flows

Add tags to your flow files using the tags property:

appId: com.example.app
tags:
  - smoke
  - login
---
- launchApp
- tapOn: "Login"

testingbot maestro app.apk ./flows --device "Pixel 8" \
  --include-tags "smoke,critical"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "maestroOptions": {
    "includeTags": ["smoke", "critical"]
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Exclude Tags

Skip flows that have specific tags. This is equivalent to Maestro's --exclude-tags option. Unlike includeTags, flows with no tags are kept.

You can combine the two. includeTags is applied first and excludeTags second, so a flow tagged both smoke and flaky is skipped by "includeTags": ["smoke"], "excludeTags": ["flaky"].

Use Cases

• Skip slow tests during development for faster feedback
• Exclude known flaky tests from CI pipelines
• Skip platform-specific tests (e.g., exclude "ios-only" when running on Android)

testingbot maestro app.apk ./flows --device "Pixel 8" \
  --exclude-tags "slow,flaky"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "maestroOptions": {
    "excludeTags": ["slow", "flaky"]
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

IP Geolocation

Test your app from different geographic locations using TestingBot's GeoIP feature. Traffic from the device will route through an IP address in the specified country.

Use Cases

• Test geo-restricted content or features
• Verify location-based pricing or currency display
• Test localized content delivery

testingbot maestro app.zip ./flows \
  --platform iOS \
  --device "iPhone 15" \
  --deviceVersion "17.2" \
  --geo-country-code "DE"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "iOS",
    "version": "17.2",
    "deviceName": "iPhone 15",
    "testingbot.geoCountryCode": "DE"
  }]
}' \
-H "Content-Type: application/json"

Network Throttling

Simulate different network conditions to test how your app performs under various connectivity scenarios.

Network Presets

testingbot maestro app.zip ./flows \
  --platform iOS \
  --device "iPhone 15" \
  --deviceVersion "17.2" \
  --throttle-network "3G"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "iOS",
    "version": "17.2",
    "deviceName": "iPhone 15",
    "throttle_network": "3G"
  }]
}' \
-H "Content-Type: application/json"

Test Name

Set a custom name for your test that appears in the TestingBot dashboard. This makes it easier to identify specific test runs.

testingbot maestro app.zip ./flows \
  --platform iOS \
  --device "iPhone 15" \
  --deviceVersion "17.2" \
  --name "Login Flow - Smoke Test"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "iOS",
    "version": "17.2",
    "deviceName": "iPhone 15",
    "name": "Login Flow - Smoke Test"
  }]
}' \
-H "Content-Type: application/json"

Build Grouping

Group multiple test runs under a single build name. This is useful for organizing tests that belong to the same CI/CD pipeline run or release version.

Benefits

• View aggregated pass/fail statistics for all tests in a build
• Track test results across different device configurations
• Easily identify which builds introduced failures

# The Maestro CLI groups runs by the --name you pass; the API exposes this as the "build" field
testingbot maestro app.ipa ./flows \
  --platform iOS \
  --device "iPhone 17" \
  --real-device \
  --name "Release 2.5.0"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "iOS",
    "version": "26.0",
    "deviceName": "iPhone 17",
    "realDevice": true,
    "build": "Release 2.5.0"
  }]
}' \
-H "Content-Type: application/json"

Shard Split

Group your Maestro flows into chunks, which will run across multiple parallel sessions for faster execution. For example you have 3 parallel slots and 9 tests, but you want to split this test suite into 3 chunks of tests and run them in parallel on connected devices, then you would use shardSplit set to 3.

# Split flows across 3 parallel sessions - without this each flow would run in its own session
testingbot maestro app.apk ./flows \
  --device "Pixel 8" \
  --deviceVersion "14" \
  --shard-split 3

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "shardSplit": 3,
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Device Matrix

Run the same flows across several devices in one command with --device-matrix. Each cell names exactly one device as <device>[:<version>][:real]; cells are comma-separated or the flag is repeated. There is no cross-product, because not every device exists in every OS version.

testingbot maestro app.apk ./flows \
  --device-matrix "Pixel 9:14" \
  --device-matrix "Samsung Galaxy S24:14:real" \
  --device-matrix "Pixel 8"

Every flow runs once per device, so the cost is devices × flows; the CLI prints that summary before submitting. Each device becomes its own run with its own results, live table rows and dashboard link, --json lists the device per run, and --retry re-runs only the flow that failed on the device it failed on. If any cell is not a valid device and OS combination the whole request is rejected and nothing runs, so a matrix never partially submits.

--real-device, or an .ipa app which implies it, applies to every cell. --device and --deviceVersion cannot be combined with a matrix; list every device as a cell instead.

Reuse an Uploaded App

Every run prints its project ID after the app upload. Pass that ID to a later run with --app-binary-id and the upload is skipped; each run still gets its own project and results. testingbot upload uploads an app on its own and prints the ID, which is handy for pipelines that build once and run several suites.

testingbot upload app.apk
#   App ready: app.apk. Project ID: 4321
#   Run flows against it with: testingbot maestro --app-binary-id 4321 ./flows

testingbot maestro --app-binary-id 4321 ./flows/smoke
testingbot maestro --app-binary-id 4321 ./flows/regression --device "Pixel 9"

The platform is taken from the stored app unless --platform is given. Unchanged binaries are also deduplicated by checksum on every upload; pass --ignore-checksum-check to force a fresh upload.

Expo / EAS Build

eas build hands back a download URL rather than a local file, and for iOS simulator builds the artifact is a .tar.gz that contains the .app. Pass the URL with --app-url and the CLI downloads it, extracts the bundle when needed, and uploads it like any other app. Android EAS builds (.apk) and plain .zip / .ipa URLs work the same way, and a local .tar.gz can be passed as the app file directly.

# iOS simulator build
URL=$(eas build --platform ios --profile preview --json --non-interactive | jq -r '.[0].artifacts.buildUrl')
testingbot maestro --app-url "$URL" ./flows --device "iPhone 16"

# Android build
URL=$(eas build --platform android --profile preview --json --non-interactive | jq -r '.[0].artifacts.buildUrl')
testingbot maestro --app-url "$URL" ./flows --device "Pixel 9"

Inside an EAS Build or EAS Workflows job the run is tagged automatically with the EAS build id, profile and platform, and the job's commit hash is used as the commit SHA unless --commit-sha is given. EAS download links are signed and expire after about an hour; a rejected link is reported as such so you know to request a fresh one. testingbot upload <url> accepts URLs too, which is handy to upload once and reuse across several suites.

JSON Output and Exit Codes

--json prints one JSON document on stdout with the outcome, project ID, dashboard URL and every flow attempt per run, and moves all log lines to stderr. --json-file writes the same document to <projectId>_testingbot.json (or --json-file-name) while keeping the console output. Exit codes are 0 passed, 2 flows failed, 1 CLI or infrastructure error. Examples and the document layout are on the CI/CD page.

CI/CD Integration

Pass Git and repository metadata to associate test runs with specific commits and pull requests. This information appears in the TestingBot dashboard and can be used for tracking and debugging.

# Pass Git metadata for CI/CD tracking
testingbot maestro app.apk ./flows \
  --device "Pixel 8" \
  --deviceVersion "14" \
  --commit-sha "abc123def456" \
  --pull-request-id "42" \
  --repo-owner "myorg" \
  --repo-name "myapp"

- uses: testingbot/maestro-action@v1
  with:
    api-key: ${{ secrets.TB_KEY }}
    api-secret: ${{ secrets.TB_SECRET }}
    app-file: app.apk
    workspace: ./flows
    device: Pixel 8

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "metadata": {
    "commitSha": "abc123def456",
    "pullRequestId": "42",
    "repoName": "myapp",
    "repoOwner": "myorg"
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Device Orientation

Set the device orientation at the start of your test.

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

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8",
    "orientation": "LANDSCAPE"
  }]
}' \
-H "Content-Type: application/json"

Soft Keyboard (Android)

By default, the Android soft keyboard is hidden during Maestro tests. Use the showKeyboard option to display the soft keyboard on Android devices.

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "maestroOptions": {
    "showKeyboard": true
  },
  "capabilities": [{
    "platformName": "Android",
    "version": "14",
    "deviceName": "Pixel 8"
  }]
}' \
-H "Content-Type: application/json"

Platform Configuration

Platform-specific settings allow you to optimize the environment for Android or iOS. These are configured in your config.yaml file under the platform key.

iOS specifics

Android specifics

Example config.yaml

platform:
  ios:
    disableAnimations: true
  android:
    disableAnimations: true

Device Timezone

Set the device timezone for your test. Useful for testing time-sensitive features.

testingbot maestro app.zip ./flows \
  --platform iOS \
  --device "iPhone 15" \
  --deviceVersion "17.2" \
  --timezone "America/New_York"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "iOS",
    "version": "17.2",
    "deviceName": "iPhone 15",
    "timeZone": "America/New_York"
  }]
}' \
-H "Content-Type: application/json"

See the full list of timezone identifiers.

Device Locale

Set the device locale to test localized content and formatting. The locale affects language, date formats, number formats, and currency display.

testingbot maestro app.zip ./flows \
  --platform iOS \
  --device "iPhone 15" \
  --deviceVersion "17.2" \
  --device-locale "de_DE"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{
  "capabilities": [{
    "platformName": "iOS",
    "version": "17.2",
    "deviceName": "iPhone 15",
    "locale": "de_DE"
  }]
}' \
-H "Content-Type: application/json"

Common Locale Codes

Maestro config.yaml

You can include a config.yaml file in your Maestro flows zip file. This configuration file lets you define options that apply to all your flows.

Supported config.yaml Options

Example config.yaml

env:
  API_URL: https://api.example.com
  DEBUG: "true"

includeTags:
  - smoke
  - critical

TestingBot Tunnel

Use TestingBot Tunnel to allow your app to access private or staging backend servers during tests.

Use Cases

• Test against staging APIs not accessible from the public internet
• Access localhost services running on your machine
• Test with private databases or internal services

To start a tunnel, download and run the TestingBot Tunnel client before starting your tests.

You can also use the built-in tunnel option to automatically start a tunnel for the duration of your test run.

See the dedicated Maestro Tunnel guide for use cases, a staging token helper and CI/CD examples.

CLI Reference

When using the TestingBot CLI, these options are available as command-line flags:

App & Flows

The application and flows are normally passed as positional arguments (testingbot maestro app.apk ./flows), but you can also set them explicitly:

Device Options

Test Configuration

Execution Options

CI/CD Integration

With the TestingBot GitHub App installed, a run carrying the repository and full commit SHA also posts a status check on the pull request.

Network & Location

Report & Artifacts

Tunnel Options

Advanced Options

Authentication & Debugging

Credentials are normally resolved from testingbot login, the TB_KEY / TB_SECRET environment variables, or a ~/.testingbot file. You can also pass them explicitly:

Other Commands

Besides maestro, the CLI has commands for working with projects after they were started. All of them accept the authentication and --json flags above.

See Async runs, status and artifacts for a pipeline example.

Frequently asked questions