Relational Selectors

Identify elements by position (above, below, leftOf, rightOf) or parent-child relationships (containsChild, childOf, containsDescendants).

Relational Selectors allow you to identify UI elements based on their relationship to other views on the screen. This is extremely useful when elements have generic names (like multiple "Buy" buttons) or when you want to target a view that lacks a stable text or id but is always located near a known anchor.

Overview

Selector	Description
above	Matches a view located vertically above a specified anchor element.
below	Matches a view located vertically below a specified anchor element.
leftOf	Matches a view located to the left of a specified anchor element.
rightOf	Matches a view located to the right of a specified anchor element.
containsChild	Matches a parent element that has a direct child matching specific criteria.
childOf	Matches an element that is a child of a specified parent element.
containsDescendants	Matches a view that contains a specific set of descendant elements.

Usage tips

• Compound Selectors: Positional selectors (above, below, leftOf, rightOf) use screen bounds; for example, leftOf means "left of" by coordinate only, not necessarily next to or vertically aligned with the anchor. Combining them with other attributes (id, text, enabled, etc.) improves precision: tapOn: { id: "icon", rightOf: "Settings", enabled: true }.

• Anchor Reliability: Always use the most stable element (typically static text or a unique ID) as the anchor for above, below, leftOf, or rightOf.

Alignment selectors

The vertical alignment selectors above and below identify views located above or below a reference element.

# Tap a view located below the "Email" label
- tapOn:
    below: Email

# Tap a view located above the "Checkout" title
- tapOn:
    above: Checkout

Similarly, horizontal alignment selectors leftOf and rightOf are used to identify elements positioned side-by-side, such as icons next to labels.

# Tap the view to the right of an input field
- tapOn:
    rightOf:
      id: input_text

# Tap the view to the left of a specific phrase
- tapOn:
    leftOf: I agree to the terms

These alignment selectors use screen bounds; for precision when multiple elements match, combine them with other selectors (see Compound Selectors in the tip above).

To assert vertical hierarchy

You can stack above or below to assert the vertical order of elements:

- assertVisible:
    text: Top Thing
    above:
      text: Middle Thing
      above:
        text: Bottom Thing

Parent-Child Relationships

These selectors navigate the accessibility tree rather than relying on screen position.

containsChild (Direct child only)

This matches a parent element that has a direct child matching the given selector.

# Tap the container that directly contains the text "Order 12345"
- tapOn:
    containsChild:
      text: Order 12345

childOf (Direct parent only)

This matches an element that is a direct child of a specific parent. This is useful when the same child element exists in multiple containers.

# Tap the Delete button inside the Basket
- tapOn:
    text: Delete
    childOf:
        id: basket_container

containsDescendants

This matches a view that contains all specified descendant elements, at any depth in its hierarchy. This is not limited to direct children. Use containsDescendants for complex components like cards, rows, or grouped layouts where relevant elements may be nested multiple levels deep.

# Find a list item that contains both a specific product name and a price
- assertVisible:
    id: list_item
    containsDescendants:
      - text: Wireless Headphones
      - text: $99.99