### Environment Variables Override Example (Bash)

Source: https://context7_llms

Provides examples of how to override Maestro environment variables using bash commands for testing across different environments.

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

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

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

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

### Web Flow Example - Basic Navigation

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

This snippet shows a simple Maestro flow for interacting with a web application. It demonstrates launching a URL and performing a tap action on a UI element. This flow is defined in a YAML file.

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

```

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

### Waiting Strategy: Bad vs Good Example

Source: https://context7_llms

Illustrates the difference between unreliable fixed timeouts (`waitForAnimationToEnd`) and the recommended robust `extendedWaitUntil` strategy that waits for actual UI states.

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

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

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

### Launch Application Command

Source: https://context7_llms

Starts a browser session. This is a fundamental command to initiate a test flow.

```yaml
- launchApp
```

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

### Maestro MCP Quick Reference Commands

Source: https://context7_llms

A collection of useful Maestro MCP commands for quick reference. Includes commands for getting full command syntax, querying documentation, inspecting the live UI, and running ad-hoc commands or flow files.

```bash
mcp_maestro_cheat_sheet()
mcp_maestro_query_docs(question: "How do I wait for an element?")
mcp_maestro_query_docs(question: "What selectors are available?")
mcp_maestro_inspect_view_hierarchy(device_id: "<device_id>")
mcp_maestro_run_ad_hoc_command(device_id: "<device_id>", command_yaml: "- tapOn: 'Submit'")
mcp_maestro_run_flow_files(device_id: "<device_id>", flow_files: "maestro/user_settings_open.yaml")

```

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

### Running Maestro Flows via CLI

Source: https://context7_llms

Shows how to execute Maestro tests directly from the command line interface. Examples include running a single flow file, running all flow files in a directory, and 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

```

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

### Android Flow Example - Contacts App

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

This snippet demonstrates a basic Maestro flow for automating contact creation on an Android application. It covers launching the app, interacting with UI elements to input text, and saving the contact. This flow is defined in a YAML file.

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

```

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

### iOS Flow Example - Contacts App

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

This snippet illustrates a Maestro flow for editing contact information on an iOS application. It includes launching the app, selecting a contact, editing a phone number, and saving the changes. This flow is defined in a YAML file.

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

```

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

### Maestro MCP Command Examples for UI Inspection

Source: https://context7_llms

Illustrates the usage of Maestro MCP (Model Context Protocol) tools for inspecting the UI hierarchy and running ad-hoc commands. These commands are crucial for understanding the current state of the application's UI before generating or modifying test cases.

```shell
mcp_maestro_cheat_sheet()
mcp_maestro_inspect_view_hierarchy(device_id: "<device_id>")
```

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

### Selector Strategy: Fallback 2 (Index)

Source: https://context7_llms

When multiple elements share the same text or other properties, the `index` can be used to select a specific one. Indexing starts from 0.

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

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

### Waiting Strategy: Element Appears

Source: https://context7_llms

Always use `extendedWaitUntil` to wait for elements. This example shows waiting for an element to become visible within a specified timeout.

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

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

### Maestro YAML Test File Structure - New Test

Source: https://context7_llms

Example of a basic Maestro YAML file structure for creating a new test case. It includes application identification, test name, URL configuration, and an initial step like launching the app and waiting for an element to be visible.

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

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

### Swipe Gesture Command

Source: https://context7_llms

Performs a drag or swipe gesture on the screen between specified start and end coordinates. Used for interactions like scrolling or swiping through carousels.

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

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

### Flow Composition with Run Flow

Source: https://context7_llms

Demonstrates how to compose flows using the `runFlow` command, allowing for the reuse of existing flow files and passing environment variables.

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

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

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

### Running Maestro Flows via MCP

Source: https://context7_llms

Demonstrates how to execute Maestro flows using the Maestro Command Processor (MCP). It shows commands for running flow files and running ad-hoc flow YAML content, specifying the target device.

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

