### Install App Before Maestro Testing

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Install a fresh application build before running tests using the `--app-file` flag. This ensures testing against the correct version for Android, iOS Simulator, and iOS Device.

```bash
maestro-runner --app-file app.apk flows/ # Android
maestro-runner --platform ios --app-file MyApp.app flows/ # iOS Simulator
maestro-runner --platform ios --team-id ABCDE12345 --app-file MyApp.ipa flows/ # iOS Device
```

--------------------------------

### Run Maestro Flows on iOS Simulator

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Execute Maestro flows on an iOS simulator. This includes starting a simulator by name or allowing Maestro Runner to auto-select one.

```bash
maestro-runner --platform ios flows/
maestro-runner --platform ios --start-simulator "iPhone 15 Pro" flows/
maestro-runner --platform ios --auto-start-emulator flows/
```

--------------------------------

### CI/CD Integration for maestro-runner

Source: https://devicelab.dev/open-source/maestro-runner

Example command for CI/CD environments to automatically start an emulator, run tests in parallel, and shut down upon completion.

```bash
maestro-runner --auto-start-emulator --parallel 2 flows/
```

--------------------------------

### Install maestro-runner via CLI

Source: https://devicelab.dev/open-source/maestro-runner

Installs the maestro-runner binary using a shell script via curl.

```bash
curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash
```

--------------------------------

### Web Navigation and Interaction Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Examples of navigation commands like launchApp and openLink, and various selection methods for interacting with web elements.

```yaml
# Navigate to URL
- launchApp: https://myapp.com

# Navigate with clear state
- launchApp:
    appId: https://myapp.com
    clearState: true

# Tap by selector
- tapOn:
    css: "button[type=submit]"
- tapOn:
    testId: submit-btn
```

--------------------------------

### Login Flow Example (YAML)

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Demonstrates a complete login process using Maestro. It includes launching the app, clearing state, interacting with UI elements to enter credentials, and asserting successful login. It also shows how to save authentication state for reuse.

```yaml
url: https://myapp.example.com
name: Login and Save Auth
tags:
  - auth
---
- launchApp:
    appId: https://myapp.example.com
    clearState: true

- tapOn:
    css: "button[type=button]"
    text: "Sign In"

- inputText:
    text: "testuser@example.com"
    css: "input[type=email]"

- inputText:
    text: "Test1234!"
    css: "input[type=password]"

- tapOn:
    css: "button[type=submit]"

- assertVisible: "Dashboard"
- assertNoJSErrors

# Save auth state for other flows
- saveAuthState: /tmp/auth-state.json

```

--------------------------------

### Install application for testing

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Deploys an application build to the target device or simulator before executing flows.

```bash
# Android
maestro-runner --app-file app.apk flows/

# iOS simulator
maestro-runner --platform ios --app-file App.app flows/

# iOS real device
maestro-runner --platform ios --team-id ABCDE12345 --app-file App.ipa flows/
```

--------------------------------

### Run Maestro Flows on Cloud (Appium)

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Connect to Appium-compatible cloud providers like BrowserStack or SauceLabs. Requires specifying the Appium URL and capabilities file. A local Appium server can also be used.

```bash
maestro-runner --driver appium \
  --appium-url "https://your-cloud-provider/wd/hub" \
  --caps caps.json \
  flows/
maestro-runner --driver appium flows/ # Local Appium server
```

--------------------------------

### Manage Android emulators and iOS simulators

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Commands to start, manage, and configure virtual devices for test execution.

```bash
# Start a specific AVD
maestro-runner --start-emulator Pixel_7_API_33 flows/

# Auto-start if no devices found
maestro-runner --auto-start-emulator flows/

# iOS Simulator
maestro-runner --platform ios --start-simulator "iPhone 15 Pro" flows/
```

--------------------------------

### Checkout Flow Example with Network Mocking (YAML)

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Illustrates a checkout process that reuses saved authentication state and mocks a payment API. It blocks analytics, sets up a mock response for the payment endpoint, interacts with the UI, and verifies the mocked response was used. Finally, it clears network mocks.

```yaml
url: https://myapp.example.com
name: Checkout Flow
tags:
  - checkout
---
# Skip login — load saved auth state
- loadAuthState: /tmp/auth-state.json
- launchApp

# Block analytics to speed up tests
- blockNetwork:
    patterns:
      - "*.analytics.com/*"

# Mock the payment API
- mockNetwork:
    url: "*/api/payment/charge"
    method: "POST"
    response:
      status: 200
      headers:
        Content-Type: "application/json"
      body: '{"success": true, "transactionId": "TXN-12345"}'

# Run the checkout flow
- tapOn: "Products"
- tapOn: "Add to Cart"
- tapOn: "Checkout"

# Verify form state
- assertVisible:
    css: "input[type=email]"
    enabled: false

- tapOn:
    css: "button[type=submit]"
    label: "Submit payment"

# Wait for the payment API call
- waitForRequest:
    url: "*/api/payment/charge"
    method: "POST"
    output: paymentRequest

# Verify the mocked payment response was used
- assertVisible: "TXN-12345"

# No JS errors during the entire flow
- assertNoJSErrors

# Clean up
- clearNetworkMocks

```

