### Launch Application Command

Source: https://context7_llms

Starts a new browser session for the application under test. This is typically the first command in any test flow.

```yaml
- launchApp
```

--------------------------------

### Waiting Strategy: Bad vs Good Example

Source: https://context7_llms

Illustrates the unreliability of fixed timeouts (`waitForAnimationToEnd`) compared to the robustness of waiting for specific element visibility (`extendedWaitUntil`).

```yaml
# ❌ BAD - Fixed timeout, unreliable
- tapOn: "Load"
- waitForAnimationToEnd:
    timeout: 5000

# ✅ GOOD - Waits for actual content
- tapOn: "Load"
- extendedWaitUntil:
    visible: "Data"
    timeout: 15000
```

--------------------------------

### Maestro Troubleshooting: Unsure of Command Syntax

Source: https://context7_llms

Guides users on how to get help with Maestro command syntax by calling the `mcp_maestro_cheat_sheet()` function.

```bash
Call `mcp_maestro_cheat_sheet()`
```

--------------------------------

### Maestro MCP: Get Full Command Syntax

Source: https://context7_llms

Details the Maestro MCP command to retrieve a comprehensive list of all available command syntaxes, useful for new users or when needing a quick reference.

```bash
mcp_maestro_cheat_sheet()
```

--------------------------------

### Environment Variable Overrides in Bash

Source: https://context7_llms

Provides examples of how to override Maestro's environment variables directly from the command line using bash, enabling testing across different environments.

```bash
# Local development (default)
maestro test maestro/login.yaml

# Staging
MAESTRO_BASE_URL="https://staging.example.com" maestro test maestro/login.yaml

# Production
MAESTRO_BASE_URL="https://app.example.com" maestro test maestro/login.yaml
```

--------------------------------

### Flow Composition with runFlow

Source: https://context7_llms

Demonstrates how to compose complex flows by reusing existing flows using the `runFlow` command, passing environment variables as needed.

```yaml
appId: web
name: "Save user settings"
url: ${BASE_URL}

env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
---
- runFlow:
    file: settings_open.yaml
    env:
      BASE_URL: ${BASE_URL}
- tapOn:
    text: "First Name"
- inputText: "TestUser"
- tapOn:
    text: "Save"
- extendedWaitUntil:
    visible: "Settings saved"
    timeout: 10000
```

--------------------------------

### Maestro MCP: Query Specific Documentation

Source: https://context7_llms

Shows how to use the MCP to query documentation for specific Maestro features or commands, enabling users to find answers to their questions efficiently.

```bash
mcp_maestro_query_docs(question: "How do I wait for an element?")
mcp_maestro_query_docs(question: "What selectors are available?")
```

--------------------------------

### Maestro MCP: Run Ad-hoc Commands

Source: https://context7_llms

Demonstrates how to execute a single Maestro command or a short flow directly using the MCP, useful for quick testing or debugging specific interactions.

```bash
mcp_maestro_run_flow(device_id: "<device_id>", flow_yaml: "- tapOn: 'Submit'")
```

--------------------------------

### Form Filling with Maestro

Source: https://context7_llms

Demonstrates how to fill out a form by interacting with text fields for first name and last name, and then saving the input. It relies on specific text labels to identify form elements.

```yaml
- tapOn:
    text: "First Name"
- inputText: "John"
- tapOn:
    text: "Last Name"  
- inputText: "Doe"
- tapOn:
    text: "Save"
```

--------------------------------

### Basic Authentication Flow Template

Source: https://context7_llms

A template for handling user login, signup, or initial app launch. It includes launching the app, waiting for the login screen, and inputting credentials.

```yaml
appId: web
name: "Login - Basic authentication"
url: ${BASE_URL}

env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
  USER_EMAIL: ${MAESTRO_USER_EMAIL || "user@example.com"}
  USER_PASSWORD: ${MAESTRO_USER_PASSWORD || "password"}
---
- launchApp
- extendedWaitUntil:
    visible: "Log in"
    timeout: 20000
- tapOn:
    text: "Next"
    repeat: 3
- tapOn:
    text: "Got it"
    repeat: 3
- tapOn:
    text: "Log in"
- tapOn:
    text: "Email"
- inputText: ${USER_EMAIL}
- tapOn:
    text: "Password"
- inputText: ${USER_PASSWORD}
- tapOn:
    text: "Log in"
- extendedWaitUntil:
    visible: "Dashboard"
    timeout: 30000
```

