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:
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"
Last updated
Was this helpful?