Complete List of Supported Commands in Maestro YAML: 40+ Operations for Mobile UI Testing

Maestro supports over 40 distinct YAML commands defined as Kotlin data classes in Commands.kt, covering gestures, assertions, app lifecycle, clipboard operations, AI-powered visual checks, and flow control.

Maestro is an open-source mobile UI testing framework created by mobile-dev-inc. The framework uses YAML-based flow files where each step corresponds to a specific command class in the orchestration model. Understanding the complete command taxonomy is essential for writing comprehensive end-to-end tests for iOS and Android applications.

How Commands Map to YAML Syntax

Maestro defines every possible YAML action as a concrete command class in maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt. The YAML parser exposes these through MaestroCommand.kt, where each command is stored as a nullable property:

data class MaestroCommand(
    val tapOnElement: TapOnElementCommand? = null,
    val tapOnPoint: TapOnPointCommand? = null,
    val tapOnPointV2Command: TapOnPointV2Command? = null,
    // ... other command fields
)

The top-level keys in a Maestro flow file are the lower-camelCase versions of the command class names. For example, TapOnElementCommand becomes tapOn, and ScrollUntilVisibleCommand becomes scrollUntilVisible.

Gesture and Interaction Commands

These commands simulate user touch inputs and navigation gestures.

tapOn and tapOnPoint

The tapOn command maps to TapOnElementCommand and supports tapping elements via selectors, with options for long-press, double-tap, and repeat counts:

- tapOn:
    selector: "id:login_button"
    repeat: 2
    longPress: 500

For coordinate-based tapping, use tapOnPointV2 (mapping to TapOnPointV2Command), which accepts percentage or pixel strings:

- tapOnPointV2: "50%,30%"

Avoid tapOnPoint (mapping to TapOnPointCommand), which is deprecated.

swipe and scroll

The swipe command (SwipeCommand) supports directional swipes or point-to-point gestures:

- swipe:
    direction: up
    duration: 500

For scrolling until an element appears, use scrollUntilVisible (ScrollUntilVisibleCommand):

- scrollUntilVisible:
    selector: "text:Continue"
    direction: down
    scrollDuration: fast
    visibilityPercentage: 80
    timeout: 15000
    centerElement: true

Simple scrolling uses scroll (ScrollCommand).

Navigation and Hardware Keys

Simulate system navigation with backPress (BackPressCommand) and hardware keys with pressKey (PressKeyCommand):

- backPress
- pressKey: home
- pressKey: volumeUp

Dismiss the keyboard using hideKeyboard (HideKeyboardCommand).

Assertion and Verification Commands

These commands validate UI state and visual appearance.

Standard Assertions

The assertCondition command (AssertConditionCommand) provides general-purpose assertions with optional timeouts:

- assertCondition:
    visible: "text:Welcome"
    timeout: 5000

Avoid the deprecated assert command (AssertCommand).

Visual and AI-Based Assertions

Compare screenshots using assertScreenshot (AssertScreenshotCommand):

- assertScreenshot:
    image: "baseline/home.png"
    threshold: 0.01

For AI-powered visual testing, use assertWithAI (AssertWithAICommand) and assertNoDefectsWithAI (AssertNoDefectsWithAICommand):

- assertWithAI:
    screenshot: "baseline/home.png"
    threshold: 0.02
- assertNoDefectsWithAI

Extract text via OCR using extractTextWithAI (ExtractTextWithAICommand).

App Lifecycle and System Commands

Manage application state and device configuration.

Application Control

Launch apps with launchApp (LaunchAppCommand):

- launchApp:
    appId: "com.example.myapp"
    arguments:
      username: "test"

Stop or kill applications using stopApp (StopAppCommand) and killApp (KillAppCommand):

- stopApp: "com.example.myapp"
- killApp: "com.example.myapp"

Clear application state with clearState (ClearStateCommand) and keychain data (iOS) with clearKeychain (ClearKeychainCommand).

Device Configuration

Set permissions with setPermissions (SetPermissionsCommand):

- setPermissions:
    appId: "com.example.myapp"
    permissions:
      all: allow

Change device orientation using setOrientation (SetOrientationCommand):

- setOrientation: landscape

Mock GPS location with setLocation (SetLocationCommand) or simulate movement with travel (TravelCommand).

Configure network settings using setAirplaneMode (SetAirplaneModeCommand) or toggleAirplaneMode (ToggleAirplaneModeCommand).

Apply general device configurations with applyConfiguration (ApplyConfigurationCommand).

Clipboard and Text Input Commands

Manage text entry and clipboard operations.

Text Input

