# 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](https://docs.moropo.com/creating-tests/commands) support selectors including:

* [tapon-1](https://docs.moropo.com/creating-tests/commands/tapon-1 "mention")
* [tapon](https://docs.moropo.com/creating-tests/commands/tapon "mention")
* [copytextfrom](https://docs.moropo.com/creating-tests/commands/copytextfrom "mention")
* [assertvisible](https://docs.moropo.com/creating-tests/commands/assertvisible "mention")
* [assertnotvisible](https://docs.moropo.com/creating-tests/commands/assertnotvisible "mention")
* [scrolluntilvisible](https://docs.moropo.com/creating-tests/commands/scrolluntilvisible "mention")
* [swipe](https://docs.moropo.com/creating-tests/commands/swipe "mention")

## All Options

<pre class="language-yaml"><code class="lang-yaml"><strong># standard selectors
</strong><strong>- assertVisible:            # or another selector-based command
</strong>    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"
</code></pre>

## Text Selector

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

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

```yaml
- 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.

```yaml
- assertVisible:
    id: "login_submit_button"
    optional: true
```

## Picking a single view from multiple matches&#x20;

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:

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

```yaml
- tapOn:
    point: 50%,50%
```

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

```yaml
- 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.&#x20;

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

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

## Checked Selector

The `checked` selector will find elements that are checked.&#x20;

For example, with a checkbox:

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

```yaml
- assertVisible:
    id: "email_input"
    focused: true
```

## Selected Selector

The `selected` selector will find elements that are selected.

For example, with a radio button:

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

```yaml
- 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

<pre class="language-yaml"><code class="lang-yaml">- doubleTapOn:
    containsChild:
<strong>      text: "double tap on the direct parent element of where this text appears"
</strong></code></pre>

### Contains Descendants Selector

```yaml
- 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

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

### Below Selector

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

### LeftOf Selector

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

### RightOf Selector

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