### Maestro Test File Creation Example (YAML)

Source: https://context7_llms

An example of a new Maestro test file in YAML format. It includes basic configurations like `appId`, `name`, `url`, and an initial `launchApp` command with an `extendedWaitUntil` condition.

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

env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
---
- launchApp
- extendedWaitUntil:
    visible: "[UI element]"
    timeout: 20000
```

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

### Launch Application

Source: https://context7_llms

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

```yaml
- launchApp
```

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

### Waiting Strategy: Bad vs Good Example

Source: https://context7_llms

Illustrates the difference between unreliable fixed timeouts and the recommended `extendedWaitUntil` for robustness. Always wait for actual content visibility.

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

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

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

### Maestro Test File Extension Example (YAML)

Source: https://context7_llms

An example of extending an existing Maestro test file. It uses the `runFlow` command to incorporate an existing test and then adds new steps like tapping on a new UI element.

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

env:
  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
---
- runFlow:
    file: [existing_test].yaml
    env:
      BASE_URL: ${BASE_URL}
- tapOn:
    text: "[New UI element]"
```

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

### Form Filling Automation with Maestro

Source: https://context7_llms

Demonstrates how to fill out a form by tapping on input fields and entering text. This example fills 'First Name' and 'Last Name' before tapping 'Save'.

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

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

### Running Maestro Flows via MCP

Source: https://context7_llms

Provides examples of how to execute Maestro flows using the `mcp_maestro_run_flow` and `mcp_maestro_run_flow_files` commands, specifying the device ID and flow file or YAML content.

```python
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'")
```

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

### MCP Tool: Cheat Sheet Command

Source: https://context7_llms

A simple command to invoke the Maestro MCP cheat sheet, providing quick access to command syntax and examples for Maestro YAML.

```bash
mcp_maestro_cheat_sheet()
```

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

### Configure Claude Desktop for Maestro MCP

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

This configuration snippet enables Maestro MCP integration within the Claude Desktop application. It specifies the command to run Maestro's MCP server and its arguments. Ensure the 'maestro' command points to your installed Maestro CLI if it's not in your system's PATH.

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

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

### Slider Interaction with Maestro

Source: https://context7_llms

Shows how to interact with a slider element by tapping on it and then performing a swipe gesture. The swipe is defined by start and end coordinates and duration.

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

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

### Environment Variable Overrides via CLI

Source: https://context7_llms

Provides examples of how to override default environment variables when running Maestro tests from the command line, allowing for testing across different environments (local, staging, production).

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

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

### MCP Quick Reference: Execute Flow Files

Source: https://context7_llms

Demonstrates how to execute entire Maestro flow files using the `mcp_maestro_run_flow_files` command, requiring the device ID and the path to the flow files.

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

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

### MCP Quick Reference: Query Specific Documentation

Source: https://context7_llms

Demonstrates how to query specific documentation within Maestro MCP using `mcp_maestro_query_docs` with a natural language question about commands or selectors.

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

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

### Maestro CLI: Basic Selectors for UI Elements

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

Demonstrates common selectors used in Maestro CLI commands like `tapOn`. These include text, ID, index, and point coordinates for precise element identification. It also shows how to filter by size and state like enabled, checked, focused, and selected.

```yaml
- tapOn:
    text: 'Text'
    id: 'the_id'
    index: 0
    point: 50%, 50%
    width: 100
    height: 100
    tolerance: 10
    enabled: true
    checked: true
    focused: true
    selected: true
```

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

### MCP Quick Reference: Run Ad-hoc Commands

Source: https://context7_llms

Shows how to run ad-hoc Maestro commands directly through MCP using `mcp_maestro_run_flow`, specifying the device ID and the flow YAML content.

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

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

### Running Maestro Flows via CLI

Source: https://context7_llms

Illustrates how to run Maestro tests directly from the command line, targeting specific YAML files, directories, or setting environment variables like `MAESTRO_BASE_URL`.

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

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

### Dismissing Onboarding Dialogs with Maestro

Source: https://context7_llms

Automates the process of dismissing multiple onboarding dialogs using the `repeat` option with `tapOn`. This is intended for auth flows or first-time app launches.

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

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

### Maestro Troubleshooting: Unsure of Command Syntax

Source: https://context7_llms

Suggests using the `mcp_maestro_cheat_sheet()` command when unsure about Maestro command syntax, providing quick access to command documentation.

```markdown
| Unsure of command syntax | Call `mcp_maestro_cheat_sheet()` |
```

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

### Web Navigation Flow Automation (Maestro YAML)

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

This snippet shows a basic Maestro flow for interacting with a web application. It defines steps to launch a web application at a specified URL and perform a tap action. This requires Maestro and a compatible browser environment.

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

