---
title: Maestro Selectors and Core Commands | Maestro Mobile Testing
description: Almost every Maestro command needs to know *which* element to act on.
  That is the job of a **selector**. This chapter covers how selectors match, the…
source_url:
  html: https://testingbot.com/resources/courses/maestro/selectors-and-commands
  md: https://testingbot.com/resources/courses/maestro/selectors-and-commands.md
---

Course

[Maestro Mobile Testing](https://testingbot.com/resources/courses/maestro)

Chapter 3 of 10

1. [1 Maestro Tutorial: Mobile UI Tests in YAML](https://testingbot.com/resources/courses/maestro)
2. [2 Install Maestro and Run Your First Flow](https://testingbot.com/resources/courses/maestro/install-and-first-flow)
3. [3 Maestro Selectors and Core Commands](https://testingbot.com/resources/courses/maestro/selectors-and-commands)
4. [4 Subflows, Conditions, Loops and JavaScript](https://testingbot.com/resources/courses/maestro/flow-control-and-javascript)
5. [5 iOS vs Android: Permissions, State, Links](https://testingbot.com/resources/courses/maestro/ios-and-android-specifics)
6. [6 Debugging Flaky Maestro Flows](https://testingbot.com/resources/courses/maestro/debugging-and-flakiness)
7. [7 Organising a Maestro Suite](https://testingbot.com/resources/courses/maestro/organising-a-suite)
8. [8 Run Maestro Flows on TestingBot](https://testingbot.com/resources/courses/maestro/run-on-testingbot)
9. [9 Running Maestro in CI Pipelines](https://testingbot.com/resources/courses/maestro/ci-pipelines)
10. [10 Knowledge check](https://testingbot.com/resources/courses/maestro/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 3 of 10 Beginner 7 min read 3 quick checks Updated Nov 2026 

# Maestro Selectors and Core Commands
On this page
1. [Two ways to write a selector](https://testingbot.com#two-ways-to-write-a-selector)
2. [The core commands](https://testingbot.com#the-core-commands)
3. [A real bug: the field that already had a value](https://testingbot.com#a-real-bug-the-field-that-already-had-a-value)
4. [Choosing selectors that last](https://testingbot.com#choosing-selectors-that-last)

Almost every Maestro command needs to know _which_ element to act on. That is the job of a **selector**. This chapter covers how selectors match, the commands you will use in nearly every flow, and a real bug from the sample app that shows why the details matter.

## Two ways to write a selector[#](https://testingbot.com#two-ways-to-write-a-selector)

A plain string is shorthand for a `text` selector:

```yaml
- tapOn: "Login" # same as: tapOn: { text: "Login" }
- assertVisible: "Welcome"
```

A map lets you combine attributes. An element must match **all** of them:

```yaml
- tapOn:
    id: submit_button
    enabled: true
    below: "Password"
```

### text[#](https://testingbot.com#text)

`text` matches what is displayed on screen. On Android that includes the `contentDescription`; on iOS it includes the `accessibilityLabel`. Two rules catch people out:

1. **It is a regular expression** , so `.*Continue.*` is a partial match and characters like `$`, `(` or `[` must be escaped with a backslash.
2. **It must match the whole text.** `assertVisible: "15"` does not match an element whose text is `150`. You will see that rule in action below.

The screen clearly shows `Total: $15`, but `assertVisible: "Total: $15"` fails. What is the likely reason?

 Text selectors only match buttons The assertion did not wait long enough `text` is a regular expression, so `$` is treated as an end-of-line anchor and has to be escaped The text must be lowercase

Text and id selectors are regexes that must match the whole text. Escape special characters such as `$`, `(` and `[` with a backslash.

### id[#](https://testingbot.com#id)

`id` matches the Android **resource id** or the iOS **accessibilityIdentifier**. It is also a regex. Ids are invisible to users, so they survive copy changes and translations, which makes them the right choice for icons, inputs and anything in a localised app. On Jetpack Compose, expose test tags as ids with `Modifier.semantics { testTagsAsResourceId = true }`; on Flutter, use Semantics identifiers rather than widget Keys, which Maestro cannot see.

The sample app is React Native, where the `testID` prop becomes the id on both platforms. That is why `id: inputA` works in the Android and the iOS build.

### When several elements match[#](https://testingbot.com#when-several-elements-match)

- `index` picks the Nth match, starting at 0: `tapOn: { id: buy_button, index: 2 }` taps the third.
- **Relational selectors** anchor on something stable nearby: `below`, `above`, `leftOf`, `rightOf` use screen position; `childOf`, `containsChild` and `containsDescendants` use the view tree.
- **State selectors** filter by `enabled`, `checked`, `focused` or `selected`.

```yaml
# The "Remove" button inside the card that contains "Order 12345"
- tapOn:
    text: "Remove"
    childOf:
      containsChild:
        text: "Order 12345"
```

A good default order of preference: an `id` you control, then visible `text`, then a relational selector anchored on stable text, and only as a last resort a screen coordinate.

A list has a Remove button in every card. You want the one in the card that contains `Order 12345`. Which selector says that?

 `tapOn: { text: "Remove", index: 0 }` `tapOn: { text: "Remove", childOf: { containsChild: { text: "Order 12345" } } }` `tapOn: { point: "50%,40%" }`

A relational selector anchored on stable text says which card you mean. `index` depends on order, and a screen coordinate breaks on another device.

## The core commands[#](https://testingbot.com#the-core-commands)

| Command | What it does |
| --- | --- |
| `launchApp` | Stops and (re)starts the app under test. Options: `clearState`, `permissions`, `arguments`, `stopApp`. |
| `tapOn` / `longPressOn` / `doubleTapOn` | Touches an element or a `point`. `tapOn` also takes `repeat`, `delay` and `retryTapIfNoChange`. |
| `inputText` | Types into the focused field. Tap the field first. |
| `eraseText` | Presses backspace, 50 times by default or `eraseText: 10` for an exact count. |
| `hideKeyboard` | Dismisses the soft keyboard. |
| `assertVisible` / `assertNotVisible` | Waits up to about 7 seconds for an element to appear (or disappear), then fails. |
| `scroll` | One upward swipe from the middle of the screen. |
| `scrollUntilVisible` | Scrolls in a `direction` (default `DOWN`) until an `element` is fully visible, up to a `timeout` (default 20 seconds). |
| `swipe` | A gesture by `direction`, from an element (`from:`), or between `start`/`end` coordinates. |
| `back` | System back button. Android and web only. |
| `openLink` | Opens a URL or deep link. |
| `takeScreenshot` | Saves a PNG into the run's artifact folder. |
| `copyTextFrom` | Copies an element's text into `maestro.copiedText`. |

A slightly larger example, for a hypothetical settings screen:

```yaml
appId: com.example.app
---
- launchApp
- tapOn:
    id: settings_tab
- scrollUntilVisible:
    element: "Delete account"
    direction: DOWN
    timeout: 10000
- tapOn: "Delete account"
- assertVisible:
    text: "Confirm"
    enabled: true
- back
- assertNotVisible: "Confirm"
```

Note what is missing: no sleeps and no explicit waits between the tap and the assertion. Assertions poll, and Maestro waits for the UI to settle after each action.

## A real bug: the field that already had a value[#](https://testingbot.com#a-real-bug-the-field-that-already-had-a-value)

When this course's flow was first written for the sample app, it looked like the version in many tutorials:

```yaml
- tapOn:
    id: inputA
- eraseText
- inputText: "10"
- tapOn:
    id: inputB
- eraseText
- inputText: "5"
- assertVisible: "15"
```

On an iOS simulator it failed: `Assertion is false: "15" is visible`. The failure screenshot showed A = `100`, B = `50` and Total = `150`.

Here is what happened. Both fields start with the value `0`. `tapOn` taps the **centre** of the element, and on iOS that put the cursor _before_ the existing `0`. `eraseText` sends backspaces, which delete characters to the left of the cursor, of which there were none. Typing `10` then produced `100`. And because text selectors must match the whole string, `assertVisible: "15"` did not match `150`, so the test correctly failed instead of passing by accident.

The fix is to tap where the cursor should end up, at the right-hand edge of the field:

```yaml
- tapOn:
    id: inputA
    point: "90%,50%"
- eraseText
- inputText: "10"
```

When `point` is combined with a selector, the percentages are relative to the matched element, not the screen, so this stays device-independent. Two lessons generalise beyond this app:

- **Always check what is already in a field.** Pre-filled values, placeholder text and saved form data all interact with `eraseText`.
- **Read the failure screenshot before changing the flow.** The answer was visible in one image; adding a retry would have hidden it.

In `tapOn: { id: inputA, point: "90%,50%" }`, what are the percentages relative to?

 The whole screen The app window, excluding the status bar The keyboard The element matched by `id: inputA`

When `point` is combined with a selector it is relative to the matched element, so the tap lands at the field's right edge on any screen size.

## Choosing selectors that last[#](https://testingbot.com#choosing-selectors-that-last)

- Ask developers to add ids to inputs, buttons and icons. It is a one-line change per element and the single biggest stability win.
- Keep text selectors for things whose wording _is_ the requirement, such as an error message.
- Avoid absolute coordinates like `point: "100,200"` on their own. They break on a different screen size.
- Use `maestro hierarchy` to see exactly which `text`, `resource-id` and `accessibilityText` values the device exposes.

These selectors work the same way when your flows later run on [TestingBot's Android and iOS devices](https://testingbot.com/support/app-automate/maestro), because the flow file does not change between local and cloud runs. If you are coming from WebDriver-style locators, the [Appium locators chapter](https://testingbot.com/resources/courses/appium-webdriverio/locate-elements) of the Appium course makes an interesting contrast. The next chapter makes flows reusable: subflows, conditions, loops and JavaScript.

[Previous · Chapter 2 Install Maestro and Run Your First Flow](https://testingbot.com/resources/courses/maestro/install-and-first-flow) [Next · Chapter 4 Subflows, Conditions, Loops and JavaScript](https://testingbot.com/resources/courses/maestro/flow-control-and-javascript)

On this page

1. [Two ways to write a selector](https://testingbot.com#two-ways-to-write-a-selector)
2. [The core commands](https://testingbot.com#the-core-commands)
3. [A real bug: the field that already had a value](https://testingbot.com#a-real-bug-the-field-that-already-had-a-value)
4. [Choosing selectors that last](https://testingbot.com#choosing-selectors-that-last)

Certification

Earn the free, resume-worthy TestingBot Maestro Certification for this course.

[How it works](https://testingbot.com/resources/courses/maestro/certification)