```

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

### Maestro Selector Syntax

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

Demonstrates the fundamental syntax for Maestro selectors, including text, ID, index, point, dimensions, and state-based criteria.

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

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

### Configure Claude Desktop for Maestro MCP

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

This configuration snippet allows Claude Desktop to connect to Maestro MCP servers. It requires adding a specific JSON object to the Claude configuration file and restarting the application. Ensure the 'maestro' command points to the correct path if not in your system's PATH.

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

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

### Dismissing Onboarding Dialogs with Maestro

Source: https://context7_llms

Handles the dismissal of onboarding or introductory dialogs within a mobile application, specifically for auth flows or first-time app launches. It uses `tapOn` with a `repeat` count to efficiently dismiss multiple dialogs.

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

```

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

### Environment Variables Configuration

Source: https://context7_llms

Shows how to define environment variables within a Maestro flow, including setting default values and overriding them for different deployment environments (local, staging, production).

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

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

### Git Command Reference for Detecting File Changes

Source: https://context7_llms

Provides bash commands to identify modified files in a Git repository. Useful for tracking changes in unstaged, staged, last commit, or between branches. Helps in focusing test generation efforts on affected code.

```bash
git diff --name-only

git diff --staged --name-only

git diff HEAD~1 --name-only

git diff main...HEAD --name-only
```

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

### Basic Authentication Flow Template

Source: https://context7_llms

A YAML template for handling login, signup, or initial app launch with basic authentication. 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
```

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

### Filtering Git Diffs for UI-Related Files

Source: https://context7_llms

Demonstrates bash commands to filter Git diff output for specific file types and directories. This helps in isolating UI-related code changes (e.g., .tsx, .jsx files or specific package directories) for targeted test generation.

```bash
git diff --name-only | grep -E ".(tsx|jsx)$"
git diff --name-only | grep "packages/trader/src"
git diff --name-only | grep "packages/core/src"
```

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

### Maestro Shorthand Text Selector

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

Illustrates the simplified syntax for selecting elements based on their text content using the `text` selector directly.

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

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

### Login Flow with Maestro

Source: https://context7_llms

Automates the mobile application login process. It launches the app, waits for the login button, taps it, inputs credentials, and verifies successful login by waiting for the 'Portfolio' screen. Uses `extendedWaitUntil` for robust waiting.

```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: "Portfolio"
    timeout: 30000

```

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

### Maestro YAML Test File Structure - Extending Existing Test

Source: https://context7_llms

Shows how to extend an existing Maestro test file by running a previous flow and then adding new steps. This is useful for adding new functionalities or assertions to already defined test scenarios.

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

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

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

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

### Sidebar Flow Template

Source: https://context7_llms

A YAML template for interacting with sidebar panels. It assumes no onboarding dismissal is needed and focuses on opening and verifying content within a sidebar.

```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: "dt_sidebar_[item_name]"
- extendedWaitUntil:
    visible: "[Panel header text]"
    timeout: 10000
- assertVisible: "[Expected content]"
```

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

### Maestro Relative Position Selectors

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

Shows how to select UI elements based on their spatial relationship to other elements, such as 'below', 'above', 'leftOf', 'rightOf', and 'contains'.

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

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

### Form Filling with Maestro

Source: https://context7_llms

Demonstrates how to fill out a form in a mobile application. This snippet shows tapping on input fields for 'First Name' and 'Last Name', entering text, and then tapping a 'Save' button. It's a common pattern for user data submission.

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

```

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

### Selector Strategy: Fallback 1 (ID)

Source: https://context7_llms

If text matching is ambiguous or not feasible, use the HTML `id` attribute. It's crucial to use actual `id` attributes and not `data-testid` values.

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

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

### Selector Strategy: Fallback 3 (Repeat)

Source: https://context7_llms

The `repeat` option is useful for scenarios like onboarding dialogs or repeated prompts where the same action needs to be performed multiple times.

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

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

### Tap On Element Command

Source: https://context7_llms

Simulates a click action on a specified element. It can target elements by their text content.

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

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

### Extended Wait Until Command for Visibility

Source: https://context7_llms

Waits for a specific element to become visible on the screen, with a configurable timeout. This is crucial for synchronizing tests with UI updates.

```yaml
- extendedWaitUntil:
    visible: "Log in"
    timeout: 20000
```

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

### Maestro CLI Command Syntax Validation

Source: https://context7_llms

Provides the Maestro CLI command for validating the syntax of a flow YAML file. This is a crucial step before running tests to catch potential errors in the flow definition.

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