--------------------------------

### Running Maestro Flows via CLI

Source: https://context7_llms

Illustrates the command-line interface (CLI) methods for running Maestro tests. This includes running a single YAML file, all files in a directory, or setting environment variables like the base URL.

```bash
maestro test maestro/login.yaml
maestro test maestro/
MAESTRO_BASE_URL="https://localhost:8443" maestro test maestro/login.yaml
```

--------------------------------

### Maestro Troubleshooting: Dismissing Multiple Dialogs

Source: https://context7_llms

Explains how to handle scenarios requiring the dismissal of multiple dialogs by utilizing the `repeat: N` option within the `tapOn` command.

```bash
Use `repeat: N` on `tapOn`
```

--------------------------------

### Maestro Troubleshooting: Multiple Elements Match

Source: https://context7_llms

Offers a solution for cases where multiple UI elements match a given selector. The recommendation is to use the `index:` property to specify the desired element.

```bash
Add `index: 0` (or 1, 2...)
```

--------------------------------

### Dismissing Onboarding Dialogs with Maestro

Source: https://context7_llms

Provides a method for dismissing multiple onboarding dialogs, specifically designed for auth flows or first-time app launches. It uses `repeat` to tap 'Next' and 'Got it' multiple times.

```yaml
- tapOn:
    text: "Next"
    repeat: 3
- tapOn:
    text: "Got it"
    repeat: 2
```

--------------------------------

### Running Maestro Flows via MCP

Source: https://context7_llms

Shows how to execute Maestro flows using the Maestro Command Processor (MCP). It covers running single flow files or multiple flows from a directory, specifying the device ID.

```bash
mcp_maestro_run_flow_files(device_id: "<device_id>", flow_files: "maestro/login.yaml")
mcp_maestro_run_flow(device_id: "<device_id>", flow_yaml: "- tapOn: 'Submit'")
```

--------------------------------

### Selector Strategy: Repeat (Fallback 3)

Source: https://context7_llms

For sequences of identical elements, like onboarding dismissals or dialogs, use the `repeat` property to interact with multiple instances.

```yaml
- tapOn:
    text: "Got it"
    repeat: 3
```

--------------------------------

### Maestro MCP: Inspect Live UI

Source: https://context7_llms

Explains the MCP command for inspecting the view hierarchy of a live application screen, which is crucial for identifying element selectors and troubleshooting UI issues.

```bash
mcp_maestro_inspect_view_hierarchy(device_id: "<device_id>")
```

--------------------------------

### Maestro MCP: Execute Flow Files

Source: https://context7_llms

Details the MCP command for running one or more Maestro flow files, specifying the target device ID and the path to the flow files.

```bash
mcp_maestro_run_flow_files(device_id: "<device_id>", flow_files: "maestro/settings_open.yaml")
```

--------------------------------

### Waiting Strategy: Element Appears

Source: https://context7_llms

Use `extendedWaitUntil` with the `visible` property to wait for a specific element to become present on the screen. This is more reliable than fixed timeouts.

```yaml
- extendedWaitUntil:
    visible: "Submit Button"
    timeout: 15000
```

--------------------------------

### Login Flow Automation with Maestro

Source: https://context7_llms

Automates the application login process by tapping on elements, inputting credentials, and waiting for the dashboard to become visible. It utilizes specific element IDs for email and password inputs.

```yaml
- launchApp
- extendedWaitUntil:
    visible: "Log in"
    timeout: 20000
- tapOn: "Log in"
- tapOn:
    id: "EmailInput"
- inputText: ${USER_EMAIL}
- tapOn:
    id: "PasswordInput"
- inputText: ${USER_PASSWORD}
- tapOn:
    text: "Log in"
- extendedWaitUntil:
    visible: "Dashboard"
    timeout: 30000
```

--------------------------------

### Maestro Troubleshooting: YAML Syntax Errors

Source: https://context7_llms

Provides the command to validate YAML syntax for Maestro flows, helping to identify and correct formatting errors before running the tests.

```bash
Validate with `mcp_maestro_check_flow_syntax()`
```

--------------------------------

### Web Application Launch Flow in Maestro YAML

Source: https://docs.maestro.dev/

This YAML snippet defines a Maestro flow for launching a web application by its URL. It demonstrates the basic 'launchApp' command.

```yaml
url: https://example.com
---
- launchApp
- tapOn: 

```

--------------------------------

### Maestro Troubleshooting: Flow Fails Silently

