Maestro Support

Maestro is an open-source, YAML-based UI automation framework for testing Android and iOS applications using simple, human-readable test flows.

Digital.ai Testing enables you to upload a Maestro test bundle and execute it on Real and simulated mobile device in the cloud, alongside your existing Appium, Espresso, and XCUITest test suites. Test execution includes device reservation, video recording, step-level logs, and reporting through Reporter.

info

Maestro support is currently available for Android devices only (API level 26 and later).

The Maestro support for iOS will be added in a future release.

How it works

When you submit a Maestro test run, Digital.ai Testing:

1. Uploads and validates the Maestro test bundle provided through the Test Run API.
2. Selects the Maestro flows to execute based on the bundle contents and optional tag filters.
3. Schedules the execution on the reserved Android device(s) according to the selected running type (FAST_FEEDBACK or COVERAGE).
4. Executes the Maestro tests while capturing execution logs and recording the test session.
5. Generates a report for each executed flow, including the execution status, video recording, and Maestro logs.

Preparing your Maestro test bundle

Package your Maestro flows as a ZIP file with the following structure:

my-maestro-tests.zip
├── flows/
│   ├── login-test.yaml
│   ├── checkout-test.yaml
│   └── ...
├── utils/            # Optional — YAML helper files only
│   └── ...
└── config.yaml       # Optional

• The flows/ directory is required and must contain at least one Maestro flow file.
• The utils/ directory is optional and may contain reusable YAML helper files.
• The optional config.yaml file is used to configure flow selection through tags.

info

The uploaded ZIP bundle is validated before extraction to ensure it is well-formed and safe to process. Bundles that fail validation are rejected before test execution begins.

Filtering flows with tags

Use the optional config.yaml file to control which flows are executed by specifying includeTags and/or excludeTags.

Example:

includeTags:
  - sanity

excludeTags:
  - flaky

• If includeTags is specified, only flows containing at least one matching tag are executed.
• If excludeTags is specified, flows containing any matching tag are excluded from execution.
• Tag filtering is applied before test execution for both FAST_FEEDBACK and COVERAGE runs.

Running a Maestro test using the API

Maestro tests are executed using the same Test Run API used for Espresso and XCUITest, with the execution type set to MAESTRO.

For complete endpoint details, see Manage Test Run with the API.

POST

/api/v1/test-run/execute-test-run

or

/api/v1/test-run/execute-test-run-async

for asynchronous execution.

Parameter	Type	Required	Description
executionType	String	Yes	Set to MAESTRO.
runningType	String	Yes	fastFeedback or coverage.
app / appUrl / cloudApp	File / String / Long	Yes (one of)	Android application under test (APK, API level 26 or later).
maestroFile	File	Yes	ZIP bundle containing the Maestro flows and optional configuration files.
deviceQueries	String	Yes	Specifies the Android devices on which the tests will run.

Unsupported parameters

The following parameters are supported only for Espresso and XCUITest executions and cannot be used with executionType=MAESTRO.

• uuid
• includeTests
• ignoreTestFile
• cucumberOption
• useUIAutomator
• useTestOrchestrator
• clearPackageData

All other common Test Run API parameters, such as maxDevices, minDevices, overallTimeout, creationTimeout, reservationDuration, retry, retryDifferentDevice, additionalAppIds, and runTags, behave the same as they do for other execution types.

Example

curl "https://CLOUD_SERVER/api/v1/test-run/execute-test-run-async?deviceQueries=@os='android'" \
  -H "Authorization: Basic YOUR_CREDENTIALS" \
  -F "executionType=MAESTRO" \
  -F "runningType=fastFeedback" \
  -F "app=@APP_PATH" \
  -F "maestroFile=@MAESTRO_BUNDLE.zip"

Reports

A separate report is generated for each executed Maestro flow. Reports include:

• Pass or fail status
• Video recording of the test execution
• Step-level Maestro execution log
• Additional execution logs to assist with troubleshooting

Limitations

• Maestro execution is supported only on Android devices (API level 26 and later).
• iOS execution is not currently supported.
• Espresso- and XCUITest-specific execution options such as useUIAutomator, useTestOrchestrator, clearPackageData, includeTests, ignoreTestFile, and cucumberOption are not supported for Maestro test runs.

See also

• Run Automated Tests on a Reserved Device
• Manage Test Run with the API
• Maestro documentation