```

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

### Selector Strategy: Use Repeat (Fallback 3)

Source: https://context7_llms

For sequences of identical elements, such as onboarding dialogs or tooltips, use the `repeat` option to perform an action on multiple instances.

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

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

### Maestro Troubleshooting: Dismiss Multiple Dialogs

Source: https://context7_llms

Explains how to handle dismissing multiple dialogs in Maestro by utilizing the `repeat: N` option on `tapOn` commands for efficiency.

```markdown
| Need to dismiss multiple dialogs | Use `repeat: N` on `tapOn` |
```

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

### Selector Strategy: Use Index (Fallback 2)

Source: https://context7_llms

If multiple elements match a selector (e.g., text), you can specify which one to interact with using its zero-based `index`.

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

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

### Basic Authentication Flow Template

Source: https://context7_llms

A reusable template for handling login, signup, or initial app launch with basic authentication. It includes launching the app, waiting for login elements, 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
```

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

### Flow Composition using runFlow

Source: https://context7_llms

Demonstrates how to compose larger flows by reusing smaller, modular flows using the `runFlow` command. This includes passing environment variables to the sub-flow.

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

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

### Git Command Reference for Analyzing Changes

Source: https://context7_llms

Provides essential Git commands to identify modified files, including unstaged, staged, and historical changes. Useful for pinpointing files affected by recent development.

```bash
# Recent changes (unstaged)
git diff --name-only

# Staged changes
git diff --staged --name-only

# Changes in last commit
git diff HEAD~1 --name-only

# Changes in a feature branch vs main
git diff main...HEAD --name-only
```

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

### API Reference - Selectors

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

Details on how to use selectors to interact with UI elements in Maestro, including common commands and available selector properties.

```APIDOC
## Selectors

Commands that interact with a view (e.g `tapOn`, `assertVisible`, `copyTextFrom`) require the view to be specified using 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
```

### 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
```

### 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
```

### Element Traits


```

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

### Maestro Troubleshooting: Multiple Elements Match

Source: https://context7_llms

Offers a solution for when multiple UI elements match a selector in Maestro, recommending the use of the `index:` property to specify the desired element.

```markdown
| Multiple elements match | Add `index: 0` (or 1, 2...) |
```

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

### Waiting Strategy: Element Appears

Source: https://context7_llms

Waits for a specified element to become visible on the page within a given timeout. This is the recommended way to handle dynamic content loading.

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

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

### Login Flow Automation with Maestro

Source: https://context7_llms

Automates the login process by launching the app, tapping login, entering email and password, and waiting for the dashboard to be visible. Uses `extendedWaitUntil` for robust waiting and `inputText` for credentials.

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

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

### Environment Variable Definition

Source: https://context7_llms

Shows how to define environment variables within a Maestro YAML file, including setting default values and using placeholders for dynamic values.

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

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

### Selector Strategy: Use Text

Source: https://context7_llms

The default and preferred method for selecting elements is by their visible text content. This is straightforward for buttons, links, and labels.

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

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

### Maestro Troubleshooting: YAML Syntax Errors

Source: https://context7_llms

Recommends validating YAML syntax for Maestro flows using the `mcp_maestro_check_flow_syntax()` command to catch errors before execution.

```markdown
| YAML syntax errors | Validate with `mcp_maestro_check_flow_syntax()` |
```

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

### Maestro Assertions with Regular Expressions

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

Illustrates using regular expressions within Maestro's assertion commands (like assertVisible) to match patterns in element text. This includes handling partial matches, defining character patterns, and escaping special regex characters.

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

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

### Select Elements by Traits in Maestro

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

Demonstrates how to select UI elements based on their descriptive traits like text content, character count, or shape. These selectors abstract away the need for specific element IDs or exact text matches.

```YAML
- tapOn: #text or any other command that works with selectors
    traits: text # An element that contains some text
- tapOn:
    traits: long-text # An element that contains at least 200 characters of text
- tapOn:
    traits: square # A square element (or close - width and height differ by less than 3%)