```

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

### Extended Flow Template

Source: https://context7_llms

A YAML template for building upon existing flows. It allows running a base flow and then performing additional 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
```

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

### Waiting Strategy: Element Disappears

Source: https://context7_llms

This strategy waits for an element to no longer be visible on the screen, which is useful for confirming the completion of operations like loading or transitions.

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

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

### Input Text Command

Source: https://context7_llms

Types text into the currently focused input field. This is used for filling forms or entering credentials.

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

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

### Selector Strategy: Default (Text)

Source: https://context7_llms

The default strategy for targeting elements is by their visible text content. This is the most straightforward and readable method.

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

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

### Assert Visible Command

Source: https://context7_llms

Verifies that a specific element is present and visible on the screen. Used for confirming expected UI states.

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

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

### Select Specific Element by Index (Maestro)

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

When multiple elements match a selector, use the 'index' parameter to pinpoint a specific occurrence. Indexes are zero-based, so 'index: 2' refers to the third matching element.

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

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

### Assert Not Visible Command

Source: https://context7_llms

Verifies that a specific element is no longer visible on the screen. Useful for confirming that processes have completed or elements have been removed.

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

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

### Slider Interaction with Maestro

Source: https://context7_llms

Illustrates how to interact with a slider element in a mobile application using Maestro. This involves tapping on the slider by its ID and then performing a swipe gesture to adjust its value. The `duration` parameter controls the swipe speed.

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

```

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

### Use Regular Expressions for Assertions (Maestro)

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

Maestro selectors treat text fields as regular expressions. This enables partial matches, pattern matching for dynamic content like OTPs, and proper escaping of special characters.

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

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

### View Selectors API

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

Commands that interact with a view require the view to be specified using a selector. Maestro provides various selectors to precisely target UI elements.

```APIDOC
## View Selectors API

### Description
Commands like `tapOn`, `assertVisible`, and `copyTextFrom` require a view to be specified using a selector. Maestro offers a variety of selectors to target UI elements.

### Method
N/A (describes selector syntax)

### Endpoint
N/A (describes selector syntax)

### Parameters
#### Selector Types
- **text** (string, regex) - Optional - Finds an element with text or accessibility text that matches the regular expression.
- **id** (string) - Optional - Finds an element with an accessibility identifier that matches the given string.
- **index** (integer) - Optional - Selects the element at the specified 0-based index among those matching other criteria.
- **point** (string) - Optional - Selects an element at a relative position (e.g., "50%, 50%") or exact coordinates (e.g., x:50 y:50 in pixels).
- **width** (integer) - Optional - Finds an element with a specific width in pixels.
- **height** (integer) - Optional - Finds an element with a specific height in pixels.
- **tolerance** (integer) - Optional - Tolerance in pixels to apply when comparing width and height.
- **enabled** (boolean) - Optional - Searches for a view with a given "enabled" state.
- **checked** (boolean) - Optional - Searches for a view with a given "checked" state.
- **focused** (boolean) - Optional - Searches for a view with a given "focused" state.
- **selected** (boolean) - Optional - Searches for a view with a given "selected" state.

### Shorthand Selector for Text

To use the `text` selector more concisely:
```
- tapOn: 'Exact Text'
```

### Relative Position Selectors

Maestro allows selecting views based on their position relative to other views.

- **below** (View selector) - Matches a view directly above the specified view.
- **above** (View selector) - Matches a view directly below the specified view.
- **leftOf** (View selector) - Matches a view directly to the right of the specified view.
- **rightOf** (View selector) - Matches a view directly to the left of the specified view.
- **containsChild** (View selector) - Matches a view that has the specified view as a direct child.
- **childOf** (View selector) - Matches a view that is a direct child of the specified view (identified by `id`).
- **containsDescendants** (View selector array) - Matches a view that contains all the specified descendant views.

### Request Example
```json
{
  "selector": {
    "text": "Username",
    "id": "username_input"
  }
}
```

### Response
#### Success Response (200)
N/A (describes selector syntax)

#### Response Example
N/A (describes selector syntax)
```

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

### Select Elements by Traits (Maestro)

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

Select elements based on high-level descriptive aspects like text content, long text, or shape. This method allows for more semantic element targeting.

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

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