maestro.mobile.dev - ReadMe.md for beginners

ReadMe.md

Maestro Test Automation

Welcome to the Maestro Test Automation documentation. This README serves as a summerized source for understanding key concepts and features of Maestro for mobile application testing.

Table of Contents

• 1. Maestro Configuration
  • 1.1. Workspace Configuration
  • 1.2. Flow Configuration
  • 1.3. Device Configuration
• 2. Maestro Commands
• 3. Maestro Selectors
  • 3.1. Basic Selectors
  • 3.2. Relative Position Selectors
  • 3.3. Selector Usage
• 4. Additional Information

---

1. Maestro Configuration

Maestro configuration is defined in a YAML file. The file is typically named config.yaml and is located in the root directory of the workspace.

The configuration file contains the following sections:

1.1. Workspace Configuration

This section defines the global settings for the workspace, such as the list of flows to run and the tags to include.

1.2. Flow Configuration

This section defines the settings for each flow, such as the app to launch and the environment variables to set.

1.3. Device Configuration

This section defines the settings for each device, such as the device name and the port to connect to.

The following are some of the key settings that can be configured in the Maestro configuration file:

• Flows: The flows property defines the list of flows to run. Each flow is defined by its filename.

• Tags: The tags property defines the list of tags to include. Only flows that have one of the specified tags will be run.

• Env: The env property defines the environment variables that should be made available to all flows.

• AppId: The appId property defines the app to launch when running launchApp.

• Name: The name property defines a custom name for the flow.

• OnFlowStart: The onFlowStart property defines a hook that is executed before the initiation of each flow. This hook can be used to run setup scripts.

• OnFlowComplete: The onFlowComplete property defines a hook that is executed upon the completion of each flow. This hook can be used to run teardown scripts.

For detailed information on Maestro configuration, refer to the relevant documentation and resources.

2. Maestro Commands

Maestro provides a comprehensive set of commands for test automation. Below is the full list of Maestro commands, each designed to perform specific actions during testing:

• assertVisible: Checks whether a view is visible.
• assertNotVisible: Checks whether a view is not visible.
• assertTrue: Checks whether a condition is true.
• back: Navigates back in the app.
• clearKeychain: Clears the keychain data for the app.
• clearState: Clears the app's state, including its preferences, databases, and accounts.
• copyTextFrom: Copies text from a view.
• evalScript: Evaluates a JavaScript script.
• eraseText: Erases text from a view.
• extendedWaitUntil: Waits until a condition is met.
• hideKeyboard: Hides the keyboard.
• inputText: Enters text into a view.
• launchApp: Launches an app.
• openLink: Opens a link in the app.
• pressKey: Presses a key on the device.
• pasteText: Pastes text from the clipboard into a view.
• repeat: Repeats a command a specified number of times.
• runFlow: Runs a flow of commands.
• runScript: Runs a JavaScript script.
• scroll: Scrolls a view.
• scrollUntilVisible: Scrolls a view until it is visible.
• setLocation: Sets the device's location.
• startRecording: Starts recording a flow of commands.
• stopApp: Stops the app.
• stopRecording: Stops recording a flow of commands.
• swipe: Swipes across the screen.
• takeScreenshot: Takes a screenshot of the device's screen.
• tapOn: Taps on a view.
• doubleTapOn: Double taps on a view.
• travel: Moves the device's cursor to a specific location.
• waitForAnimationToEnd: Waits until an animation has finished.

These commands provide the necessary flexibility to automate various actions within the mobile application during testing. Each command serves a specific purpose in the test automation process.

3. Maestro Selectors

Maestro selectors are used to identify views in the UI. There are two types of selectors:

3.1. Basic Selectors

Basic selectors match views based on their text, id, or index. Some basic selectors include:

• text: Matches views that contain the specified text.
• id: Matches views that have the specified id.
• index: Matches the view at the specified index.

3.2. Relative Position Selectors

Relative position selectors match views based on their position relative to other views. Some relative position selectors include:

• above: Matches views that are above the specified view.
• below: Matches views that are below the specified view.
• leftOf: Matches views that are to the left of the specified view.
• rightOf: Matches views that are to the right of the specified view.
• containsChild: Matches views that have a child view with the specified text.
• containsDescendants: Matches views that have all of the descendant views specified.

3.3. Selector Usage

Here are some important details and usage options related to Maestro selectors:

• Selectors can be combined using the and and or operators. For example, the selector text:"Login" and id:"login_button" would match a view that has the text "Login" and the id "login_button."

• Selectors can be negated using the not operator. For example, the selector not text:"Login" would match a view that does not have the text "Login."

• Selectors can be used with the findViews command to find all views that match the selector.

Maestro selectors play a crucial role in identifying and interacting with UI elements during test automation, providing flexibility and precision in testing scenarios.

4. Additional Information

Here's an example script that demonstrates how to use Maestro to open the Twitter app and search for tweets by a specific user, in this case, "maestro."

# Twitter Search Script

# Specify the Twitter app's package name
appId: com.twitter.android

# Start the script
---
- launchApp  # Launch the Twitter app

# Perform a Twitter search
- tapOn: "Search"  # Tap on the search button (assuming it has the "Search" text)
- inputText: "maestro"  # Enter the search query "maestro"
- pressKey: "Enter"  # Press the Enter key to initiate the search

# Wait for search results to load
- waitFor: "Search Results"  # Wait for the search results screen

# Scroll through the search results (optional)
- scroll: "down"  # Scroll down to view more search results

# Capture a screenshot of the search results (optional)
- takeScreenshot: "twitter_search_results.png"

# End the script
- stopApp  # Stop the Twitter app

Explanation:

This example script illustrates how to use Maestro to automate interactions with the Twitter app. Here's a breakdown of each step:

1. appId: We specify the package name of the Twitter app to ensure that Maestro launches the correct application.

2. launchApp: This command launches the Twitter app on the device.

3. tapOn: We tap on the "Search" button in the app's UI, assuming it has the "Search" text. This simulates a user tapping the search button.

4. inputText: We input the search query "maestro" into the search field. This simulates typing on the device's keyboard.

5. pressKey: We press the "Enter" key to initiate the search.

6. waitFor: We wait for the "Search Results" screen to load. This ensures that Maestro waits until the search results are displayed.

7. scroll (optional): If needed, we can scroll through the search results using the "scroll" command. In this script, we scroll down to view more search results.

8. takeScreenshot (optional): This command captures a screenshot of the search results and saves it as "twitter_search_results.png" (optional but useful for visual verification).

9. stopApp: Finally, we stop the Twitter app, ending the script.

This script demonstrates how Maestro allows you to automate interactions with mobile apps by simulating user actions and verifying the app's behavior. Beginners can use Maestro's simple and expressive commands to create automated test scripts for various mobile testing scenarios.