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

By default, TestingBot runs your Maestro flows with the latest version of the Maestro CLI.

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 all flow files in your zip archive. To run only specific flows, use the option below.

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.

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

testingbot maestro app.ipa ./flows \
  --platform iOS \
  --device "iPhone 17" \
  --real-device \
  --build "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"

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"

testingbot maestro app.apk ./flows \
  --device "Pixel 8" \
  --commit-sha "${{ github.sha }}" \
  --pull-request-id "${{ github.event.pull_request.number }}" \
  --repo-owner "${{ github.repository_owner }}" \
  --repo-name "${{ github.event.repository.name }}"

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.

CLI Reference

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

Device Options

Test Configuration

CI/CD Integration

Network & Location

Output Options

Tunnel Options

Advanced Options

Frequently asked questions