### Web Flow Example (YAML) Source: https://docs.maestro.dev/ This snippet provides an example of a web UI test flow using Maestro's YAML syntax. It demonstrates launching a web application via URL and interacting with elements on the page. This is applicable for automating tests in desktop web browsers. ```yaml url: https://example.com --- - launchApp - tapOn: ``` -------------------------------- ### iOS Flow Example (YAML) Source: https://docs.maestro.dev/ This snippet illustrates a UI test flow for an iOS application using Maestro's declarative YAML syntax. It showcases launching the app, interacting with elements, inputting text, and saving changes, providing a clear example for automating iOS user interactions. ```yaml appId: com.apple.MobileAddressBook --- - launchApp - tapOn: "John Appleseed" - tapOn: "Edit" - tapOn: "Add phone" - inputText: "123123" - tapOn: "Done" ``` -------------------------------- ### Waiting Strategy: Good vs. Bad Example Source: https://context7_llms Illustrates the recommended `extendedWaitUntil` for waiting on element visibility versus the unreliable method of using fixed `waitForAnimationToEnd` timeouts. ```yaml # ❌ BAD - Fixed timeout, unreliable - tapOn: "Load" - waitForAnimationToEnd: timeout: 5000 # ✅ GOOD - Waits for actual content - tapOn: "Load" - extendedWaitUntil: visible: "Data" timeout: 15000 ``` -------------------------------- ### Slider Interaction Example (YAML) Source: https://context7_llms This example demonstrates how to interact with a slider element using Maestro. It involves tapping on the slider and then performing a swipe gesture to adjust its value. ```yaml - tapOn: id: "volume_slider" - swipe: start: 40%,50% end: 80%,50% duration: 800 ``` -------------------------------- ### Launch Application with Maestro Source: https://context7_llms Starts a new browser session. This is typically the first command in a Maestro flow to initialize the testing environment. ```yaml - launchApp ``` -------------------------------- ### Troubleshooting: Get Command Syntax Help (Python) Source: https://context7_llms This Python command provides a cheat sheet for all available Maestro MCP commands, useful for recalling syntax or discovering new functionalities. ```python mcp_maestro_cheat_sheet() ``` -------------------------------- ### Login Flow Example (YAML) Source: https://context7_llms This snippet demonstrates a typical login flow using Maestro's YAML syntax. It includes launching the app, waiting for the login button, inputting credentials, and verifying successful login. ```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 ``` -------------------------------- ### Flow Composition with RunFlow Source: https://context7_llms Demonstrates how to reuse existing flows using the `runFlow` command. This example shows saving user settings by first running a `settings_open.yaml` flow, then performing further actions. ```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 ``` -------------------------------- ### Dismiss Onboarding Dialogs Example (YAML) Source: https://context7_llms This snippet shows how to dismiss onboarding dialogs or modals, specifically intended for auth flows or first-time app launches. It uses the `repeat` keyword to tap 'Next' or 'Got it' multiple times. ```yaml - tapOn: text: "Next" repeat: 3 - tapOn: text: "Got it" repeat: 2 ``` -------------------------------- ### Form Filling Example (YAML) Source: https://context7_llms This YAML snippet illustrates how to fill out a form using Maestro. It covers tapping on input fields, entering text, and finally tapping a save button. ```yaml - tapOn: text: "First Name" - inputText: "John" - tapOn: text: "Last Name" - inputText: "Doe" - tapOn: text: "Save" ``` -------------------------------- ### Android Flow Example (YAML) Source: https://docs.maestro.dev/ This snippet demonstrates a basic UI test flow for an Android application using Maestro's YAML syntax. It covers launching the app, interacting with UI elements like buttons and input fields, and saving data. This is useful for automating common user journeys on Android. ```yaml appId: com.android.contacts --- - launchApp - tapOn: "Create new contact" - tapOn: "First Name" - inputText: "John" - tapOn: "Last Name" - inputText: "Snow" - tapOn: "Save" ``` -------------------------------- ### Run Maestro Tests via CLI (Bash) Source: https://context7_llms This section provides examples of how to run Maestro tests directly from the command line, including specifying individual files, directories, 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 ``` -------------------------------- ### Configure Claude Desktop for Maestro MCP Source: https://docs.maestro.dev/getting-started/maestro-mcp This configuration allows Claude Desktop to use Maestro as an MCP server, enabling it to connect to apps and data. Ensure the 'maestro' command points to your Maestro CLI installation. ```json { "mcpServers": { "maestro": { "command": "maestro", "args": [ "mcp" ] } } } ``` -------------------------------- ### Overriding Environment Variables via Bash Source: https://context7_llms Provides examples of how to override Maestro environment variables directly from the command line using bash, allowing for flexible testing configurations across different deployment 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 ``` -------------------------------- ### Selector Strategy: Fallback to Index for Multiple Matches Source: https://context7_llms If multiple elements match a given selector (e.g., text), the `index` property can specify which occurrence to target, starting from 0 for the first match. ```yaml - tapOn: text: "Next" index: 0 ``` -------------------------------- ### Use Regular Expressions for Partial Text Matching Source: https://docs.maestro.dev/api-reference/selectors Maestro's element selectors treat text fields as regular expressions. This allows for flexible matching beyond exact string comparison. To match a substring within a larger text element, use wildcards like '.*' at the beginning and end of your pattern. For example, '.*brown fox.*' will match any element containing the phrase 'brown fox'. ```yaml - assertVisible: '.*brown fox.*' ``` -------------------------------- ### Query Maestro Documentation Command (Python) Source: https://context7_llms Use this Python command to query specific documentation topics related to Maestro, such as waiting for elements or available selectors. ```python mcp_maestro_query_docs(question: "How do I wait for an element?") mcp_maestro_query_docs(question: "What selectors are available?") ``` -------------------------------- ### Basic Authentication Flow Template Source: https://context7_llms A template for handling user login, signup, or initial application launch that requires authentication. It includes launching the app, waiting for login elements, inputting credentials, and asserting successful login. ```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 ``` -------------------------------- ### Run Maestro Flow via MCP Command (Python) Source: https://context7_llms These Python function calls show how to execute Maestro flows either by specifying individual flow files or by providing the YAML content directly, along with the target device ID. ```python mcp_maestro_run_flow_files(device_id: "", flow_files: "maestro/login.yaml") mcp_maestro_run_flow(device_id: "", flow_yaml: "- tapOn: 'Submit'" ) ``` -------------------------------- ### Selector Strategy: Repeat for Onboarding/Dialogs Source: https://context7_llms The `repeat` property is useful for scenarios where the same action needs to be performed multiple times in succession, such as dismissing multiple introductory dialogs or onboarding screens. ```yaml - tapOn: text: "Got it" repeat: 3 ``` -------------------------------- ### Run Maestro MCP Commands (Shell) Source: https://context7_llms These commands interact with Maestro's Model Context Protocol (MCP) to perform various testing-related actions on a device. They are essential for inspecting UI, running flows, and gathering information before test generation. ```shell mcp_maestro_cheat_sheet() ``` ```shell mcp_maestro_run_flow ``` ```shell mcp_maestro_run_flow_files ``` ```shell mcp_maestro_inspect_view_hierarchy(device_id: "") ``` ```shell mcp_maestro_take_screenshot ``` ```shell mcp_maestro_tap_on ``` ```shell mcp_maestro_input_text ``` ```shell mcp_maestro_query_docs ``` -------------------------------- ### Create New Maestro Test File (YAML) Source: https://context7_llms This YAML structure defines a new Maestro test case. It includes the application ID, test name, base URL configuration, and an initial step to launch the app and wait until a specific UI element is visible. This serves as a template for new test scenarios. ```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 ``` -------------------------------- ### Extend Existing Maestro Test File (YAML) Source: https://context7_llms This YAML structure demonstrates how to extend an existing Maestro test file. It uses the `runFlow` command to execute a pre-defined test file and then adds new steps, such as tapping on a new UI element. This is useful for adding new actions to existing 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]" ``` -------------------------------- ### Extended Flow Template for Building on Existing Flows Source: https://context7_llms A template designed for extending existing Maestro flows. It demonstrates how to incorporate a base flow, perform new actions, and wait for the expected results, facilitating incremental test development. ```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 ``` -------------------------------- ### Select Elements by Traits Source: https://docs.maestro.dev/api-reference/selectors This snippet demonstrates how to select UI elements based on their intrinsic properties or 'traits'. This method allows for high-level descriptions, such as selecting elements that contain text, are visually long, or have a square aspect ratio. It's useful for targeting elements when specific text or IDs might be too brittle. ```yaml - tapOn: traits: text - tapOn: traits: long-text - tapOn: traits: square ``` -------------------------------- ### Environment Variable Configuration Source: https://context7_llms Shows how to define and use environment variables within Maestro flows, including setting a default `BASE_URL` and overriding it for different environments like staging or production. ```yaml env: BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"} USER_EMAIL: ${MAESTRO_USER_EMAIL || "default@example.com"} ``` -------------------------------- ### Use Regular Expressions for Pattern Matching Source: https://docs.maestro.dev/api-reference/selectors Regular expressions are powerful for validating formats, such as randomly generated codes. You can assert that an element matches a specific pattern, like a 6-digit number, without needing to know the exact content. The pattern '[0-9]{6}' ensures the element contains exactly six digits. ```yaml - assertVisible: '[0-9]{6}' ``` -------------------------------- ### Troubleshooting: Element Not Found Command (Python) Source: https://context7_llms If an element is not found by its text, this Python command can be used to inspect the view hierarchy and identify the correct selector (e.g., `id:`). ```python mcp_maestro_inspect_view_hierarchy(device_id: "") ``` -------------------------------- ### Select Specific Element by Index Source: https://docs.maestro.dev/api-reference/selectors When multiple elements match the same selector (e.g., several buttons with the text 'Hello'), the 'index' parameter allows you to specify which occurrence to interact with. Indexes are zero-based, so 'index: 2' targets the third matching element. This is useful for disambiguating identical-looking elements but should be used judiciously to maintain test readability. ```yaml - tapOn: text: Hello index: 2 ``` -------------------------------- ### Detect Code Changes (Bash) Source: https://context7_llms These Bash commands utilize Git to identify modified files within a repository. They are crucial for pinpointing the scope of changes that require new or updated test cases, helping to adhere to the principle of testing only what has changed. ```bash # Recent changes (unstaged) git diff --name-only ``` ```bash # Staged changes git diff --staged --name-only ``` ```bash # Changes in last commit git diff HEAD~1 --name-only ``` ```bash # Changes in a feature branch vs main git diff main...HEAD --name-only ``` -------------------------------- ### Sidebar Interaction Flow Template Source: https://context7_llms A template for interacting with application sidebar panels. It focuses on opening a sidebar item and verifying the appearance of the corresponding panel content, without needing to dismiss onboarding elements. ```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]" ``` -------------------------------- ### Element Traits Source: https://docs.maestro.dev/api-reference/selectors This section describes how to use Element Traits for more specific view selection. ```APIDOC ## Element Traits This section details the usage of Element Traits for advanced view selection. Specific traits can be used in conjunction with other selectors to pinpoint elements based on their characteristics. *(Detailed trait information would typically follow here, e.g., `traits: ["selected"]`)* ### Request Example ```json { "assertVisible": { "id": "checkbox-option", "traits": ["selected"] } } ``` ### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### Selector Strategy: Default Text Matching Source: https://context7_llms The primary method for selecting UI elements is by their visible text content. This approach is straightforward and readable for common interactive elements. ```yaml - tapOn: text: "Submit" ``` -------------------------------- ### Run Another Flow with Maestro Source: https://context7_llms Reuses a previously defined Maestro flow within the current flow. This promotes modularity and reduces redundancy in test creation, allowing for the composition of complex test scenarios from smaller, reusable parts. ```yaml - runFlow: file: other.yaml ``` -------------------------------- ### Validate YAML Syntax Command (Python) Source: https://context7_llms This Python function call demonstrates how to validate the syntax of a Maestro flow YAML content before execution using the `mcp_maestro_check_flow_syntax` command. ```python mcp_maestro_check_flow_syntax(flow_yaml: "") ``` -------------------------------- ### Filter UI-Related Files (Bash) Source: https://context7_llms This Bash command filters the output of `git diff --name-only` to include only files with common web development extensions like `.tsx` and `.jsx`. This helps in quickly identifying code changes relevant to UI components that may require test case updates. ```bash git diff --name-only | grep -E ".(tsx|jsx)$" ``` -------------------------------- ### Selector Basics 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 ## Selector Basics 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: * `text`: (optional) Finds element with text or accessibility text that matches the regular expression. * `id`: (optional) Finds element with accessibility identifier that matches the regular expression. * `index`: (optional) 0-based index of the view to select among those that match all other criteria. * `point`: (optional) Relative position on screen. `"50%, 50%"` is the middle of screen. `50, 75` specifies exact coordinates in pixels (x:50 y:75). * `width`: (optional) Finds element of a given width. * `height`: (optional) Finds element of a given height. * `tolerance`: (optional) Tolerance to apply when comparing width and height. * `enabled`: (optional) Searches for view with a given "enabled" state (true/false). * `checked`: (optional) Searches for view with a given "checked" state (true/false). * `focused`: (optional) Searches for view with a given "focused" state (true/false). * `selected`: (optional) Searches for view with a given "selected" state (true/false). ### Request Example ```json { "tapOn": { "id": "login-button" } } ``` ### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### Maestro Text Shorthand Selector Source: https://docs.maestro.dev/api-reference/selectors Provides a simplified syntax for selecting elements solely based on their text content. ```yaml - tapOn: 'Text' # or any other command that works with selectors ``` -------------------------------- ### Waiting Strategy: Element Appears Source: https://context7_llms This strategy utilizes `extendedWaitUntil` to pause execution until an element is visible. It's the recommended approach over fixed timeouts for reliability. ```yaml - extendedWaitUntil: visible: "Submit Button" timeout: 15000 ``` -------------------------------- ### Maestro Basic Selectors Source: https://docs.maestro.dev/api-reference/selectors Defines fundamental selectors for Maestro commands. These include text, ID, index, point, dimensions, and state attributes like enabled, checked, focused, and 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 ``` -------------------------------- ### Check for Existing Maestro Tests (Bash) Source: https://context7_llms This Bash command checks for the existence of Maestro test files (`.yaml`) within the `maestro/` directory that relate to a specific feature. It uses `grep -l` to list filenames containing the feature name, aiding in the decision to create a new test or extend an existing one. ```bash list_dir: maestro/ grep -l "feature_name" maestro/*.yaml ``` -------------------------------- ### Shorthand Text Selector Source: https://docs.maestro.dev/api-reference/selectors A convenient shorthand is available for using the `text` selector, allowing you to directly specify the text to match. ```APIDOC ## Shorthand Text Selector If you want to use the `text` selector, you can use the following shorthand: * `tapOn`: `'Text'` ### Request Example ```json { "tapOn": "Login" } ``` ### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### Waiting Strategy: Element Disappears Source: https://context7_llms This strategy uses `extendedWaitUntil` to wait until a specific element is no longer visible on the screen, often used to confirm the completion of an asynchronous operation like data loading or animations. ```yaml - extendedWaitUntil: notVisible: "Loading..." timeout: 10000 ``` -------------------------------- ### Input Text into Focused Field with Maestro Source: https://context7_llms Enters text into the currently focused input field. This command is crucial for form filling and user authentication processes. ```yaml - inputText: "user@email.com" ``` -------------------------------- ### Assert Element Visibility with Maestro Source: https://context7_llms Verifies that a specific element is present and visible in the UI. This is used for confirming expected states or successful navigation to a particular screen. ```yaml - assertVisible: "Dashboard" ``` -------------------------------- ### Tap on Element by Text with Maestro Source: https://context7_llms Simulates a click or tap action on a UI element identified by its visible text. This is a fundamental interaction for navigating and triggering actions in an application. ```yaml - tapOn: text: "Log in" ``` -------------------------------- ### Wait for Element Visibility with Maestro Source: https://context7_llms Pauses the test execution until a specified element becomes visible on the screen or until a timeout is reached. This ensures that subsequent actions are performed only after the necessary UI components are ready. ```yaml - extendedWaitUntil: visible: "Log in" timeout: 20000 ``` -------------------------------- ### Perform Swipe Gesture with Maestro Source: https://context7_llms Simulates a drag or swipe gesture between two points on the screen. This is used for interactions like scrolling or manipulating horizontally swipable elements. ```yaml - swipe: start: 40%,50% end: 80%,50% ``` -------------------------------- ### Maestro Relative Position Selectors Source: https://docs.maestro.dev/api-reference/selectors Enables selection of views based on their spatial relationship to other elements, such as 'below', 'above', 'leftOf', 'rightOf', 'containsChild', 'childOf', and 'containsDescendants'. ```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: - id: title_id text: A descendant view has id "title_id" and this text - Another descendant view has this text ``` -------------------------------- ### Selector Strategy: Fallback to ID Attribute Source: https://context7_llms When text matching is ambiguous or insufficient, the `id` attribute of an HTML element can be used as a fallback selector. It's crucial to use the actual `id` attribute and not other attributes like `data-testid`. ```yaml - tapOn: id: "submit-button" ``` -------------------------------- ### Relative Position Selectors Source: https://docs.maestro.dev/api-reference/selectors Maestro allows selecting views based on their position relative to other views, such as 'below' or 'contains child'. ```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"): * `below`: Matches a view *above* that has the given text or ID. * `above`: Matches a view *below* that has the given text or ID. * `leftOf`: Matches a view to the *right* that has the given text or ID. * `rightOf`: Matches a view to the *left* that has the given text or ID. * `containsChild`: Matches a view that has a *direct* child view with the given text or ID. * `childOf`: Matches a view that is a child of a view with a specified ID. * `containsDescendants`: Matches a view that has all the descendant views specified. ### Request Example ```json { "tapOn": { "below": { "text": "Username Input" } } } ``` ### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### Escape Special Characters in Regular Expressions Source: https://docs.maestro.dev/api-reference/selectors Certain characters have special meaning within regular expressions (e.g., '[', ']', '(', ')', '*'). If you need to match these characters literally, they must be escaped using a backslash ('\'). For instance, to match the literal text 'Movies [NEW]', you must use 'Movies \[NEW\]' to escape the square brackets. ```yaml - assertVisible: 'Movies \[NEW\]' ``` -------------------------------- ### Assert Element Not Visible with Maestro Source: https://context7_llms Verifies that a specific element is not present or is hidden in the UI. This is useful for ensuring that loading indicators disappear or that certain elements are not displayed after an action. ```yaml - assertNotVisible: "Loading" ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.