### CI Example: Auto-start Emulator and Run Tests

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

An example of how to integrate maestro-runner into a CI/CD pipeline. This command automatically starts an emulator, runs tests in parallel, and then shuts down the emulator.

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

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

### Install Maestro Runner

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/releases/v1.1.0.md

Installs the Maestro Runner using a curl command. To install a specific version, use the --version flag.

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

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

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

### Install Maestro Runner

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

Installs the maestro-runner using a curl script. You can also specify a version to install.

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

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

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

### New Driver Implementation Example

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/DEVELOPER.md

Provides a basic structure for implementing a new driver, including handling different step types and essential driver methods.

```go
package mydriver

import (
    "github.com/devicelab-dev/maestro-runner/pkg/core"
    "github.com/devicelab-dev/maestro-runner/pkg/flow"
)

type Driver struct {
    findTimeout int
}

func (d *Driver) Execute(step flow.Step) *core.CommandResult {
    switch s := step.(type) {
    case *flow.TapOnStep:
        return d.executeTap(s)
    case *flow.InputTextStep:
        return d.executeInputText(s)
    default:
        return &core.CommandResult{
            Success: false,
            Error:   fmt.Errorf("unsupported step: %s", step.Type()),
        }
    }
}

func (d *Driver) Screenshot() ([]byte, error)       { /* capture screenshot */ }
func (d *Driver) Hierarchy() ([]byte, error)         { /* capture UI hierarchy */ }
func (d *Driver) GetState() *core.StateSnapshot      { /* return current state */ }
func (d *Driver) GetPlatformInfo() *core.PlatformInfo { /* return platform info */ }
func (d *Driver) SetFindTimeout(ms int)              { d.findTimeout = ms }
func (d *Driver) SetWaitForIdleTimeout(ms int) error  { return nil }
```

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

### Provider Registration Example

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/README.md

Demonstrates how to register a new cloud provider using an init function. The factory function checks the Appium URL and returns a provider instance or nil if it doesn't match.

```go
func init() {
    Register(func(appiumURL string) Provider {
        if !strings.Contains(strings.ToLower(appiumURL), "yourprovider") {
            return nil
        }
        return &yourProvider{}
    })
}
```

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

### Add New Step Type Constant

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/DEVELOPER.md

Example of how to define a new step type constant within the `pkg/flow/step.go` file.

```go
const (
    StepMyNewCommand StepType = "myNewCommand"
)
```

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

### Commit Message Example

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/CONTRIBUTING.md

Follow this format for clear and descriptive commit messages, detailing the changes made.

```git
Add support for swipe gestures

- Implement SwipeStep parsing
- Add swipe command to Appium driver
- Add tests for swipe directions
```

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

### Maestro Flow with WebView Interaction

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/releases/v1.1.0.md

Example Maestro flow demonstrating interaction with elements inside a WebView. Elements are found transparently via CDP.

```yaml
- launchApp:
    appId: com.example.app
    clearState: true
- tapOn: "Open WebView"
- assertVisible: "Welcome"        # Found via CDP inside the WebView
- tapOn:
    id: "submit-button"           # CDP element finding
```

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

### Recording Commands

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Commands for starting and stopping screen recording. Note: This feature is planned for Phase 5+ and may not be available in v1 minimum.

```APIDOC
## Recording (Phase 5+; not in v1 minimum)

### `recordStart`

#### Description
Starts screen recording.

#### Inputs
- `outPath` (string) - The host path where the recording will be saved.
- `fps?` (number) - Optional. Frames per second for the recording.
- `quality?` (number) - Optional. Quality setting for the recording.

#### Returns
- `{ recording: true }` (object) - Indicates that recording has started.

### `recordStop`

#### Description
Stops the screen recording.

#### Inputs
- (none)

#### Returns
- `{ bytes: <base64> }` (object) - The recording data as a base64 encoded string.
- `{ outPath }` (object) - The path where the recording was saved on the host.
```

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

### Get Protocol Version

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

The GET /version endpoint returns the current protocol version and the runner build SHA or tag. The Go client asserts protocol version compatibility on connection.