--------------------------------

### Check version information

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Displays the currently installed version of the maestro-runner CLI.

```bash
maestro-runner --version
```

--------------------------------

### Troubleshoot Keyboard Covering Element

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Address issues where the keyboard covers a target element during input actions. Adding a `- hideKeyboard` step after input commands can resolve this.

```yaml
- inputText: "user@example.com"
- hideKeyboard
- tapOn: "Submit"
```

--------------------------------

### Parallel Maestro Execution

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Run Maestro tests across multiple devices concurrently. This can be combined with auto-start emulators or specific device targeting.

```bash
maestro-runner --parallel 3 flows/
maestro-runner --parallel 3 --auto-start-emulator flows/
maestro-runner --device emulator-5554,emulator-5556 flows/
```

--------------------------------

### Troubleshoot clearState on iOS Real Device (Appium)

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Workaround for `clearState` failures on iOS real devices when `mobile: clearApp` is unsupported. Using `newSession: true` with `launchApp` provides a clean state by creating a fresh Appium session.

```yaml
- launchApp:
    appId: com.example.app
    newSession: true
```

--------------------------------

### Execute Web Flows via CLI

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Commands to run web testing flows using different browser configurations, including headless mode, installed Chrome, and custom binaries.

```bash
# Run a flow against a web app
maestro-runner --platform web flows/login.yaml

# With a visible browser window
maestro-runner --platform web --headed flows/

# Use your installed Chrome instead of bundled Chromium
maestro-runner --platform web --browser chrome flows/

# Custom binary
maestro-runner --platform web --browser /opt/chrome-canary/chrome flows/
```

--------------------------------

### Perform Structural Queries with CSS

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-selectors

Examples of using CSS descendant and pseudo-class selectors to perform structural queries that replace unsupported relative selectors.

```yaml
# Instead of childOf, use CSS descendant/child selectors:
- tapOn:
    css: "#parent-form > button.submit"

# Instead of containsChild:
- tapOn:
    css: ".card:has(.badge)"
```

--------------------------------

### Run Maestro Flows on Android

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Execute Maestro flows on an Android device. Auto-detection is used for platform and device. For faster execution, the DeviceLab driver can be specified.

```bash
maestro-runner flows/
maestro-runner --driver devicelab flows/
maestro-runner --platform android --device emulator-5554 flows/
maestro-runner --auto-start-emulator flows/
maestro-runner --start-emulator Pixel_7_API_33 flows/
```

--------------------------------

### Run Maestro Flows on iOS Real Device

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Execute Maestro flows on an iOS real device. Requires specifying a team ID for code signing and optionally a device UDID for targeting.

```bash
maestro-runner --platform ios --team-id ABCDE12345 flows/
security find-identity -v -p codesigning | head -5
maestro-runner --platform ios --team-id ABCDE12345 \
  --device 00001234-ABCDEF012345 flows/
```

--------------------------------

### Troubleshoot Stale Socket Files

Source: https://devicelab.dev/open-source/maestro-runner/docs/getting-started

Clean up stale socket and PID files that may remain after an unexpected Maestro Runner termination. This is typically done by removing specific files in the /tmp directory.

```bash
rm /tmp/uia2-<serial>.sock /tmp/uia2-<serial>.pid
```

--------------------------------

### Perform HTTP Requests with JavaScript API

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Demonstrates how to use the built-in HTTP client to perform GET and POST requests within Maestro scripts. The response object provides status, body, and auto-parsed JSON data.

```javascript
var response = http.get("https://api.example.com/users");
if (response.ok) {
  output.userId = response.json.id;
}

http.post("https://api.example.com/data", {
  headers: {"Authorization": "Bearer " + token},
  body: {key: "value"},
  timeout: 10000
});
```

--------------------------------

### Mock Network Responses

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Intercepts network requests and provides mock responses. This allows for controlled testing without relying on actual backend services. Supports mocking GET, POST, and error responses with custom status codes, headers, and bodies. URL patterns support wildcards.

```yaml
# Mock a GET endpoint
- mockNetwork:
    url: "*/api/users"
    method: "GET"
    response:
      status: 200
      headers:
        Content-Type: "application/json"
      body: '{"users": [{"id": 1, "name": "Test User"}]}'

# Mock a POST endpoint
- mockNetwork:
    url: "*/api/orders"
    method: "POST"
    response:
      status: 201
      body: '{"orderId": "ORD-42"}'

# Mock error response
- mockNetwork:
    url: "*/api/payment"
    response:
      status: 500
      body: '{"error": "Service unavailable"}'
```

--------------------------------

### Launch Application with Options (YAML)

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Launches an application with various configuration options. Supports specifying app ID, clearing state, managing sessions, setting permissions, launch arguments, and environment variables. Defaults can be overridden.

