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

> Explore over 40 Maestro YAML commands for mobile UI testing. Automate gestures, assertions, app lifecycles, and AI visual checks with this comprehensive list.

- Repository: [Maestro/Maestro](https://github.com/mobile-dev-inc/Maestro)
- Tags: api-reference
- Published: 2026-03-20

---

**Maestro supports over 40 distinct YAML commands defined as Kotlin data classes in [`Commands.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt). The YAML parser exposes these through [`MaestroCommand.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/MaestroCommand.kt), where each command is stored as a nullable property:

```kotlin
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:

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

```

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

```yaml
- 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:

```yaml
- swipe:
    direction: up
    duration: 500

```

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

```yaml
- 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`):

```yaml
- 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:

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

```

Avoid the deprecated `assert` command (`AssertCommand`).

### Visual and AI-Based Assertions

Compare screenshots using `assertScreenshot` (`AssertScreenshotCommand`):

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

```

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

```yaml
- 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`):

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

```

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

```yaml
- 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`):

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

```

Change device orientation using `setOrientation` (`SetOrientationCommand`):

```yaml
- 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`):

```yaml
- inputText: "Hello, World!"

```

Erase existing text using `eraseText` (`EraseTextCommand`):

```yaml
- eraseText:
    characters: 10

```

Input random data with `inputRandom` (`InputRandomCommand`):

```yaml
- inputRandom:
    type: username

```

### Clipboard Operations

Copy text from elements using `copyTextFrom` (`CopyTextFromCommand`):

```yaml
- copyTextFrom:
    selector: "id:email_field"

```

Set clipboard content directly with `setClipboard` (`SetClipboardCommand`):

```yaml
- setClipboard: "copied text"

```

Paste clipboard content with `pasteText` (`PasteTextCommand`):

```yaml
- pasteText

```

## Flow Control and Logic Commands

Orchestrate complex test scenarios with control flow structures.

### Flow Execution

Execute nested flows with `runFlow` (`RunFlowCommand`):

```yaml
- 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`):

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

```

Evaluate scripts without return values using `evalScript` (`EvalScriptCommand`):

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

```

### Repetition and Retry

Repeat actions with `repeat` (`RepeatCommand`):

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

```

Retry on failure with `retry` (`RetryCommand`):

```yaml
- 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`):

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

```

Capture static screenshots with `takeScreenshot` (`TakeScreenshotCommand`):

```yaml
- takeScreenshot: "login_screen"

```

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

```yaml
- 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`](https://github.com/mobile-dev-inc/Maestro/blob/main/Commands.kt) alongside their replacements but may be removed in future releases.

## Summary

- Maestro defines **40+ concrete command classes** in [`Commands.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/Commands.kt) that map directly to YAML keys using lower-camelCase naming.
- The [`MaestroCommand.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/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:

```yaml
- 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:

```yaml
- 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`](https://github.com/mobile-dev-inc/Maestro/blob/main/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.