```http
GET /version
```

```json
{
  "protocolVersion": 1,
  "runnerBuild": "<sha-or-tag>"
}
```

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

### Run Maestro Runner for iOS

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/releases/v1.1.0.md

Example of running Maestro Runner for iOS. The --team-id flag is no longer required for auto-detected simulators.

```bash
maestro-runner --platform ios test flow.yaml
```

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

### Run Maestro Runner Tests

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

Executes Maestro YAML flows for different platforms. Supports installing apps, using Appium, and parallel execution.

```bash
maestro-runner test flow.yaml
```

```bash
maestro-runner --platform ios test flow.yaml
```

```bash
maestro-runner --platform web test flow.yaml
```

```bash
maestro-runner --app-file app.apk test flows/
```

```bash
maestro-runner --driver appium --appium-url <server-url> test flow.yaml
```

```bash
maestro-runner test --parallel 3 flows/
```

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

### Run Tests and Checks with Make

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/CONTRIBUTING.md

Use `make test` to run the test suite. Use `make check` to execute all checks, including linting and testing.

```bash
make test
```

```bash
make check
```

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

### App Launch Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Launches an application on the device.

```APIDOC
## Command: appLaunch

### Description
Launches a specified application. If the application is already running, it will be replaced.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application to launch.
- **arguments** (array of strings)? - Optional - Arguments to pass to the application upon launch.
- **environment** (object)? - Optional - Environment variables to set for the application process.

### Returns
- **pid** (integer) - The process ID of the launched application.
- **launched** (boolean) - True if the application was successfully launched.

### Notes
Uses `XCUIApplication(bundleIdentifier:).launch()`. Replaces the cached `currentApp`.
```

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

### Bundle WebDriverAgent

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/WebDriverAgent/README.md

Run this command to create bundles for WebDriverAgent. The resulting zip files contain the necessary components for iOS and tvOS.

```bash
npm run bundle
```

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

### Run Maestro with DeviceLab Driver

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/releases/v1.1.0.md

Execute a Maestro flow using the DeviceLab driver. CDP automatically activates when a WebView is detected on the screen.

```bash
maestro-runner --driver devicelab test webview-flow.yaml
```

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

### App Activate Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Brings an application to the foreground without relaunching it.

```APIDOC
## Command: appActivate

### Description
Brings a specified application to the foreground without relaunching it.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application to activate.

### Returns
- **pid** (integer) - The process ID of the activated application.
- **activated** (boolean) - True if the application was successfully activated.
```

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

### Create New Step Struct

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/DEVELOPER.md

Defines a new step struct, including its fields and a `Describe` method for human-readable output.

```go
type MyNewCommandStep struct {
    BaseStep `yaml:",inline"
    Target   string `yaml:"target"
}

func (s *MyNewCommandStep) Describe() string {
    return fmt.Sprintf("myNewCommand on %s", s.Target)
}
```

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

### App Current Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Retrieves information about the currently foregrounded application.

```APIDOC
## Command: appCurrent

### Description
Returns information about the application that is currently in the foreground.

### Inputs
(none)

### Returns
- **appBundleId** (string)? - The bundle identifier of the foregrounded application (optional).
- **pid** (integer)? - The process ID of the foregrounded application (optional).

```

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

### Screen Size Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Retrieves the screen dimensions and scale of the device.

```APIDOC
## Command: screenSize

### Description
Retrieves the screen size and scale factor of the device.

### Inputs
- **appBundleId** (string)? - Optional - The bundle identifier of the application. This may influence coordinate space resolution.

### Returns
- **width** (float) - The width of the screen in points.
- **height** (float) - The height of the screen in points.
- **scale** (float) - The screen scale factor (e.g., 2.0 or 3.0).
```

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

### Upload App to TestingBot Storage

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/testingbot.md

Upload your application package (.apk, .ipa, or .zip) to TestingBot's storage service using a cURL command. Replace placeholders with your TestingBot credentials and the correct file path.

```bash
curl -X POST "https://api.testingbot.com/v1/storage" \
  -u "YOUR_TESTINGBOT_KEY:YOUR_TESTINGBOT_SECRET" \
  -F "file=@/path/to/app.apk"
```

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