```yaml
- launchApp
- launchApp: com.example.app

# With options
- launchApp:
    appId: com.example.app
    clearState: true
    stopApp: false
    newSession: true
    permissions:
      camera: allow
      location: deny
    arguments:
      --username: devicelab
      --password: robustest
    environment:
      BASE_URL: "https://api.example.com"
      LOG_LEVEL: "debug"

# Fresh session (Appium driver, useful for real iOS devices)
- launchApp:
    appId: com.example.app
    newSession: true

```

--------------------------------

### Execute Test Flows with maestro-runner

Source: https://devicelab.dev/open-source/maestro-runner

Demonstrates various command-line options for running test flows, including platform selection, directory execution, Appium integration, and parallel processing.

```bash
maestro-runner flow.yaml                              # Android (default)
maestro-runner --platform ios flow.yaml               # iOS
maestro-runner flows/                                 # All flows in a directory
maestro-runner --driver appium --appium-url <url> flow.yaml  # Appium / cloud
maestro-runner --parallel 3 flows/                    # Parallel on 3 devices
```

--------------------------------

### Configure Flow Execution Settings

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Shows how to define advanced flow configurations, including environment variables, timeouts, and lifecycle hooks like onFlowStart and onFlowComplete.

```yaml
appId: com.example.app
name: Checkout Flow
tags:
  - smoke
  - checkout
env:
  BASE_URL: https://staging.example.com
  TEST_USER: testuser
timeout: 120000
commandTimeout: 15000
waitForIdleTimeout: 3000
onFlowStart:
  - launchApp:
      appId: com.example.app
      clearState: true
onFlowComplete:
  - takeScreenshot: final-state.png
---
- tapOn: "Shop"
- tapOn: "Add to Cart"
- tapOn: "Checkout"
```

--------------------------------

### Launch App with New Appium Session

Source: https://devicelab.dev/open-source/maestro-runner/docs/technical-approach

This snippet demonstrates how to launch an application with a new Appium session, useful when `clearState` fails or is unsupported. It ensures a clean state by creating a fresh session for the test flow.

```yaml
- launchApp:
    appId: com.example.app
    newSession: true

```

--------------------------------

### Select Elements using Primary and State Criteria

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Illustrates various ways to target UI elements, including shorthand text matching, resource IDs, CSS selectors, and state-based filtering like enabled or checked status.

```yaml
# Text match
- tapOn: "Login"

# By ID
- tapOn:
    id: submit-btn

# By CSS
- tapOn:
    css: "#login-form button[type=submit]"

# State filtering
- tapOn:
    text: "Submit"
    enabled: true

- assertVisible:
    id: checkbox
    checked: true
```

--------------------------------

### Use Variable Substitution in Flow Steps

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Shows how to inject dynamic values into flow configurations using JavaScript expressions or dollar-prefixed environment variables.

```yaml
- inputText: "${Date.now()}"
- assertTrue: "${count > 0}"
- inputText: "$USERNAME"

appId: ${APP_ID}
---
- launchApp
```

--------------------------------

### Accept System Alert (YAML)

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Accepts the current system alert dialog by tapping 'Allow' or 'OK'. It polls for alerts for a default of 5 seconds and can be configured with a custom timeout. Useful for handling permission prompts.

```yaml
- acceptAlert                    # wait up to 5s for alert, tap Allow
- acceptAlert:
    timeout: 3000               # custom timeout in ms

```

--------------------------------

### Apply Common Step Properties

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Demonstrates how to apply optional properties like timeout, labels, and optional flags to any step in a flow.

```yaml
- tapOn:
    text: "Maybe Visible"
    optional: true
    label: "Dismiss optional popup"
    timeout: 3000
```

--------------------------------

### App Launch API

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Provides endpoints to launch applications with various configurations including clearing state, setting permissions, arguments, and environment variables.

