# devicelab-dev/maestro-runner architecture

> Architecture diagram of the GitHub repository devicelab-dev/maestro-runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devicelab-dev/maestro-runner
- Repository: https://github.com/devicelab-dev/maestro-runner

## Overview

maestro-runner executes existing Maestro YAML UI flows against mobile devices, simulators, browsers, or Appium-backed cloud sessions. The principal path is CLI invocation, flow validation and parsing, step execution, platform-driver commands, then test reports. Distinct branches cover device/emulator management, platform automation, Flutter/React Native support, JavaScript scripting, parallel runs, and cloud providers. Relationships among sampled modules follow the source index and excerpts; broader capability links are supported by the README, while unsampled implementation details are not inferred.

Main entry points: [`pkg/cli`](https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/cli) (CLI commands), [`pkg/cli/android.go`](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/cli/android.go) (Android CLI), [`pkg/cli/ios.go`](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/cli/ios.go) (iOS CLI), [`pkg/executor/flow_runner.go`](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/flow_runner.go) (Flow executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Invocation and flows"]
  node_cli["CLI commands"]
  node_npm["npm launcher<br/>[resolve.js]"]
  node_validator["Flow validator<br/>[validator.go]"]
  node_parser["Flow parser<br/>[parser.go]"]
end

subgraph group_execution["Execution services"]
  node_runner["Flow executor<br/>[flow_runner.go]"]
  node_parallel["Parallel runner<br/>[runner.go]"]
  node_scripting["Flow scripting<br/>[scripting.go]"]
  node_jsengine["JavaScript engine<br/>[engine.go]"]
  node_flutter["Flutter support<br/>[wrapper.go]"]
end

subgraph group_platforms["Platform automation"]
  node_android["Android CLI<br/>[android.go]"]
  node_ios["iOS CLI<br/>[ios.go]"]
  node_devicelab["DeviceLab driver"]
  node_uiautomator["UIAutomator2 driver<br/>[client.go]"]
  node_wda["WDA driver<br/>[client.go]"]
  node_iosagent["DeviceLab iOS<br/>[client.go]"]
  node_legacyios["Legacy iOS agent<br/>[client.go]"]
  node_appium["Appium driver<br/>[client.go]"]
end

subgraph group_integrations["Device and cloud"]
  node_devices["Device management"]
  node_emulators["Android emulators<br/>[manager.go]"]
  node_simulators["iOS simulators<br/>[manager.go]"]
  node_cloud["Cloud sessions"]
end

subgraph group_results["Run results"]
  node_reports["Report generation"]
  node_reportindex[("Live report index<br/>[index.go]")]
end

node_user(("Test author"))

node_user -->|"runs flows"| node_cli
node_user -->|"launches via npm"| node_npm
node_npm -->|"resolves binary"| node_cli
node_cli -.->|"preflight checks"| node_validator
node_cli -.->|"loads flow"| node_parser
node_parser -.->|"provides steps"| node_runner
node_runner -->|"dispatches scripts"| node_scripting
node_scripting -->|"evaluates JavaScript"| node_jsengine
node_runner -->|"records results"| node_reports
node_runner -.->|"executes commands"| node_devicelab
node_runner -.->|"executes commands"| node_appium
node_cli -->|"selects platform"| node_android
node_cli -->|"selects platform"| node_ios
node_android -->|"uses default driver"| node_devicelab
node_android -->|"selects driver"| node_uiautomator
node_ios -->|"selects driver"| node_wda
node_ios -->|"uses default driver"| node_iosagent
node_ios -->|"selects legacy driver"| node_legacyios
node_ios -.->|"manages simulators"| node_simulators
node_android -.->|"manages emulators"| node_emulators
node_android -->|"discovers devices"| node_devices
node_ios -->|"supports Flutter"| node_flutter
node_android -->|"supports Flutter"| node_flutter
node_cli -->|"runs in parallel"| node_parallel
node_cli -->|"configures cloud"| node_cloud
node_cloud -->|"uses Appium"| node_appium
node_reports -->|"updates index"| node_reportindex

click node_cli "https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/cli"
click node_npm "https://github.com/devicelab-dev/maestro-runner/blob/main/npm/maestro-runner/lib/resolve.js"
click node_validator "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/validator/validator.go"
click node_parser "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/flow/parser.go"
click node_runner "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/flow_runner.go"
click node_parallel "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/runner.go"
click node_scripting "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/scripting.go"
click node_jsengine "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/jsengine/engine.go"
click node_flutter "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/flutter/wrapper.go"
click node_android "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/cli/android.go"
click node_ios "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/cli/ios.go"
click node_devicelab "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/device/devicelab_driver.go"
click node_uiautomator "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/uiautomator2/client.go"
click node_wda "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/wda/client.go"
click node_iosagent "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/devicelab_ios/client.go"
click node_legacyios "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/devicelab_ios_legacy/client.go"
click node_appium "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/appium/client.go"
click node_devices "https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/device"
click node_emulators "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/emulator/manager.go"
click node_simulators "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/simulator/manager.go"
click node_cloud "https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/cloud"
click node_reports "https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/report"
click node_reportindex "https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/report/index.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_npm,node_validator,node_parser toneBlue
class node_runner,node_parallel,node_scripting,node_jsengine,node_flutter toneAmber
class node_android,node_ios,node_devicelab,node_uiautomator,node_wda,node_iosagent,node_legacyios,node_appium toneMint
class node_devices,node_emulators,node_simulators,node_cloud toneRose
class node_reports,node_reportindex,node_user toneIndigo
```

## Components

### Invocation and flows

- [CLI commands](https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/cli): `pkg/cli`
- [npm launcher](https://github.com/devicelab-dev/maestro-runner/blob/main/npm/maestro-runner/lib/resolve.js): `npm/maestro-runner/lib/resolve.js`
- [Flow validator](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/validator/validator.go): `pkg/validator/validator.go`
- [Flow parser](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/flow/parser.go): `pkg/flow/parser.go`

### Execution services

- [Flow executor](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/flow_runner.go): `pkg/executor/flow_runner.go`
- [Parallel runner](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/runner.go): `pkg/executor/runner.go`
- [Flow scripting](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/executor/scripting.go): `pkg/executor/scripting.go`
- [JavaScript engine](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/jsengine/engine.go): `pkg/jsengine/engine.go`
- [Flutter support](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/flutter/wrapper.go): `pkg/flutter/wrapper.go`

### Platform automation

- [Android CLI](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/cli/android.go): `pkg/cli/android.go`
- [iOS CLI](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/cli/ios.go): `pkg/cli/ios.go`
- [DeviceLab driver](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/device/devicelab_driver.go): `pkg/device/devicelab_driver.go`
- [UIAutomator2 driver](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/uiautomator2/client.go): `pkg/uiautomator2/client.go`
- [WDA driver](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/wda/client.go): `pkg/driver/wda/client.go`
- [DeviceLab iOS](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/devicelab_ios/client.go): `pkg/driver/devicelab_ios/client.go`
- [Legacy iOS agent](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/devicelab_ios_legacy/client.go): `pkg/driver/devicelab_ios_legacy/client.go`
- [Appium driver](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/driver/appium/client.go): `pkg/driver/appium/client.go`

### Device and cloud

- [Device management](https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/device): `pkg/device`
- [Android emulators](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/emulator/manager.go): `pkg/emulator/manager.go`
- [iOS simulators](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/simulator/manager.go): `pkg/simulator/manager.go`
- [Cloud sessions](https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/cloud): `pkg/cloud`

### Run results

- [Report generation](https://github.com/devicelab-dev/maestro-runner/tree/main/pkg/report): `pkg/report`
- [Live report index](https://github.com/devicelab-dev/maestro-runner/blob/main/pkg/report/index.go): `pkg/report/index.go`

### Other components

- **Test author**

## Connections

- Test author → CLI commands: runs flows
- Test author → npm launcher: launches via npm
- npm launcher → CLI commands: resolves binary (evidence: `npm/maestro-runner/lib/resolve.js`)
- CLI commands → Flow validator: preflight checks
- CLI commands → Flow parser: loads flow
- Flow parser → Flow executor: provides steps
- Flow executor → Flow scripting: dispatches scripts (evidence: `pkg/executor/flow_runner.go`)
- Flow scripting → JavaScript engine: evaluates JavaScript (evidence: `pkg/executor/scripting.go`)
- Flow executor → Report generation: records results (evidence: `pkg/executor/flow_runner.go`)
- Flow executor → DeviceLab driver: executes commands
- Flow executor → Appium driver: executes commands
- CLI commands → Android CLI: selects platform
- CLI commands → iOS CLI: selects platform
- Android CLI → DeviceLab driver: uses default driver
- Android CLI → UIAutomator2 driver: selects driver
- iOS CLI → WDA driver: selects driver
- iOS CLI → DeviceLab iOS: uses default driver
- iOS CLI → Legacy iOS agent: selects legacy driver
- iOS CLI → iOS simulators: manages simulators
- Android CLI → Android emulators: manages emulators
- Android CLI → Device management: discovers devices (evidence: `pkg/cli/android.go`)
- iOS CLI → Flutter support: supports Flutter
- Android CLI → Flutter support: supports Flutter
- CLI commands → Parallel runner: runs in parallel
- CLI commands → Cloud sessions: configures cloud
- Cloud sessions → Appium driver: uses Appium
- Report generation → Live report index: updates index (evidence: `pkg/report/index.go`)