### Benchmark Comparison for Android Drivers

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

Compares the execution time of Maestro flows using DeviceLab, UIAutomator2, and Maestro CLI on a Pixel 4a device. DeviceLab offers significantly faster execution.

```text
Benchmark: 9 flows, 163 steps on Pixel 4a (Android 13)

  DeviceLab:     1m 12s
  UIAutomator2:  2m 24s
  Maestro CLI:   4m 22s
```

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

### Press Button Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Simulates pressing a hardware button on the device.

```APIDOC
## Command: pressButton

### Description
Simulates pressing a specific hardware button on the device.

### Inputs
- **button** (string) - Required - The name of the button to press. Possible values: "home", "lock", "volumeUp", "volumeDown", "appSwitcher".

### Returns
- **pressed** (boolean) - True if the button press was simulated successfully.
```

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

### Enable Parallel Execution with Appium on Sauce Labs

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

Use this command to run multiple Appium sessions concurrently on Sauce Labs. Ensure your Sauce Labs credentials and capabilities are correctly configured.

```bash
maestro-runner \
  --driver appium \
  --parallel 3 \
  --appium-url "https://$SAUCE_USERNAME:$SAUCE_ACCESS_KEY@ondemand.us-west-1.saucelabs.com:443/wd/hub" \
  --caps provider-caps.json \
  test flow_a.yaml flow_b.yaml flow_c.yaml
```

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

### Snapshot Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Captures a snapshot of the application's UI hierarchy.

```APIDOC
## Command: snapshot

### Description
Captures a snapshot of the entire UI hierarchy for a given application or the currently foregrounded app.

### Inputs
- **appBundleId** (string)? - Optional - The bundle identifier of the application to snapshot. If omitted, the currently foregrounded app is snapshotted.

### Returns
- **nodes** (array of SnapshotNode) - An array representing the UI hierarchy.

### Notes
Returns the full tree without filtering, caps, or occlusion computation. The tree is reconstructed via `parentIndex`.
```

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

### Step Interface Definition

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/DEVELOPER.md

Defines the core methods that all flow steps must implement, providing information about the step's type, optionality, and description.

```go
type Step interface {
    Type() StepType
    IsOptional() bool
    Label() string
    Describe() string
}
```

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

### URL Handling Commands

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Command for opening a specified URL on the device.

```APIDOC
## URLs

### `openURL`

#### Description
Opens a given URL on the device. Uses `XCUIDevice.shared.system.open(URL)` on iOS 15+ or a SpringBoard tap path as a fallback.

#### Inputs
- `url` (string) - The URL to open.

#### Returns
- `{ opened: true }` (object) - Indicates that the URL was successfully opened.
```

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

### Maestro Flow Configuration with Timeouts

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

Demonstrates extending standard Maestro YAML flows with additional configuration fields for command and idle timeouts. Use `waitForIdleTimeout: 0` to disable device idle waiting.

```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"
```

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

### Run Maestro Flows on Cloud Device Grids

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

Use this command to execute Maestro YAML flows on cloud device grids via the Appium driver. Ensure you provide the cloud provider's hub URL and a capabilities JSON file.

```bash
maestro-runner --driver appium --appium-url <HUB_URL> --caps caps.json test flows/
```

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

### Protocol Version

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Retrieves the current protocol version and runner build information.

```APIDOC
## GET /version

### Description
Returns the current protocol version and the build SHA or tag of the runner.

### Method
GET

### Endpoint
/version

### Response
#### Success Response (200)
- **protocolVersion** (integer) - The current protocol version.
- **runnerBuild** (string) - The build SHA or tag of the runner.

### Response Example
```json
{
  "protocolVersion": 1,
  "runnerBuild": "<sha-or-tag>"
}
```
```

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

### Find By Class Chain Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Finds UI elements using a class chain query.

```APIDOC
## Command: findByClassChain

### Description
Finds UI elements within an application using a class chain query string.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application.
- **query** (string) - Required - The class chain query string.

### Returns
- **found** (boolean) - True if any elements matching the class chain query were found.
- **nodes** (array of SnapshotNode) - An array of found UI elements as SnapshotNodes.
```

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

