Exit course
Chapter 3 of 10 Beginner 7 min read 3 quick checks Updated

Maestro Selectors and Core Commands

On this page
  1. Two ways to write a selector
  2. The core commands
  3. A real bug: the field that already had a value
  4. 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#

A plain string is shorthand for a text selector:

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

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

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

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 and id selectors are regexes that must match the whole text. Escape special characters such as $, ( and [ with a backslash.

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#

  • 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.
# 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?

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#

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:

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#

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

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

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

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#

  • 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, because the flow file does not change between local and cloud runs. If you are coming from WebDriver-style locators, the Appium locators chapter of the Appium course makes an interesting contrast. The next chapter makes flows reusable: subflows, conditions, loops and JavaScript.