maestro-runner Documentation

The devicelab-ios-runner is an XCUITest-based iOS automation runner designed for use with the devicelab driver in the maestro-runner project. It serves as the iOS counterpart to the devicelab-android-driver.

Its primary objectives are to provide a self-contained, owned XCUITest runner that eliminates runtime third-party downloads and ensures local parity with upstream Maestro flows, including matching retry profiles.

WebDriverAgent is a WebDriver server implementation for iOS and tvOS. It enables remote control of devices and simulators by linking XCTest.framework and calling Apple's APIs directly.

Key capabilities include:

• Launching and killing applications.
• Tapping and scrolling views.
• Confirming view presence on a screen.
• Implementing most of the WebDriver Spec and parts of the Mobile JSON Wire Protocol Spec.

The devicelab driver is an optimized Android driver that runs automation directly on the device via WebSocket, bypassing the UIAutomator2 HTTP layer. It is approximately 2x faster than the default UIAutomator2 driver and 5x faster than the standard Maestro CLI. It includes features like bounds stabilization for animated elements and improved special character handling.

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

The runner is built using a specific architectural stack designed for reliable automation:

• Core Engine: XCUITest
• Communication: Network.framework providing an HTTP interface
• Command Format: JSON command protocol

This design allows the runner to receive commands over the network and execute them on-device via XCUITest.

The communication protocol between the maestro-runner Go driver and the iOS runner is based on the agent-device contract. This includes:

• Command/Response shapes: Defined in RunnerTests+Models.swift.
• Transport: HTTP/JSON transport defined in RunnerTests+Transport.swift.
• Dispatch logic: Defined in RunnerTests+CommandExecution.swift.

The Go driver located in pkg/driver/devicelab_ios/ is responsible for translating Maestro flow steps into these specific command shapes.

The maestro-runner operates through a three-stage pipeline to execute automation flows:

1. YAML Parser (pkg/flow): Converts Maestro YAML flow files into typed Step structures.
2. Executor (pkg/executor): Orchestrates the execution lifecycle and delegates specific commands to the active Driver implementation.
3. Report Generator (pkg/report): Compiles execution data into JSON or HTML reports.

This separation allows the runner to support multiple device backends (drivers) while maintaining a consistent flow definition and reporting format.

maestro-runner automatically detects and interacts with cloud Appium providers based on the --appium-url flag. The integration follows a three-step lifecycle:

1. Detect: After parsing --appium-url, registered providers check if the URL matches their identifier (e.g., containing "saucelabs").
2. Extract metadata: Once an Appium session is created, the provider reads session capabilities and stores provider-specific data (like jobID or session type) in a map[string]string.
3. Report result: After all flows and reports are finished, the provider receives the TestResult and reports the pass/fail status to the cloud API.

No additional flags are required for detection and reporting to function.

maestro-runner is designed as a pluggable execution engine for Maestro YAML flow files. It decouples the test definition from the execution backend through three independent layers:

1. YAML Parser (pkg/flow): Responsible for parsing Maestro YAML files into typed step structures. This layer is isolated so that changes to the YAML syntax do not affect the drivers.
2. Driver (pkg/core, pkg/driver): A standardized interface that all backends must implement. This allows the runner to support multiple execution engines (like UIAutomator2, Appium, or WDA) interchangeably.
3. Report (pkg/report): Consumes the results of the execution to generate outputs such as JSON or HTML reports. This layer is independent of both the parser and the driver.

This separation allows you to add new drivers (e.g., Detox) or new report formats without modifying the parser or existing drivers.

The name displayed in Sauce Labs for a job or session is determined by the following priority:

1. sauce:options.name: If provided in your capabilities JSON, this value is used to name the session/job.
2. YAML Flow Basename: If no name is provided in capabilities, the runner uses the filename of the Maestro flow (excluding the .yaml or .yml extension).

Note: If multiple flows run sequentially within a single Appium session, the session name is taken from the first flow in that sequence.

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

To prevent character loss in React Native SecureTextField components on iOS Simulators (where hasKeyboardFocus often remains false), the runner uses a synthetic typing path.

When a target is identified as a .secureTextField, the runner uses DLSendSyntheticTyping (via SyntheticTyping.h/m) which bypasses standard keyboard-focus checks. For non-secure fields, the runner continues to use the standard app.typeText method. If the synthetic path fails, it falls back to app.typeText to ensure compatibility.