### Devicelab iOS Runner Project Layout

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/README.md

This snippet shows the planned directory structure for the devicelab-ios-runner project. It includes the main README, a phased plan, protocol specifications, Xcode project files, UI test target sources, and build scripts.

```bash
devicelab-ios-runner/
├── README.md
├── PLAN.md                       # phased plan and acceptance criteria
├── PROTOCOL.md                   # wire protocol spec (written after Phase 0)
├── .gitignore
├── DevicelabIOSRunner.xcodeproj/ # Xcode project (Phase 2+)
├── DevicelabIOSRunner/           # UI test target sources (fresh Swift)
└── scripts/
    └── build.sh                  # standalone build pipeline
```

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

### Run Maestro Flows on Sauce Labs

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

Command to execute Maestro flows using the Appium driver against Sauce Labs. Ensure to replace placeholders with your Sauce Labs credentials and select the appropriate region endpoint.

```bash
maestro-runner \
  --driver appium \
  --appium-url "https://$SAUCE_USERNAME:$SAUCE_ACCESS_KEY@ondemand.us-west-1.saucelabs.com:443/wd/hub" \
  --caps provider-caps.json \
  test flows/
```

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

### Driver Interface Definition

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/DEVELOPER.md

Defines the core methods that all backend drivers must implement for Maestro to interact with devices.

```go
type Driver interface {
    Execute(step flow.Step) *CommandResult
    Screenshot() ([]byte, error)
    Hierarchy() ([]byte, error)
    GetState() *StateSnapshot
    GetPlatformInfo() *PlatformInfo
    SetFindTimeout(ms int)
    SetWaitForIdleTimeout(ms int) error
}
```

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

### Find By Predicate Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Finds UI elements using a predicate string.

```APIDOC
## Command: findByPredicate

### Description
Finds UI elements within an application using a predicate string.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application.
- **predicate** (string) - Required - The predicate string to match elements.

### Returns
- **found** (boolean) - True if any elements matching the predicate were found.
- **nodes** (array of SnapshotNode) - An array of found UI elements as SnapshotNodes.
```

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

### Provider Interface Definition

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/README.md

Defines the interface that all cloud Appium providers must implement. This includes methods for naming, extracting metadata, and reporting test results.

```go
package cloud

type Provider interface {
    // Name returns the human-readable provider name.
    Name() string

    // ExtractMeta is called once after the Appium session is created.
    // Read what you need from sessionID and caps, write to meta.
    ExtractMeta(sessionID string, caps map[string]interface{}, meta map[string]string)

    // ReportResult is called once after all flows and reports complete.
    // Use meta for provider-specific data, result for test outcome.
    ReportResult(appiumURL string, meta map[string]string, result *TestResult) error
}
```

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

### App State Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Retrieves the current state of an application.

```APIDOC
## Command: appState

### Description
Retrieves the current state of a specified application.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application to query.

### Returns
- **state** (string) - The current state of the application. Possible values: "running", "notRunning", "runningBackground".

```

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

### iOS Real Device Capabilities for Sauce Labs

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

JSON configuration for running Maestro flows on an iOS real device hosted by Sauce Labs. Includes device name, platform version, app details, and specific Sauce Labs options like resigning.

```json
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "iPhone.*",
  "appium:platformVersion": "^(18|26).*",
  "appium:app": "storage:filename=SauceLabs-Demo-App.ipa",
  "sauce:options": {
    "build": "Maestro iOS Run",
    "appiumVersion": "latest",
    "resigningEnabled": true
  }
}
```

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

### iOS Simulator Capabilities for Sauce Labs

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

JSON configuration for running Maestro flows on an iOS simulator provided by Sauce Labs. Details simulator device, platform version, app details, and Appium version.

```json
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "iPhone Simulator",
  "appium:platformVersion": "17.0",
  "appium:app": "storage:filename=SauceLabs-Demo-App.Simulator.zip",
  "sauce:options": {
    "build": "Maestro iOS Simulator Run",
    "appiumVersion": "2.1.3"
  }
}
```

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

