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

* [tapOn](/creating-tests/commands/tapon-1.md)
* [doubleTapOn](/creating-tests/commands/tapon.md)
* [copyTextFrom](/creating-tests/commands/copytextfrom.md)
* [assertVisible](/creating-tests/commands/assertvisible.md)
* [assertNotVisible](/creating-tests/commands/assertnotvisible.md)
* [scrollUntilVisible](/creating-tests/commands/scrolluntilvisible.md)
* [swipe](/creating-tests/commands/swipe.md)

## 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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.moropo.com/creating-tests/test-step-selectors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.