Type text with inputText (InputTextCommand):

- inputText: "Hello, World!"

Erase existing text using eraseText (EraseTextCommand):

- eraseText:
    characters: 10

Input random data with inputRandom (InputRandomCommand):

- inputRandom:
    type: username

Clipboard Operations

Copy text from elements using copyTextFrom (CopyTextFromCommand):

- copyTextFrom:
    selector: "id:email_field"

Set clipboard content directly with setClipboard (SetClipboardCommand):

- setClipboard: "copied text"

Paste clipboard content with pasteText (PasteTextCommand):

- pasteText

Flow Control and Logic Commands

Orchestrate complex test scenarios with control flow structures.

Flow Execution

Execute nested flows with runFlow (RunFlowCommand):

- defineVariables:
    env:
      USERNAME: "test_user"
      PASSWORD: "s3cr3t"

- runFlow:
    file: "./login-flow.yaml"
    env:
      USERNAME: ${env.USERNAME}

Define variables using defineVariables (DefineVariablesCommand).

Scripting

Execute JavaScript with runScript (RunScriptCommand):

- runScript:
    file: "script.js"
    env:
      myVar: "value"

Evaluate scripts without return values using evalScript (EvalScriptCommand):

- evalScript: "console.log('debug')"

Repetition and Retry

Repeat actions with repeat (RepeatCommand):

- repeat:
    times: 3
    commands:
      - tapOn: "id:increment_button"

Retry on failure with retry (RetryCommand):

- retry:
    maxRetries: 3
    delay: 1000
    commands:
      - tapOn: "id:flaky_button"

Recording and Media Commands

Capture screen recordings and manage media files.

Record screen sessions using startRecording (StartRecordingCommand) and stopRecording (StopRecordingCommand):

- startRecording:
    path: "/tmp/recording.mp4"
- tapOn: "text:Start"
- stopRecording

Capture static screenshots with takeScreenshot (TakeScreenshotCommand):

- takeScreenshot: "login_screen"

Add media files to the device using addMedia (AddMediaCommand):

- addMedia:
    - "image1.png"
    - "video1.mp4"

Wait for UI animations to settle using waitForAnimationToEnd (WaitForAnimationToEndCommand).

Deprecated Commands to Avoid

Several commands remain in the codebase for backward compatibility but should be replaced with modern alternatives:

• assert (AssertCommand) — Use assertCondition instead for general-purpose assertions.
• tapOnPoint (TapOnPointCommand) — Use tapOnPointV2 instead, which supports percentage-based and string-based coordinates.

These deprecated commands are defined in Commands.kt alongside their replacements but may be removed in future releases.

Summary

• Maestro defines 40+ concrete command classes in Commands.kt that map directly to YAML keys using lower-camelCase naming.
• The MaestroCommand.kt wrapper class holds exactly one command per step, serving as the YAML parser's entry point.
• Commands cover gestures (tapOn, swipe, scroll), assertions (assertCondition, assertWithAI), app lifecycle (launchApp, killApp), flow control (runFlow, repeat, retry), and device configuration (setLocation, setOrientation).
• Avoid deprecated commands like assert and tapOnPoint in favor of assertCondition and tapOnPointV2.

Frequently Asked Questions

What is the difference between tapOn and tapOnPointV2?

tapOn maps to TapOnElementCommand and requires a selector to identify a UI element, while tapOnPointV2 maps to TapOnPointV2Command and accepts absolute coordinates as a string (e.g., "50%,30%"). Use tapOn for element-based interactions and tapOnPointV2 for coordinate-based tapping when elements are not reliably selectable.

How do I run a sub-flow with environment variables in Maestro?

Use the runFlow command (RunFlowCommand) with the env parameter to pass variables, and defineVariables (DefineVariablesCommand) to declare them at the parent level:

- defineVariables:
    env:
      USERNAME: "test_user"
- runFlow:
    file: "./login-flow.yaml"
    env:
      USERNAME: ${env.USERNAME}

Which assertion command should I use for checking element visibility?

Use assertCondition (AssertConditionCommand) instead of the deprecated assert command. The modern command supports flexible conditions and optional timeouts:

- assertCondition:
    visible: "text:Welcome"
    timeout: 5000

What commands are available for AI-powered testing in Maestro?

Maestro provides four AI-specific commands defined in Commands.kt: assertWithAI (AssertWithAICommand) for image comparison against baselines, assertNoDefectsWithAI (AssertNoDefectsWithAICommand) for defect detection without references, extractTextWithAI (ExtractTextWithAICommand) for OCR operations, and standard assertion commands that can utilize AI selectors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}