### Configure TestingBot iOS Capabilities

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/testingbot.md

Define the capabilities for running iOS tests on TestingBot. Ensure 'tb://app-id' is replaced with your uploaded app's identifier and 'realDevice' is set to true for physical devices.

```json
{
  "platformName": "iOS",
  "appium:deviceName": "iPhone 16",
  "appium:platformVersion": "18.0",
  "appium:app": "tb://app-id",
  "appium:automationName": "XCUITest",
  "tb:options": {
    "key": "YOUR_TESTINGBOT_KEY",
    "secret": "YOUR_TESTINGBOT_SECRET",
    "name": "Maestro iOS test",
    "realDevice": true
  }
}
```

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

### Alert Handling Commands

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Commands for checking the visibility of alerts and for accepting or dismissing them.

```APIDOC
## Alerts

### `alertVisible`

#### Description
Checks if an alert is currently visible on the screen.

#### Inputs
- (none)

#### Returns
- `{ visible: bool, button1Label?, button2Label? }` (object) - An object indicating if an alert is visible, and the labels of the first two buttons if present.

### `alertAccept`

#### Description
Accepts the currently visible alert.

#### Inputs
- (none)

#### Returns
- `{ dismissed: true }` (object) - Indicates that the alert was dismissed.

### `alertDismiss`

#### Description
Dismisses the currently visible alert.

#### Inputs
- (none)

#### Returns
- `{ dismissed: true }` (object) - Indicates that the alert was dismissed.
```

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

### Find By Label Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Finds a UI element by its accessibility label.

```APIDOC
## Command: findByLabel

### Description
Finds a UI element within an application using its accessibility label.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application.
- **label** (string) - Required - The accessibility label of the element to find.
- **exact** (boolean)? - Optional - If true, performs an exact match for the label. Defaults to false (substring match).

### Returns
- **found** (boolean) - True if an element with the specified label was found.
- **node** (SnapshotNode)? - The found UI element as a SnapshotNode (optional).
```

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

### Runtime Settings Commands

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Commands to adjust runtime settings of the device, such as idle timeout and typing frequency.

```APIDOC
## Settings (runtime)

### `setIdleTimeout`

#### Description
Sets the idle timeout for the device. A value of 0 disables the timeout.

#### Inputs
- `timeoutMs` (number) - The idle timeout in milliseconds. Set to 0 to disable.

#### Returns
- `{ set }` (object) - Indicates if the setting was successfully applied.

### `setTypingFrequency`

#### Description
Sets the typing frequency in characters per second.

#### Inputs
- `freq` (number) - The typing frequency in characters per second.

#### Returns
- `{ set }` (object) - Indicates if the setting was successfully applied.

### `setFindTimeout`

#### Description
Sets the timeout for find operations.

#### Inputs
- `timeoutMs` (number) - The timeout in milliseconds.

#### Returns
- `{ set }` (object) - Indicates if the setting was successfully applied.
```

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

### Find By Identifier Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Finds a UI element by its accessibility identifier.

```APIDOC
## Command: findByIdentifier

### Description
Finds a UI element within an application using its accessibility identifier.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application.
- **identifier** (string) - Required - The accessibility identifier of the element to find.

### Returns
- **found** (boolean) - True if an element with the specified identifier was found.
- **node** (SnapshotNode)? - The found UI element as a SnapshotNode (optional).
```

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

### Run Maestro Android Tests on TestingBot

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/testingbot.md

Execute Maestro YAML flows on Android devices hosted by TestingBot. This command uses the specified capabilities file and TestingBot's Appium hub URL.

```bash
maestro-runner --driver appium \
  --appium-url "https://hub.testingbot.com/wd/hub" \
  --caps testingbot-android.json \
  test flows/
```

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

### App Terminate Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Terminates a running application.

```APIDOC
## Command: appTerminate

### Description
Terminates a specified running application.

### Inputs
- **appBundleId** (string) - Required - The bundle identifier of the application to terminate.

### Returns
- **terminated** (boolean) - True if the application was successfully terminated.
```

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

