Test Step Selectors

A selector is an identifier used to interact with a view in your app's component hierarchy.

All selectors are optional, but at least one must be used if the test step command requires it. Many test step commands support selectors including:

• tapOn

• doubleTapOn

• copyTextFrom

• assertVisible

• assertNotVisible

• scrollUntilVisible

• swipe

All Options

# standard selectors
- assertVisible:            # or another selector-based command
    text: "Press here"          # optional - matches text or accessibility text 
    id: "login_submit_button"   # optional - matches an element ID
    optional: true              # defaults to false - skips command element not found
    index: 0                    # optional - index of the element in a list of matches (0 = first element in list)
    point: 50%,50%              # optional - relative X/Y coordinates, e.g. center of screen
    point: 10,10                # optional - pixel-based coordinates
    width: 300                  # optional - pixel width of the element to match
    height: 300                 # optional - pixel height of the element to match
    tolerance: 10               # optional - allows a range in width/height, defaults to 0
    checked: true               # optional - matches elements that are checked (true) or not (false)
    focused: true               # optional - matches elements that are focused (true) or not (false)
    selected: true              # optional - matches elements that are selected (true) or not (false)
    enabled: true               # optional - matches elements that are enabled (true) or not (false)
    
#relative position selectors
- tapOn:                    # or another selector-based command
    containsChild:              # optional - matches element that has a direct child with selector
      text: "child text"        
    containsDescendants:        # optional - matches element that has any descendant with these selectors
      - text: "text of child"
      - text: "text of grandchild"
    above:                      # optional - matches element above this text
      text: "some text"
    below:                      # optional - matches element below this text
      text: "some text"
    rightOf:                    # optional - matches element to the rightOf this text
      text: "some text"
    leftOf:                     # optional - matches element to the leftOf this text
      text: "some text"

Text Selector

Finds a view using text (or accessibility text). For example, to assert that an element rendering "Press Here" is visible:

- assertVisible:
    text: "Press Here"

ID Selector

Finds a view using an ID. For example, to assert that an element with ID "login_submit_button" is visible:

- assertVisible:
    id: "login_submit_button"

Optional modifier

If you wish to test to continue even if the view or element cannot be founder, then set optional to true. This modifier defaults to false.

- assertVisible:
    id: "login_submit_button"
    optional: true

Picking a single view from multiple matches

If the view component you are selecting has multiple matches, you can use the index option to choose a single view. For example, to tap the first card from a list of many cards:

- tapOn:
    id: "card_item"
    index: 0

Point Selector

The point selector uses X/Y coordinates to select a position on the device viewport. Provide percentages for a relative coordinate or integers to select a exact pixel.

For example, to tap on the exact center of the screen:

- tapOn:
    point: 50%,50%

For example, to swipe from the text "some text" to the pixel in the top-left corner:

- swipe:
    from:
      text: "some text"
    end: 10,10
    

Width and Height Selector

The width and height selectors will find elements with the given width and/or height in pixels.

Optionally, provide the tolerance parameter to allow a pixel range.

For example, to copy text from the first element with a width and height between 290px and 310px:

- copyTextFrom:
    width: 300
    height: 300
    tolerance: 10
    index: 0

Checked Selector

The checked selector will find elements that are checked.

For example, with a checkbox:

- assertVisible:
    id: "terms_checkbox"
    checked: true

Focused Selector

The focused selector will find elements that are focused. This can be useful for asserting that text inputs are correctly focused for input.

For example, with a button:

- assertVisible:
    id: "email_input"
    focused: true

Selected Selector

The selected selector will find elements that are selected.

For example, with a radio button:

- assertVisible:
    id: "radio_option_2"
    selected: true

Enabled Selector

The enabled selector will find elements that are enabled. Typically, almost all elements are enabled. However, this can be useful for asserting that particular elements are disabled.

For example, with a button:

- assertVisible:
    id: "proceed_button"
    enabled: false

Relative Position Selectors

Additionally, you may use a relative selector to find an element spatially or hierarchically connected to another element. This is especially useful when the element you wish to interact with is missing an ID.

Contains Child Selector

- doubleTapOn:
    containsChild:
      text: "double tap on the direct parent element of where this text appears"

Contains Descendants Selector

- doubleTapOn:
    containsDescendants:
      - text: "double tap on the parent element that contains a view rendering this text"
      - text: "and another view rendering this text"

Above Selector

- doubleTapOn:
    above:
      text: "double tap on the element above where this text appears"

Below Selector

- doubleTapOn:
    below:
      text: "double tap on the element below where this text appears"

LeftOf Selector

- doubleTapOn:
    leftOf:
      text: "double tap on the element to the left of where this text appears"

RightOf Selector

- doubleTapOn:
    rightOf:
      text: "double tap on the element to the right of where this text appears"