Source: https://context7_llms

Provides a debugging tip for flows that fail without clear error messages. It recommends adding `assertVisible` after critical steps to identify where the flow is breaking.

```bash
Add `assertVisible` after critical steps
```

--------------------------------

### Tap On Element Command

Source: https://context7_llms

Simulates a click or tap action on a specified UI element. The element can be identified by its text content.

```yaml
- tapOn: "Log in"
```

--------------------------------

### Environment Variable Configuration

Source: https://context7_llms

Shows how to define and use environment variables within Maestro flows, including setting default values and overriding them for different environments.

```yaml
env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
  USER_EMAIL: ${MAESTRO_USER_EMAIL || "default@example.com"}
```

--------------------------------

### Maestro Troubleshooting: Timeout Waiting for Element

Source: https://context7_llms

Addresses the issue of timeouts when waiting for an element. It suggests increasing the `timeout` value or verifying the accuracy of the element's text selector.

```bash
Increase `timeout` or check element text
```

--------------------------------

### Selector Strategy: Text

Source: https://context7_llms

The default and preferred method for selecting elements is by their visible text content. This is straightforward and readable.

```yaml
- tapOn:
    text: "Submit"
```

--------------------------------

### Run Flow Command

Source: https://context7_llms

Reuses another existing Maestro flow file within the current flow. This promotes modularity and reduces code duplication.

```yaml
- runFlow: file: other.yaml
```

--------------------------------

### Selector Strategy: Index (Fallback 2)

Source: https://context7_llms

When multiple elements share the same text or identifier, use the `index` property to specify which instance to target (0-based).

```yaml
- tapOn:
    text: "Next"
    index: 0
```

--------------------------------

### Assert Element Visibility Command

Source: https://context7_llms

Verifies that a specific UI element is currently visible on the screen. This is crucial for confirming UI state changes.

```yaml
- assertVisible: "Dashboard"
```

--------------------------------

### Maestro Troubleshooting: Element Not Found

Source: https://context7_llms

Provides a solution for when an element is not found by its text selector. It suggests using `mcp_maestro_inspect_view_hierarchy()` to find the correct ID or selector.

```bash
Use `mcp_maestro_inspect_view_hierarchy()` or use `id:` selector
```

--------------------------------

### Configure Claude Desktop for Maestro MCP

Source: https://docs.maestro.dev/getting-started/maestro-mcp

This JSON configuration enables Claude Desktop to use Maestro as an MCP server. Ensure 'maestro' command points to your Maestro CLI executable if it's not in your system's PATH. Restart Claude after applying this configuration.

```json
{
  "mcpServers": {
    "maestro": {
      "command": "maestro",
      "args": [
        "mcp"
      ]
    }
  }
}
```

--------------------------------

### Waiting Strategy: Element Disappears

Source: https://context7_llms

Use `extendedWaitUntil` with the `notVisible` property to wait for an element to be removed from the screen, such as a loading indicator.

```yaml
- extendedWaitUntil:
    notVisible: "Loading..."
    timeout: 10000
```

--------------------------------

### Maestro CLI Shorthand Text Selector

Source: https://docs.maestro.dev/api-reference/selectors

Demonstrates the shorthand syntax for selecting elements solely based on their text content in Maestro CLI. This simplifies common interactions.

```yaml
- tapOn: 'Text' # or any other command that works with selectors
```

--------------------------------

### Assert Element Not Visible Command

Source: https://context7_llms

Verifies that a specific UI element is not currently visible on the screen. Useful for ensuring elements have been removed or hidden.

```yaml
- assertNotVisible: "Loading"
```

--------------------------------

### Selectors - Commands and Their Options

Source: https://docs.maestro.dev/api-reference/selectors

Details the available selectors for targeting UI elements in Maestro, including text, ID, index, and physical attributes.

```APIDOC
## Commands with Selectors

Commands that interact with a view (e.g. `tapOn`, `assertVisible`, `copyTextFrom`) require the view to be specified using a `_selector_`. There are many different selectors available:

```
- tapOn: # or any other command that works with selectors
    text: 'Text' # (optional) Finds element with text or accessibility text that matches the regular expression
    id: 'the_id' # (optional) Finds element with accessibility identifier that matches the regular expression
    index: 0 # (optional) 0-based index of the view to select among those that match all other criteria
    point: 50%, 50% # (optional) Relative position on screen. "50%, 50%" is the middle of screen
    point: 50, 75 # (optional) Exact coordinates on screen. x:50 y:50, in pixels
    width: 100 # (optional) Finds element of a given width
    height: 100 # (optional) Finds element of a given height
    tolerance: 10 # (optional) Tolerance to apply when comparing width and height
    enabled: true # (optional) Searches for view with a given "enabled" state
    checked: true # (optional) Searches for view with a given "checked" state
    focused: true # (optional) Searches for view with a given "focused" state
    selected: true # (optional) Searches for view with a given "selected" state