### Configure TestingBot Android Capabilities

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/testingbot.md

Define the capabilities for running Android tests on TestingBot. Ensure 'tb://app-id' is replaced with your uploaded app's identifier.

```json
{
  "platformName": "Android",
  "appium:deviceName": "Pixel 8",
  "appium:platformVersion": "14.0",
  "appium:app": "tb://app-id",
  "appium:automationName": "UiAutomator2",
  "tb:options": {
    "key": "YOUR_TESTINGBOT_KEY",
    "secret": "YOUR_TESTINGBOT_SECRET",
    "name": "Maestro Android test"
  }
}
```

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

### Create a Feature Branch

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/CONTRIBUTING.md

Before making changes, create a new branch for your feature using `git checkout -b feature/my-feature`.

```bash
git checkout -b feature/my-feature
```

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

### Ping Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Checks the runner's responsiveness and calculates round-trip time.

```APIDOC
## Command: ping

### Description
Sends a ping to the runner to check its responsiveness and measure round-trip time.

### Inputs
(none)

### Returns
- **uptimeMs** (integer) - The uptime of the runner in milliseconds.
```

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

### Android Real Device Capabilities for Sauce Labs

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

JSON configuration for running Maestro flows on an Android real device hosted by Sauce Labs. Specifies device name, platform version, and app details.

```json
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Samsung.*",
  "appium:platformVersion": "^1[5-6].*",
  "appium:app": "storage:filename=mda-2.2.0-25.apk",
  "sauce:options": {
    "build": "Maestro Android Run",
    "appiumVersion": "latest"
  }
}
```

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

### Run Maestro Flows with DeviceLab Driver

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/README.md

Executes Maestro flows on an Android device using the DeviceLab WebSocket driver. This command enables faster test execution compared to the default UIAutomator2 driver.

```bash
maestro-runner --driver devicelab --platform android test flows/
```

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

### Run JavaScript File in WebView

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/releases/v1.1.0.md

Execute a JavaScript file within a mobile WebView using `runWebViewScript`. This command supports environment variables and capturing output.

```yaml
# Simple file execution
- runWebViewScript: scripts/extract-data.js
```

```yaml
# With environment variables and output
- runWebViewScript:
    file: scripts/validate-cart.js
    env:
      EXPECTED_TOTAL: "29.99"
    output: validationResult
```

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

### Command Execution

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Commands are sent to the runner via HTTP POST requests to the /command endpoint. The request body must be a JSON object containing the command details. The runner responds with a JSON object indicating success or failure.

```APIDOC
## POST /command

### Description
Executes a command on the Devicelab iOS Runner.

### Method
POST

### Endpoint
/command

### Request Body
- **command** (string) - Required - The type of command to execute.
- **appBundleId** (string) - Optional - The bundle ID of the app to target (required for app-specific commands).

### Request Example
```json
{
  "command": "someCommandType",
  "appBundleId": "com.example.MyApp"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the command was successful.
- **data** (object) - Command-specific data returned upon success.

#### Response Example
```json
{
  "ok": true,
  "data": {}
}
```

#### Error Response
- **ok** (boolean) - Indicates if the command failed.
- **error** (object) - Contains error details if the command failed.
  - **code** (string) - An error code indicating the type of failure.
  - **message** (string) - A human-readable error message.
  - **details** (object) - Optional structured context about the error.

#### Error Response Example
```json
{
  "ok": false,
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "The specified element could not be found."
  }
}
```
```

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

### Run Flows with Included Tags using Maestro CLI

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

Use the --include-tags flag in the maestro-runner CLI to execute only flows that match at least one of the specified tags.

```bash
maestro-runner --driver appium --appium-url "..." --caps provider-caps.json \
  test --include-tags smoke --include-tags quick flows/
```

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

### Android Emulator Capabilities for Sauce Labs

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

JSON configuration for running Maestro flows on an Android emulator provided by Sauce Labs. Specifies emulator device, platform version, and app details.

```json
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Google Pixel 9 Emulator",
  "appium:platformVersion": "16.0",
  "appium:app": "storage:filename=mda-2.2.0-25.apk",
  "sauce:options": {
    "build": "Maestro Android Emulator Run",
    "appiumVersion": "2.11.0"
  }
}
```

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

### Rotate Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Changes the device's screen orientation.

```APIDOC
## Command: rotate