```

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

### Run Another Flow

Source: https://context7_llms

Reuses the steps defined in another Maestro YAML flow file. This promotes modularity and reduces redundancy in test definitions.

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

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

### MCP Tool: Inspect View Hierarchy

Source: https://context7_llms

Allows inspection of the current UI element tree on a device. This is crucial for accurately identifying UI elements and their properties before generating tests.

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

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

### Sidebar Interaction Flow Template

Source: https://context7_llms

A template for interacting with sidebar panels in a web application. It assumes no onboarding dismissal is needed and focuses on selecting a sidebar item and verifying panel content.

```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]"
```

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

### Extended Flow Template for Building on Existing Flows

Source: https://context7_llms

A template designed for extending existing test flows. It utilizes `runFlow` to include a base flow and then adds new actions and assertions.

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

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

### Tap on Element by Text

Source: https://context7_llms

Simulates a click action on an element identified by its visible text. This is a common way to interact with buttons and links.

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

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

### Maestro CLI Syntax Validation

Source: https://context7_llms

Demonstrates how to validate the syntax of a Maestro flow YAML file using the `mcp_maestro_check_flow_syntax` command.

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

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

### Maestro Troubleshooting: Flow Fails Silently

Source: https://context7_llms

Provides a solution for flows that fail silently in Maestro by recommending the addition of `assertVisible` after critical steps to gain visibility into failures.

```markdown
| Flow fails silently | Add `assertVisible` after critical steps |
```

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

### Maestro CLI: Shorthand Text Selector

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

Provides a simplified syntax for using the 'text' selector in Maestro CLI commands. This shorthand allows for quicker specification of elements based on their visible text content.

```yaml
- tapOn: 'Text'
```

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

### iOS Contacts Flow Automation (Maestro YAML)

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

This snippet demonstrates a Maestro flow for automating contact management on an iOS application. It uses YAML to define steps such as launching the app, selecting a contact, editing, adding a phone number, and inputting text. This requires Maestro and a compatible iOS environment.

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

```

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

### Maestro CLI: Relative Position Selectors

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

Explains how to use relative positioning to select UI elements in Maestro CLI. This includes selecting elements based on their position relative to other elements, such as 'below', 'above', 'leftOf', 'rightOf', 'containsChild', 'childOf', and 'containsDescendants'.

```yaml
- tapOn:
    below: View above that has this text
    above:
      id: view_below_id
    leftOf: View to the right has this text
    rightOf: View to the left has this text
    containsChild:
      text: Text in a child view
    childOf:
      id: buy-now
    containsDescendants:
      - id: title_id
        text: A descendant view has id "title_id" and this text
      - text: Another descendant view has this text
```

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

### Select Specific Element by Index in Maestro

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

Shows how to select a particular element when multiple elements match the same selector. The 'index' parameter allows targeting a specific occurrence (0-based) of a matching element, useful for disambiguation.

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

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

### Maestro Troubleshooting: Timeout Waiting for Element

Source: https://context7_llms

Addresses timeout issues in Maestro when waiting for an element, suggesting to increase the `timeout` value or verify the accuracy of the element's text.

```markdown
| Timeout waiting for element | Increase `timeout` or check element text |
```

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

### Selector Strategy: Use ID (Fallback 1)

Source: https://context7_llms

When text is not unique or available, use the element's HTML `id` attribute. Ensure you are using the actual `id` and not attributes like `data-testid`.

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

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

### Maestro Troubleshooting: Element Not Found

Source: https://context7_llms

Provides a solution for 'Element not found by text' errors in Maestro, suggesting the use of `mcp_maestro_inspect_view_hierarchy()` or the `id:` selector as alternatives.

```markdown
| Element not found by text | Use `mcp_maestro_inspect_view_hierarchy()` or use `id:` selector |
```

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

### Android Contacts Flow Automation (Maestro YAML)

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

This snippet defines a Maestro flow for automating the creation of a new contact on an Android application. It uses YAML syntax to specify a sequence of actions like launching the app, tapping buttons, and inputting text. No external dependencies are required beyond Maestro itself.

```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"

```

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

### Filtering Git Diffs for UI Files

Source: https://context7_llms

Filters the output of `git diff --name-only` to include only files with `.tsx` or `.jsx` extensions, helping to isolate UI-related code changes.

```bash
git diff --name-only | grep -E "\.(tsx|jsx)$"
```

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

### Perform Swipe Gesture

Source: https://context7_llms

Simulates a swipe or drag gesture between two points on the screen. Useful for interacting with scrollable areas or custom UI elements.

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

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

### Waiting Strategy: Element Disappears

Source: https://context7_llms

Waits for a specified element to no longer be visible on the page within a given timeout. Useful for confirming that loading indicators or temporary messages have vanished.

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

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

### Input Text into Focused Field

Source: https://context7_llms

Types a given string into the currently focused input field. This is used for form submissions and user input.

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

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

### Wait for Element Visibility

Source: https://context7_llms

Pauses test execution until a specified element becomes visible on the page or a timeout occurs. Use this to ensure elements are ready before interaction.

```yaml
- extendedWaitUntil:
    visible: "Dashboard"
    timeout: 30000
```

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

### Assert Element Visibility

Source: https://context7_llms

Verifies that a specific element is currently visible on the page. This is used for asserting expected UI states.

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

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

### Assert Element Not Visible

Source: https://context7_llms

Verifies that a specific element is not visible on the page. This is useful for asserting that elements have been removed or hidden.

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

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