Maestro Usage

Maestro Usage

Quick reference for writing Maestro E2E flows. For the full command API, see resources/api-reference.md. For testing patterns and pitfalls, see resources/best-practices.md.

Flow File Structure

Every Maestro flow is a YAML file with an optional header section separated from commands by ---:

appId: com.example.app
name: "My Test Flow"
env:
  USERNAME: "test@example.com"
  PASSWORD: "password123"
tags:
  - smoke
  - regression
---
- launchApp:
    clearState: true
- tapOn: "Login"
- inputText: "test@example.com"

Header Fields

Command Quick Reference

Interaction

Navigation & App Lifecycle

Assertions

Waiting

Flow Control

Clipboard & Text

Device & Media

Recording & Screenshots

AI-Powered (Experimental)

Selectors

Selectors identify which UI element a command targets. Combine them for precision.

Core

• text: Visible text or accessibility label (regex). - tapOn: "Login" is shorthand for text: "Login".
• id: Accessibility identifier / resource ID (regex).
• index: 0-based index when multiple elements match.
• point: Screen coordinates ("50%, 50%" or "100, 250").
• css: CSS selector (web only).

Relational

• above / below / leftOf / rightOf: Position relative to an anchor element.
• containsChild: Parent with a direct child matching criteria.
• childOf: Element that is a direct child of a parent.
• containsDescendants: Parent with specific descendants at any depth.

State

• enabled: true / false — interactive state.
• checked: true / false — checkbox/switch state.
• focused: true / false — has keyboard focus.
• selected: true / false — selected tab/segment.

Traits

• traits: text: Any element containing text.
• traits: long-text: Element with 200+ characters.
• traits: square: Element with ~1:1 aspect ratio.

Common Arguments

Every command supports these optional fields:

• label: Custom display name for the step in output.
• optional: If true, flow continues even if the command fails (logged as warning).

Conditions (when)

runFlow and runScript support conditional execution:

- runFlow:
    when:
      visible: "Some Element"      # element is visible
      # notVisible: "Other"        # element is NOT visible
      # platform: iOS              # platform check (Android|iOS|Web)
      # true: ${MY_VAR == 'yes'}   # JavaScript expression
    commands:
      - tapOn: "Some Element"

Multiple conditions are ANDed together.

Environment Variables

Access env vars with ${VAR_NAME} syntax anywhere in YAML values:

env:
  USERNAME: "default_user"
---
- inputText: ${USERNAME}

Override at runtime: maestro test -e USERNAME=other_user flow.yaml

JavaScript Integration

Use runScript to execute JS files. Access env vars directly. Use output object to pass data back to the flow:

// scripts/setup.js
var name = "User_" + Date.now();
output.generatedName = name;

- runScript: scripts/setup.js
- inputText: ${output.generatedName}

HTTP Requests in JS

var response = http.get("https://api.example.com/data");
var data = json(response.body);
output.userId = data.id;

Methods: http.get(), http.post(), http.put(), http.delete(), http.request().

CLI Commands

Additional Resources

• Full command API with all options: resources/api-reference.md
• JavaScript & HTTP reference: resources/javascript-reference.md
• CLI commands & flags: resources/cli-reference.md
• Best practices and patterns: resources/best-practices.md
• Maestro MCP tool reference: resources/mcp-reference.md
• Annotated examples: examples/ (utilities, test flows, advanced patterns, project structure)
• Official docs: https://maestro.mobile.dev