```APIDOC
## POST /launchApp

### Description
Launches an application on the device. Supports various options for configuration.

### Method
POST

### Endpoint
/launchApp

### Parameters
#### Request Body
- **appId** (string) - Optional - App package/bundle ID. Defaults to the flow's `appId`.
- **clearState** (boolean) - Optional - Clear app data before launch.
- **clearKeychain** (boolean) - Optional - Clear the iOS keychain before launch.
- **stopApp** (boolean) - Optional - Stop the app before relaunching. Defaults to `true`.
- **newSession** (boolean) - Optional - Create a fresh Appium session. Useful for real iOS devices when `clearState` fails.
- **permissions** (map) - Optional - Set app permissions (e.g., `camera: allow`, `location: deny`). Defaults to `all: allow`.
- **arguments** (map) - Optional - Launch arguments passed to the app.
- **environment** (map) - Optional - Environment variables passed to the app.

### Request Example
```json
{
  "appId": "com.example.app",
  "clearState": true,
  "stopApp": false,
  "newSession": true,
  "permissions": {
    "camera": "allow",
    "location": "deny"
  },
  "arguments": {
    "--username": "devicelab",
    "--password": "robustest"
  },
  "environment": {
    "BASE_URL": "https://api.example.com",
    "LOG_LEVEL": "debug"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Tap UI Elements using Selectors

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-selectors

Demonstrates how to trigger tap actions on UI elements using different selection strategies. Supported methods include test IDs with state filters, CSS selectors with index-based matching, and accessibility roles combined with text labels.

```yaml
- tapOn:
    testId: submit-btn
    enabled: true

- tapOn:
    css: ".list-item"
    nth: 2

- tapOn:
    role: button
    text: "Submit"
```

--------------------------------

### POST /assertWithAI

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Uses AI vision to verify natural language assertions against the current screen state.

```APIDOC
## POST /assertWithAI

### Description
Verifies a human-readable description of the screen state using AI vision. Supported on Android and iOS.

### Parameters
#### Request Body
- **assertion** (string) - Required - Natural language description of the expected state

### Request Example
- assertWithAI:
    assertion: "The submit button is enabled and the form has no errors"
```

--------------------------------

### Open Links and Browsers

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Commands to open URLs, deep links, or specific browser instances. Supports configuration for auto-verification and browser forcing.

```yaml
- openLink: "https://example.com"
- openLink: "myapp://page/detail"

- openLink:
    link: "myapp://settings"
    autoVerify: true
    browser: false

- openBrowser: "https://example.com"
- openBrowser:
    url: "https://example.com/page"
```

--------------------------------

### Utility Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Miscellaneous commands for pressing hardware keys, waiting for animations, and defining global variables.

```yaml
- pressKey: ENTER
- waitForAnimationToEnd
- defineVariables:
    USERNAME: testuser
```

--------------------------------

### Text Matching and Regex Patterns

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-selectors

Shows how text matching handles regex automatically when special characters are detected, providing equivalent shorthand and explicit syntax.

```yaml
# These are equivalent:
- assertVisible: "Order #\\d+"
- assertVisible: { textRegex: "Order #\\d+" }
```

--------------------------------

### Configure Flow Lifecycle Hooks

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Using onFlowStart and onFlowComplete hooks to execute browser-specific scripts or cleanup tasks during the test lifecycle.

```yaml
url: https://myapp.example.com
onFlowStart:
  - evalBrowserScript: "localStorage.setItem('debug', 'true')"
onFlowComplete:
  - clearConsoleLogs
---
- launchApp
- tapOn: "Submit"
```

--------------------------------

### Permissions and Alerts API

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Manage application permissions and system alert dialogs.

```APIDOC
## POST /setPermissions

### Description
Sets specific permissions for an application.

### Method
POST

### Endpoint
/setPermissions

### Parameters
#### Request Body
- **appId** (string) - Required - The package/bundle ID of the app.
- **permissions** (map) - Required - A map of permissions and their desired states (`allow`, `deny`, `unset`). Example: `{"camera": "allow", "location": "deny"}`.

### Request Example
```json
{
  "appId": "com.example.app",
  "permissions": {
    "camera": "allow",
    "location": "deny",
    "contacts": "allow",
    "notifications": "allow"
  }
}
```

## POST /acceptAlert

### Description
Accepts the current system alert dialog (e.g., taps 'Allow' or 'OK'). Polls for up to 5 seconds by default.

### Method
POST

### Endpoint
/acceptAlert

### Parameters
#### Request Body
- **timeout** (integer) - Optional - Custom timeout in milliseconds for waiting for the alert. Defaults to 5000ms.

### Request Example
```json
{
  "timeout": 3000
}
```

## POST /dismissAlert

### Description
Dismisses the current system alert dialog (e.g., taps 'Don't Allow' or 'Cancel'). Polls for up to 5 seconds by default.

### Method
POST

### Endpoint
/dismissAlert

### Parameters
#### Request Body
- **timeout** (integer) - Optional - Custom timeout in milliseconds for waiting for the alert. Defaults to 5000ms.

### Request Example
```json
{
  "timeout": 3000
}
```
```

--------------------------------

### Input and Interaction Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Commands for simulating user input such as typing, erasing text, and performing mouse interactions like long presses and coordinate-based taps.

```yaml
- longPressOn: "Delete"
- tapOnPoint:
    x: 100
    y: 200
- inputText: "hello@example.com"
- inputText:
    text: "user@example.com"
    placeholder: "Email"
- eraseText: 10
```

--------------------------------

### Configure maestro-runner Flow Settings

Source: https://devicelab.dev/open-source/maestro-runner

Shows how to extend standard Maestro YAML flows with custom configuration fields like commandTimeout and waitForIdleTimeout.

```yaml
commandTimeout: 10000       # Default per-command timeout (ms)
waitForIdleTimeout: 3000    # Device idle wait (ms), 0 to disable
---
- launchApp: com.example.app
- tapOn: "Login"
- assertVisible: "Welcome"
```

--------------------------------

### Execute Swipe and Scroll Gestures

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Demonstrates how to perform swipe and scroll actions, including directional commands and custom coordinate definitions.

```yaml
# Swipe with options
- swipe:
    direction: DOWN
    speed: 50
    duration: 300

# Scroll until element is visible
- scrollUntilVisible:
    element: "End of List"
    direction: DOWN
```

--------------------------------

### Flow Control and Utility Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Advanced commands for managing browser state, including waiting for animations, handling alerts, setting device emulation, and managing variables.

```yaml
- extendedWaitUntil:
    visible:
      text: "Ready"
    timeout: 30000
- waitForAnimationToEnd
- pressKey: ENTER
- setLocation:
    latitude: "37.7749"
    longitude: "-122.4194"
- repeat:
    times: "3"
    commands:
      - scroll: DOWN
```

--------------------------------

### Define Maestro Flow File Structure

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Demonstrates the YAML structure for Maestro flows, including the optional configuration header and the sequence of test steps.

```yaml
# Config section (optional)
appId: com.example.app
name: Login Flow
tags:
  - smoke
  - login
---
# Steps section
- launchApp
- tapOn: "Login"
- inputText: "user@example.com"
- assertVisible: "Welcome"
```

--------------------------------

### Troubleshooting: Device Already in Use (Android)

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

This error indicates that a device is currently being used by another maestro-runner instance. The solution involves waiting for the existing process to complete or specifying a different device using the `--device` flag. If the error persists due to a stale process, manual removal of socket and PID files is recommended.

```bash
Error: device XXXXX is already in use
Another maestro-runner instance may be using this device.
Socket: /tmp/uia2-XXXXX.sock

```

```bash
rm /tmp/uia2-<serial>.sock /tmp/uia2-<serial>.pid

```

--------------------------------

### Execute Tap Gestures

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Covers various methods for tapping elements, including text matching, ID selection, coordinates, and advanced options like long presses or repeats.

```yaml
# Simple text match
- tapOn: "Login"

# By ID
- tapOn:
    id: submit-btn

# With options
- tapOn:
    text: "Submit"
    longPress: true
    repeat: 2
    delay: 100
    retryTapIfNoChange: true
    waitUntilVisible: true
    waitToSettleTimeoutMs: 500

# Tap at relative point within element
- tapOn:
    id: slider
    point: "80%, 50%"

# Tap at screen percentage (no selector)
- tapOn:
    point: "50%, 90%"

# Tap at absolute pixel coordinates
- tapOn:
    point: "286, 819"
```

--------------------------------

### Configure workspace settings

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Uses a config.yaml file to define shared settings like app ID and environment variables across multiple flows.

```bash
maestro-runner --config config.yaml flows/
```

--------------------------------

### Upload Files in Web Browser

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Sets files on `<input type='file'>` elements within the web page. This command allows specifying the target input element using CSS selectors and providing the path to the file to be uploaded.

```yaml
# Single file
- uploadFile:
    css: "input[type=file]"
    path: "test-data/photo.jpg"
```

--------------------------------

### Target Elements with Relative Selectors

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Demonstrates how to locate elements based on their spatial relationship to other components, such as being below, right of, or inside specific containers.

```yaml
# Tap input below label
- tapOn:
    id: input-field
    below:
      text: "Email"

# Tap inside dialog
- tapOn:
    text: "OK"
    insideOf:
      id: confirmation-dialog

# Nested relative selectors
- tapOn:
    text: "Delete"
    below:
      text: "Username"
      rightOf:
        text: "Settings"
```

--------------------------------

### CLI Execution Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Commands for running test flows via the command line, including parallel execution and debugging modes.

```bash
maestro-runner --platform web --parallel 3 flows/
maestro-runner --platform web --browser chrome flows/
maestro-runner --platform web --headed flows/login.yaml
```

--------------------------------

### App Lifecycle Management API

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Endpoints for stopping, killing, and clearing the state of applications.

```APIDOC
## POST /stopApp

### Description
Gracefully stops an application.

### Method
POST

### Endpoint
/stopApp

### Parameters
#### Request Body
- **appId** (string) - Optional - The package/bundle ID of the app to stop. If not provided, the default app is used.

### Request Example
```json
{
  "appId": "com.example.app"
}
```

## POST /killApp

### Description
Forcefully kills an application.

### Method
POST

### Endpoint
/killApp

### Parameters
#### Request Body
- **appId** (string) - Optional - The package/bundle ID of the app to kill. If not provided, the default app is used.

### Request Example
```json
{
  "appId": "com.example.app"
}
```

## POST /clearState

### Description
Clears the application's data and state.

### Method
POST

### Endpoint
/clearState

### Parameters
#### Request Body
- **appId** (string) - Optional - The package/bundle ID of the app to clear state for. If not provided, the default app is used.

### Request Example
```json
{
  "appId": "com.example.app"
}
```

## POST /clearKeychain

### Description
Clears the device's keychain. This is an iOS-only operation.

### Method
POST

### Endpoint
/clearKeychain

### Request Example
```json
{}
```
```

--------------------------------

### Execute JavaScript

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Executes JavaScript snippets or files to perform calculations or logic. Supports output storage and environment variable injection.

```yaml
- runScript: |
    function calculate() {
      return 42;
    }
    output.result = calculate();

- evalScript: "output.total = ${price} * ${quantity}"
```

--------------------------------

### Manage Browser Tabs

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Handles opening, switching between, and closing browser tabs. Useful for testing multi-tab scenarios like OAuth flows or links opening in new tabs. Tabs can be identified by URL, index, or custom labels.

```yaml
# Open a new tab
- openTab: "https://accounts.google.com/oauth"

# Open with a label for easy switching
- openTab:
    url: "https://accounts.google.com/oauth"
    tabLabel: "oauth"

# Switch to tab by label
- switchTab: oauth

# Switch by index (0-based, 0 = first tab)
- switchTab:
    index: 0

# Switch by URL pattern (glob matching with *)
- switchTab:
    url: "*/oauth/callback*"

# Close current tab (switches to remaining tab)
- closeTab

# Typical OAuth flow:
- launchApp
- tapOn: "Sign in with Google"

# A new tab opens for OAuth
- openTab:
    url: "https://accounts.google.com"
    tabLabel: "google"

# Interact with the OAuth page
- inputText:
    text: "user@gmail.com"
    placeholder: "Email"
- tapOn: "Next"

# After OAuth redirects back, switch to main app
- switchTab:
    index: 0

# Verify login succeeded
- assertVisible: "Welcome"
```

--------------------------------

### Define Web Flow Configuration

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Structure of a Maestro YAML flow file, including URL definition, environment variables, and step-by-step interaction commands.

```yaml
url: https://myapp.example.com
name: Login Flow
---
- launchApp
- tapOn: "Sign In"
- inputText:
    text: "user@example.com"
    placeholder: "Email"
- inputText:
    text: "password123"
    placeholder: "Password"
- tapOn: "Log In"
- assertVisible: "Welcome back"
```

--------------------------------

### Media Management

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Commands for capturing screenshots, adding media to the gallery, and recording screen video. Media commands are primarily for Android.

```yaml
- takeScreenshot: "login-screen.png"

- addMedia:
    files:
      - "test-data/photo.png"

- startRecording: "test-run.mp4"
- stopRecording: "test-run.mp4"
```

--------------------------------

### Set Application Permissions (YAML)

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Configures specific permissions for an application. Supports granting, denying, or unsetting permissions for various categories like camera, location, and notifications. Defaults to granting all permissions if not specified.

```yaml
- setPermissions:
    appId: com.example.app
    permissions:
      camera: allow
      location: deny
      contacts: allow
      notifications: allow

# Grant everything (default behavior)
- launchApp:
    permissions:
      all: allow

# Deny everything
- launchApp:
    permissions:
      all: deny

# Don't touch permissions
- launchApp:
    permissions:
      all: unset

# Deny camera, grant rest
- launchApp:
    permissions:
      camera: deny
      notifications: allow

```

--------------------------------

### Connect to Appium server

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Configures maestro-runner to use an external Appium server, which is required for cloud-based testing providers.

```bash
# Local Appium server
maestro-runner --driver appium flows/

# With capabilities file
maestro-runner --driver appium --caps caps.json flows/

# Cloud provider
maestro-runner --driver appium \
  --appium-url "https://your-cloud-provider/wd/hub" \
  --caps cloud-caps.json \
  flows/
```

--------------------------------

### Apply State Filters to Selectors

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-selectors

Illustrates how to refine element selection by filtering for interactive states like enabled, checked, focused, or selected.

```yaml
# Only enabled buttons
- tapOn:
    text: "Submit"
    enabled: true

# Checked checkbox
- assertVisible:
    css: "input[type=checkbox]"
    checked: true

# Focused input
- assertVisible:
    css: "input"
    focused: true

# Selected option
- assertVisible:
    css: "option"
    selected: true
```

--------------------------------

### Configuring Flow Inclusion with config.yaml

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Use a config.yaml file within a directory to define which flows to include, supporting glob patterns and recursive scanning.

```yaml
# config.yaml - include flows from subdirectories
flows:
  - "auth/*"              # Top-level files in auth/
  - "checkout/*"          # Top-level files in checkout/
  - "**"                  # All .yaml/.yml files recursively
  - "**/smoke*.yaml"      # Recursive, matching a filename pattern
```

--------------------------------

### Execute JavaScript in Browser Context

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Run JavaScript code directly within the browser's page context, providing access to `window`, `document`, DOM APIs, and `fetch`. Scripts can be provided inline or loaded from a file, with support for environment variables and capturing output.

```yaml
# Inline script (scalar shorthand)
- evalBrowserScript: "return document.title"

# With output variable
- evalBrowserScript:
    script: |
      const el = document.querySelector('#price');
      return el ? el.textContent : 'not found';
    output: priceText

# Use the result in subsequent steps
- assertTrue: "${priceText !== 'not found'}"

# Scripts run as async functions — you can use await:
- evalBrowserScript:
    script: |
      const response = await fetch('/api/status');
      const data = await response.json();
      return data.version;
    output: apiVersion
```

```javascript
const apiKey = window.__env.API_KEY;
const res = await fetch('/api/setup', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: JSON.stringify({ reset: true })
});
const data = await res.json();
return data.status;  // stored in setupResult variable
```

```yaml
# Simple — just the file path
- runBrowserScript: "scripts/setup.js"

# With env vars and output
- runBrowserScript:
    file: "scripts/setup-test-data.js"
    env:
      API_KEY: "${API_KEY}"
      ENV: "test"
    output: setupResult
```

--------------------------------

### Assertion Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Standard assertions for UI visibility and logical conditions. Includes support for JavaScript expressions and platform-specific checks.

```yaml
- assertVisible: "Welcome"
- assertNotVisible: "Error"
- assertTrue: "1 === 1"
- assertCondition:
    visible:
      text: "Success"
```

--------------------------------

### Text Input and Clipboard Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Commands for interacting with text fields, generating random data, erasing text, and managing clipboard content. These facilitate form filling and data validation workflows.

```yaml
- inputText: "hello@example.com"
- inputRandom: EMAIL
- eraseText: 5
- copyTextFrom: "Price Label"
- pasteText
- setClipboard: "text to paste later"
```

--------------------------------

### Navigation Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Basic UI navigation commands including back button simulation and keyboard dismissal. Behavior for keyboard dismissal is platform-specific between Android and iOS.

```yaml
- back
- hideKeyboard
```

--------------------------------

### ID Selectors with Regex Patterns in Maestro Runner

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Demonstrates using regular expressions within ID selectors for wildcard, alternation, and suffix anchoring. This feature is automatically detected by the presence of regex metacharacters in the ID string.

```yaml
# Wildcard match
- tapOn:
    id: "username-.*"

# Alternation
- assertVisible:
    id: "(username|email)-input"

# Suffix anchor
- tapOn:
    id: "login.*-button$"
```

--------------------------------

### Navigation and Scroll Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Commands to control viewport movement, including scrolling by direction and scrolling until a specific element becomes visible.

```yaml
- scroll: DOWN
- scrollUntilVisible:
    element: "Footer"
    direction: DOWN
- swipe: LEFT
```

--------------------------------

### Execute Maestro flows with DeviceLab driver

Source: https://devicelab.dev/open-source/maestro-runner/docs/technical-approach

Command to run automation flows using the high-performance DeviceLab driver. This driver utilizes WebSocket-based RPC communication to reduce latency compared to standard UIAutomator2.

```bash
maestro-runner --driver devicelab flows/
```

--------------------------------

### Upload Files by Path or Selector

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Uploads files to an application. Supports specifying files by their paths (relative to the flow file) or by a UI element selector (like name or testId).

```yaml
- uploadFile:
    testId: file-input
    paths:
      - "test-data/doc1.pdf"
      - "test-data/doc2.pdf"

- uploadFile:
    name: avatar
    path: "test-data/avatar.png"
```

--------------------------------

### POST /scrollUntilVisible

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Scrolls the screen until a specific element becomes visible based on defined criteria.

```APIDOC
## POST /scrollUntilVisible

### Description
Scrolls the screen in a specified direction until the target element meets the visibility requirements.

### Parameters
#### Request Body
- **element** (selector) - Required - Element to scroll to (text string or selector object)
- **direction** (string) - Required - Scroll direction: `UP`, `DOWN`, `LEFT`, `RIGHT`
- **maxScrolls** (int) - Optional - Maximum scroll attempts
- **speed** (int) - Optional - Scroll speed 0-100
- **visibilityPercentage** (int) - Optional - Percentage of element that must be visible
- **centerElement** (bool) - Optional - Scroll element to center of screen
- **timeout** (int) - Optional - Overall timeout in milliseconds

### Request Example
- scrollUntilVisible:
    element:
      id: footer
    direction: DOWN
    maxScrolls: 20
```

--------------------------------

### Simulate Network Conditions

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Simulates various network conditions, including slow network speeds (e.g., 3G) or complete offline mode. This allows testing application behavior under different network environments.

```yaml
# Simulate slow 3G
- setNetworkConditions:
    latency: 200
    downloadSpeed: 500
    uploadSpeed: 100

# Go offline
- setNetworkConditions:
    offline: true
```

--------------------------------

### Text Selectors with Regex Patterns in Maestro Runner

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Explains how Maestro Runner automatically detects and interprets regular expressions in text selectors. This includes literal text matching and various regex patterns triggered by quantifiers and special characters.

```yaml
# Literal text match
- tapOn: "Login"

# Regex match (auto-detected by quantifiers like *, +, ?, [], etc.)
- tapOn: "Item [0-9]+"
- assertVisible: "Price: \$[0-9]+\.99"
```

--------------------------------

### POST /extractTextWithAI

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Extracts specific information from the screen using AI vision and stores it in a variable.

```APIDOC
## POST /extractTextWithAI

### Description
Uses AI vision to extract specific text based on a query and stores the result in a variable.

### Parameters
#### Request Body
- **query** (string) - Required - What to extract (e.g., "price")
- **variable** (string) - Required - Variable name to store the result

### Request Example
- extractTextWithAI:
    query: "price"
    variable: product_price
```

--------------------------------

### Wait for File Download

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-commands

Waits for a file download to complete in the browser. Can save to a default temporary directory or a specified path, and optionally assert the downloaded filename. Requires a user action to initiate the download beforehand.

```yaml
# Wait for download (saves to temp dir)
- waitForDownload

# Save to specific directory
- waitForDownload:
    saveTo: "downloads/"

# Assert filename
- waitForDownload:
    saveTo: "downloads/"
    assertFilename: "report.pdf"
    timeout: 10000

# Typical pattern: click download link, then wait
- tapOn: "Download Report"
- waitForDownload:
    saveTo: "/tmp/downloads"
    assertFilename: "report.pdf"
```

--------------------------------

### Apply Step Properties

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Common modifiers for test steps, such as setting timeouts, adding labels for reports, or marking steps as optional.

```yaml
# Optional step — won't fail the flow if element is missing
- tapOn:
    text: "Dismiss"
    optional: true

# Custom timeout — wait up to 30 seconds
- assertVisible:
    text: "Report generated"
    timeout: 30000

# Label for reports
- tapOn:
    text: "Submit"
    label: "Submit the order form"
```

--------------------------------

### Report Directory Structure

Source: https://devicelab.dev/open-source/maestro-runner/docs/technical-approach

Illustrates the typical directory structure generated by maestro-runner after a test run. This includes the main report files, logs, and per-flow details with associated artifacts.

```text
reports/<timestamp>/
  report.html           # Visual HTML report
  report.json           # Machine-readable JSON report
  maestro-runner.log    # Detailed execution log
  flows/
    flow-000.json       # Per-flow detail with commands and artifacts
    flow-001.json
    ...
  assets/
    flow-000/
      cmd-000-after.png   # Screenshot after step failure
      ...

```

--------------------------------

### Assertion Commands

Source: https://devicelab.dev/open-source/maestro-runner/docs/web-testing

Validation commands to verify the state of the UI, including element visibility, text presence, and custom JavaScript-based conditions.

```yaml
- assertVisible: "Welcome"
- assertVisible:
    testId: success-banner
- assertNotVisible: "Error"
- assertTrue: "${totalPrice > 0}"
```

--------------------------------

### POST /inputText

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Inputs text into a focused field or a specific element identified by a selector.

```APIDOC
## POST /inputText

### Description
Types text into the currently focused field or a specific element.

### Parameters
#### Request Body
- **text** (string) - Required - The text to input
- **id** (string) - Optional - The element identifier

### Request Example
- inputText:
    text: "username"
    id: email-field
```

--------------------------------

### Device Control API

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Commands to control device settings like location, orientation, and airplane mode.

```APIDOC
## POST /setLocation

### Description
Sets the device's GPS location. This is supported on Android and with the Appium driver, but not on iOS native.

### Method
POST

### Endpoint
/setLocation

### Parameters
#### Request Body
- **latitude** (string) - Required - The latitude value.
- **longitude** (string) - Required - The longitude value.

### Request Example
```json
{
  "latitude": "37.7749",
  "longitude": "-122.4194"
}
```

## POST /setOrientation

### Description
Sets the device orientation.

### Method
POST

### Endpoint
/setOrientation

### Parameters
#### Request Body
- **orientation** (string) - Required - The desired orientation. Accepts `PORTRAIT` or `LANDSCAPE`.

### Request Example
```json
{
  "orientation": "PORTRAIT"
}
```

## POST /setAirplaneMode

### Description
Enables or disables airplane mode on the device.

### Method
POST

### Endpoint
/setAirplaneMode

### Parameters
#### Request Body
- **enabled** (boolean) - Required - Set to `true` to enable airplane mode, `false` to disable.

### Request Example
```json
{
  "enabled": true
}
```
```

--------------------------------

### Execute tests in parallel

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Runs automation flows across multiple devices simultaneously to reduce total execution time.

```bash
# Auto-detect devices
maestro-runner --parallel 2 flows/

# Auto-start emulators to reach target count
maestro-runner --parallel 3 --auto-start-emulator flows/
```

--------------------------------

### Kill Application (YAML)

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Forcefully terminates a running application. Similar to `stopApp`, it can accept an explicit app ID or use the default configured app ID.

```yaml
- killApp
- killApp: com.example.app

```

--------------------------------

### Managing WebDriverAgent

Source: https://devicelab.dev/open-source/maestro-runner/docs/cli-reference

Commands to check the current version of WebDriverAgent or update it to the latest or a specific version.

```bash
# Show the installed WebDriverAgent version
maestro-runner wda version

# Update to latest
maestro-runner wda update

# Update to specific version
maestro-runner wda update 8.8.3

# Check only (don't install)
maestro-runner wda update --check
```

--------------------------------

### Flow Control: Repeat, Retry, and RunFlow

Source: https://devicelab.dev/open-source/maestro-runner/docs/flow-commands

Logic commands for controlling test execution flow, including repeating steps, retrying on failure, and executing sub-flows or inline commands.

```yaml
# Repeat
- repeat:
    times: "3"
    commands:
      - tapOn: "Next"
      - swipe: LEFT

# Retry
- retry:
    maxRetries: "3"
    commands:
      - tapOn: "Submit"

# RunFlow
- runFlow: "login.yaml"
- runFlow:
    commands:
      - tapOn: "Accept"
```