How mobile-dev-inc/maestro works
Purpose and entry points
Maestro is a JVM-based, cross-platform UI/E2E automation framework for Android, iOS, and web. Users write YAML flows; the CLI parses, validates, executes, and reports them against local or cloud devices. Main entry points are the CLI application and command layer: maestro-cli/src/main/java/maestro/cli/App.kt, maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt, and MCP server command support in maestro-cli/src/main/java/maestro/cli/command/McpCommand.kt.
Flow language and shared domain model
The platform-independent contract is a typed flow model: commands, selectors, conditions, configuration, and workspace metadata. This is the boundary between YAML authoring and runtime execution. Core definitions live in maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt, maestro-orchestra-models/src/main/java/maestro/orchestra/ElementSelector.kt, and maestro-orchestra-models/src/main/java/maestro/orchestra/MaestroConfig.kt.
Parse, validate, and plan flows
The orchestra module turns YAML files into typed commands, reports syntax/validation errors with source context, resolves subflow dependencies, and plans workspace execution order/filtering. This stage prevents invalid paths, malformed commands, and unsupported configuration before device interaction. Key paths: maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt, maestro-orchestra/src/main/java/maestro/orchestra/workspace/WorkspaceExecutionPlanner.kt, and maestro-orchestra/src/main/java/maestro/orchestra/validation/AppValidator.kt.
Execution engine and artifacts
Orchestra interprets the normalized command list against a Maestro device session, applying synchronization, selectors, interactions, assertions, retries, scripts, screenshots, recording, and nested flows. It emits listener events and captures failure/debug artifacts; CLI runners turn those events into terminal, HTML, or JUnit output. Core paths: maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt, maestro-client/src/main/java/maestro/Maestro.kt, and maestro-orchestra/src/main/kotlin/maestro/orchestra/debug/ArtifactCollector.kt.
Device abstraction and platform adapters
maestro-client defines the common Driver/device/view-hierarchy API and selects platform implementations. Android communicates through ADB and bundled APK services; iOS uses an installed XCTest driver over local device/simulator tooling; web uses Chrome DevTools Protocol/Selenium-oriented components. Important boundaries: maestro-client/src/main/java/maestro/Driver.kt, maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt, maestro-client/src/main/java/maestro/drivers/IOSDriver.kt, and maestro-client/src/main/java/maestro/drivers/CdpWebDriver.kt.
On-device drivers and OS dependencies
Android driver code is an instrumentation/service implementation that exposes accessibility hierarchy, screenshots, input, settings, location, and media operations. iOS has both Kotlin-side XCTest client/installer code and a Swift/Objective-C XCTest runner that hosts route handlers. Platform runtimes include Android SDK/ADB/emulators, Xcode/simctl/XCTest/iOS devices, Chrome/CDP, Java 17+, and GraalJS for flow scripts. Paths: maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt, maestro-ios-driver/src/main/kotlin/xcuitest/XCTestDriverClient.kt, maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/XCTestHTTPServer.swift, and maestro-client/src/main/java/maestro/js/GraalJsEngine.kt.
Integrations: cloud, AI, and MCP
The CLI optionally authenticates to Maestro services for cloud execution/device listing, analytics, updates, and cloud artifacts. It also embeds an MCP server so coding agents can run flows and inspect/control live devices; its viewer includes a separate TypeScript/Vite frontend. AI commands use cloud prediction and provider clients for visual assertions/text extraction, including Anthropic and OpenAI integrations. Paths: maestro-cli/src/main/java/maestro/cli/cloud/CloudInteractor.kt, maestro-cli/src/main/java/maestro/cli/mcp/McpServer.kt, maestro-ai/src/main/java/maestro/ai/CloudPredictionAIEngine.kt, and maestro-ai/src/main/java/maestro/ai/anthropic/Client.kt.
Build and delivery
This is a Gradle multi-module repository rooted at settings.gradle.kts and build.gradle.kts. GitHub Actions build and test the CLI and demo app, publish CLI releases/snapshots, publish schemas, and rebuild iOS drivers. End-to-end fixtures center on a Flutter demo application and YAML workspaces: e2e/run_tests, e2e/demo_app/lib/main.dart, and .github/workflows/test-e2e.yaml.
Main entry points: Orchestra.kt Orchestra engine · Driver.kt Driver API · App.kt CLI application · TestCommand.kt Test command
Components 23
CLI & integrations
- CLI application · Primary user entry point.
maestro-cli/src/main/java/maestro/cli/App.kt - Test command
maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt - MCP server · Lets coding agents run flows and inspect devices.
maestro-cli/src/main/java/maestro/cli/mcp/McpServer.kt - Cloud interactor · Cloud runs, devices, artifacts, auth, and analytics.
maestro-cli/src/main/java/maestro/cli/cloud/CloudInteractor.kt - Cloud AI engine · Visual assertions and text extraction through cloud/provider clients.
maestro-ai/src/main/java/maestro/ai/CloudPredictionAIEngine.kt
Flow processing
- Typed flow model · Commands, selectors, conditions, and configuration.
maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt - YAML flow parser · Converts authored YAML to typed flows with source context.
maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt - Flow validator · Rejects malformed commands and unsupported configuration.
maestro-orchestra/src/main/java/maestro/orchestra/validation/AppValidator.kt - Workspace planner · Resolves subflows, ordering, and filtering.
maestro-orchestra/src/main/java/maestro/orchestra/workspace/WorkspaceExecutionPlanner.kt
Execution & devices
- Orchestra engine · Executes normalized commands with retries, assertions, scripts, and nested flows.
maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt - Artifact collector · Captures failure and debugging evidence.
maestro-orchestra/src/main/kotlin/maestro/orchestra/debug/ArtifactCollector.kt - Maestro session · Execution-facing device session API.
maestro-client/src/main/java/maestro/Maestro.kt - Driver API · Common device and view-hierarchy contract.
maestro-client/src/main/java/maestro/Driver.kt - Android driver
maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt - iOS driver
maestro-client/src/main/java/maestro/drivers/IOSDriver.kt - Web driver
maestro-client/src/main/java/maestro/drivers/CdpWebDriver.kt
Platform runtimes
- Android driver service · Provides hierarchy, input, screenshots, settings, and media operations.
maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt - XCTest driver client · Installs and communicates with the XCTest driver.
maestro-ios-driver/src/main/kotlin/xcuitest/XCTestDriverClient.kt - XCTest HTTP runner · Hosts XCTest route handlers.
maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/XCTestHTTPServer.swift - GraalJS engine
maestro-client/src/main/java/maestro/js/GraalJsEngine.kt
Build & delivery
- Gradle multi-module build
settings.gradle.kts - E2E fixtures
e2e/run_tests - GitHub Actions E2E · Builds, tests, publishes, and rebuilds platform drivers.
.github/workflows/test-e2e.yaml
Connections 24
- CLI application → Test command: dispatches
- CLI application → MCP server: starts
- Test command → YAML flow parser: loads flows
- YAML flow parser → Typed flow model: produces
- Typed flow model → Flow validator: validates
- Flow validator → Workspace planner: approved flows
- Workspace planner → Orchestra engine: execution plan
- Orchestra engine → Maestro session: drives
- Orchestra engine → Artifact collector: captures debug data
- Orchestra engine → GraalJS engine: runs scripts
- Orchestra engine → Cloud AI engine: uses AI assertions
- Maestro session → Driver API: uses
- Driver API → Android driver: selects
- Driver API → iOS driver: selects
- Driver API → Web driver: selects
- Android driver → Android driver service: ADB/service protocol
- iOS driver → XCTest driver client: installs and connects
- XCTest driver client → XCTest HTTP runner: XCTest routes
- CLI application → Cloud interactor: optional cloud operations
- MCP server → Maestro session: inspects and controls
- Gradle multi-module build → CLI application: builds
- GitHub Actions E2E → Gradle multi-module build: builds and publishes
- GitHub Actions E2E → E2E fixtures: runs
- E2E fixtures → Test command: exercises