```
```

--------------------------------

### Maestro Flow Syntax Validation Command

Source: https://context7_llms

Demonstrates the Maestro CLI command for validating the syntax of a flow YAML file before execution. This helps catch errors early in the development process.

```bash
mcp_maestro_check_flow_syntax(flow_yaml: "<your_yaml_content>")
```

--------------------------------

### Input Text Command

Source: https://context7_llms

Enters text into the currently focused input field. This is useful for populating forms or login fields.

```yaml
- inputText: "user@email.com"
```

--------------------------------

### Shorthand Selector for Text

Source: https://docs.maestro.dev/api-reference/selectors

Provides a simplified syntax for using the `text` selector when interacting with UI elements.

```APIDOC
### Shorthand selector for text

If you want to use the `text` selector, you can use the following shorthand:

```
- tapOn: 'Text' # or any other command that works with selectors
```
```

--------------------------------

### Selector Strategy: ID (Fallback 1)

Source: https://context7_llms

If text selection is ambiguous or unavailable, use the HTML `id` attribute. Ensure only valid HTML `id`s are used, not `data-testid`.

```yaml
- tapOn:
    id: "submit-button"
```

--------------------------------

### Slider Interaction with Maestro

Source: https://context7_llms

Illustrates how to interact with a slider element using Maestro. It involves tapping on the slider by its ID and then performing a swipe gesture to adjust its value.

```yaml
- tapOn:
    id: "volume_slider"
- swipe:
    start: 40%,50%
    end: 80%,50%
    duration: 800
```

--------------------------------

### Extended Flow Template

Source: https://context7_llms

A template for building upon existing flows, allowing for the addition of new actions and verifications. It utilizes `runFlow` to incorporate a base flow.

```yaml
appId: web
name: "[Feature] - [Extended action]"
url: ${BASE_URL}

env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
---
- runFlow:
    file: [base_flow].yaml
    env:
      BASE_URL: ${BASE_URL}
- tapOn:
    text: "[New action]"
- extendedWaitUntil:
    visible: "[Expected result]"
    timeout: 10000
```

--------------------------------

### Sidebar Flow Template

Source: https://context7_llms

A template for interacting with sidebar panels in a web application. It navigates to a sidebar item and waits for panel content to appear.

```yaml
appId: web
name: "[Panel name] - Open panel"
url: ${BASE_URL}

env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
---
- launchApp
- extendedWaitUntil:
    visible: "[Sidebar item text]"
    timeout: 20000
- tapOn:
    id: "[sidebar_item_id]"
- extendedWaitUntil:
    visible: "[Panel header text]"
    timeout: 10000
- assertVisible: "[Expected content]"
```

--------------------------------

### Maestro CLI Relative Position Selectors

Source: https://docs.maestro.dev/api-reference/selectors

Illustrates how to select UI elements based on their spatial relationship to other elements in Maestro CLI. This includes positioning relative to views above, below, left, or right, as well as selecting children and descendants.

```yaml
- tapOn: # or any other command that works with selectors
    below: View above that has this text # matches a view *above* that has the given text
    above: id: view_below_id # matches a view *below* that has the given id
    leftOf: View to the right has this text
    rightOf: View to the left has this text
    containsChild: Text in a child view # matches a view that has a *direct* child view with the given text
    childOf:
      id: buy-now # matches a view that is a child of a view with id "buy-now"
    containsDescendants: # matches a view that has all the descendant views given below
      - id: title_id
        text: A descendant view has id "title_id" and this text
      - Another descendant view has this text
```

--------------------------------

### Select Specific Element Among Similar Ones

Source: https://docs.maestro.dev/api-reference/selectors

When multiple elements match a selector (e.g., multiple buttons with the text 'Hello'), the 'index' parameter can specify which occurrence to select. Indexes are zero-based, so 'index: 2' selects the 3rd matching element. This aids in precise element targeting but should be used judiciously for readability.

```yaml
- tapOn: text: Hello
  index: 2
```