### Description
Changes the device's screen orientation to a specified orientation.

### Inputs
- **orientation** (string) - Required - The desired orientation. Possible values: "portrait", "landscapeLeft", "landscapeRight", "portraitUpsideDown".

### Returns
- **orientation** (string) - The new orientation of the device.
```

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

### Shutdown Command

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Initiates a clean shutdown of the runner.

```APIDOC
## Command: shutdown

### Description
Initiates a clean shutdown of the runner process.

### Inputs
(none)

### Returns
- **shuttingDown** (boolean) - True if the shutdown process has been initiated.
```

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

### Configure Sauce Labs Test Name via Capabilities

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

Set the Sauce Labs job name by including the 'name' field within the 'sauce:options' section of your capabilities JSON.

```json
"sauce:options": {
  "name": "My regression suite",
  "build": "Maestro Android Run",
  "appiumVersion": "latest"
}
```

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

### Run Maestro iOS Tests on TestingBot

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/testingbot.md

Execute Maestro YAML flows on iOS devices hosted by TestingBot. This command utilizes the defined capabilities and TestingBot's Appium endpoint.

```bash
maestro-runner --driver appium \
  --appium-url "https://hub.testingbot.com/wd/hub" \
  --caps testingbot-ios.json \
  test flows/
```

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

### Successful Response Envelope

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Structure for a successful response from the runner, containing an 'ok' field and a 'data' object with command-specific results.

```json
{
  "ok": true,
  "data": { /* command-specific */ }
}
```

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

### Text Manipulation Commands

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Commands for typing text, erasing text, simulating key presses, and managing clipboard content.

```APIDOC
## Text Commands

### `type`

#### Description
Sends keys to the currently focused element. The caller is responsible for tapping to focus first.

#### Inputs
- `text` (string) - The text to type.
- `typingFrequency?` (number) - Optional. The frequency of typing in characters per second.

#### Returns
- `{ typed }` (object) - Indicates the result of the typing operation.

### `eraseText`

#### Description
Deletes a specified number of characters from the current text input.

#### Inputs
- `count` (number) - The number of characters to delete.

#### Returns
- `{ erased }` (object) - Indicates the result of the erase operation.

### `keyPress`

#### Description
Simulates a key press event.

#### Inputs
- `key` (string) - The key to press. Must be one of: `"enter"`, `"tab"`, `"backspace"`, `"escape"`.

#### Returns
- `{ pressed }` (object) - Indicates the result of the key press operation.

### `clipboardGet`

#### Description
Retrieves the current text content of the clipboard.

#### Inputs
- (none)

#### Returns
- `{ text }` (object) - The text content of the clipboard.

### `clipboardSet`

#### Description
Sets the clipboard content to the specified text.

#### Inputs
- `text` (string) - The text to set to the clipboard.

#### Returns
- `{ set: true }` (object) - Indicates that the clipboard content was successfully set.
```

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

### Command Request Envelope

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

Defines the structure for commands sent to the runner. Includes the command type and app bundle ID for app-related commands.

```json
{
  "command": "<commandType>",
  "appBundleId": "<bundle-id>",          // required for app-targeted commands
  // ... command-specific fields
}
```

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

### Hardcoded Android Driver Port

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/DESIGN.md

Illustrates the hardcoded default port for the Android driver, which prevents parallel execution on the same machine.

```kotlin
// AndroidDriver.kt
private const val DefaultDriverHostPort = 7001  // No parallel execution
```

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

### Skip Flows with Excluded Tags using Maestro CLI

Source: https://github.com/devicelab-dev/maestro-runner/blob/main/docs/cloud-providers/saucelabs.md

Use the --exclude-tags flag in the maestro-runner CLI to skip flows that match any of the specified tags.

```bash
maestro-runner --driver appium --appium-url "..." --caps provider-caps.json \
  test --exclude-tags slow flows/
```