--------------------------------

### Maestro CLI Basic Selectors

Source: https://docs.maestro.dev/api-reference/selectors

Defines the fundamental selectors in Maestro CLI for identifying UI elements. These include text, ID, index, point (position), dimensions (width, height), and state attributes (enabled, checked, focused, selected).

```yaml
- tapOn: # or any other command that works with selectors
    text: 'Text' # (optional) Finds element with text or accessibility text that matches the regular expression
    id: 'the_id' # (optional) Finds element with accessibility identifier that matches the regular expression
    index: 0 # (optional) 0-based index of the view to select among those that match all other criteria
    point: 50%, 50% # (optional) Relative position on screen. "50%, 50%" is the middle of screen
    point: 50, 75 # (optional) Exact coordinates on screen. x:50 y:50, in pixels
    width: 100 # (optional) Finds element of a given width
    height: 100 # (optional) Finds element of a given height
    tolerance: 10 # (optional) Tolerance to apply when comparing width and height
    enabled: true # (optional) Searches for view with a given "enabled" state
    checked: true # (optional) Searches for view with a given "checked" state
    focused: true # (optional) Searches for view with a given "focused" state
    selected: true # (optional) Searches for view with a given "selected" state
```

--------------------------------

### Swipe Gesture Command

Source: https://context7_llms

Performs a drag or swipe gesture between two points on the screen. Useful for scrolling or triggering swipe actions.

```yaml
- swipe: start: 40%,50% end: 80%,50%
```

--------------------------------

### Using Regular Expressions for Assertions

Source: https://docs.maestro.dev/api-reference/selectors

Maestro uses regular expressions for text and ID fields. This allows for flexible matching, such as asserting visibility of elements containing specific substrings (using wildcards like '.*'), matching patterns (like a 6-digit number), or correctly escaping special regex characters.

```yaml
- assertVisible: '.*brown fox.*'
- assertVisible: '\[0-9\]{6}'
- assertVisible: 'Movies \[NEW\]'
```

--------------------------------

### Select Elements by Traits

Source: https://docs.maestro.dev/api-reference/selectors

Elements can be selected based on high-level descriptive traits like having text, being long-text (over 200 characters), or being square (width and height differ by less than 3%). This is useful for identifying elements with specific visual or content characteristics.

```yaml
- tapOn: traits: text
- tapOn: traits: long-text
- tapOn: traits: square
```

--------------------------------

### Android Contact Creation Flow in Maestro YAML

Source: https://docs.maestro.dev/

This YAML snippet defines a Maestro flow for creating a new contact on an Android application. It includes steps to launch the app, tap specific elements, input text for first and last names, and save the contact.

```yaml
# flow_contacts_android.yaml
appId: com.android.contacts
---
- launchApp
- tapOn: "Create new contact"
- tapOn: "First Name"
- inputText: "John"
- tapOn: "Last Name"
- inputText: "Snow"
- tapOn: "Save"

```

--------------------------------

### Relative Position Selectors

Source: https://docs.maestro.dev/api-reference/selectors

Enables selecting UI elements based on their position relative to other elements on the screen, such as 'below', 'leftOf', 'containsChild', etc.

```APIDOC
### Relative position selectors

Apart from the selectors mentioned above, Maestro is also able to select views using their relative position (i.e. "below another view", or "contains child"):

```
- tapOn: # or any other command that works with selectors
    below: View above that has this text # matches a view *above* that has the given text
    above: id: view_below_id # matches a view *below* that has the given id
    leftOf: View to the right has this text
    rightOf: View to the left has this text
    containsChild: Text in a child view # matches a view that has a *direct* child view with the given text
    childOf: # matches a view that is a child of a view with id "buy-now"
      id: buy-now
    containsDescendants: # matches a view that has all the descendant views given below
      - id: title_id
        text: A descendant view has id "title_id" and this text
      - Another descendant view has this text
```
```

--------------------------------

### iOS Contact Editing Flow in Maestro YAML

Source: https://docs.maestro.dev/

This YAML snippet defines a Maestro flow for editing a contact on an iOS application. It includes launching the app, selecting a contact, editing the phone number, and saving the changes.

```yaml
# flow_contacts_ios.yaml
appId: com.apple.MobileAddressBook
---
- launchApp
- tapOn: "John Appleseed"
- tapOn: "Edit"
- tapOn: "Add phone"
- inputText: "123123"
- tapOn: "Done"

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.