# Element identifier

This document outlines how to specify and identify UI elements for test steps such as Tap, LongPress, and Scroll. It covers both simple and relational element identifiers, ensuring that each view is uniquely identified during automated interactions.

***

### 1. Overview

UI test steps require that the target view be specified using an **identifier**. These identifiers are constructed using a combination of view properties (such as `id`, `text`, `accText`) and type of the element like (e.g., `image`, `editable` `switch`  `radioButton` `checkbox` `scrollable`) . When a single set of properties is insufficient to uniquely identify a view, relational identifiers can be applied.

***

### 2. Simple Element Identifier

A **Simple Element Identifier** uses a combination of the element properties to uniquely locate a view. The following JSON structure illustrates a simple identifier:

```json
{
  "id": "id",             // Resource ID for Android
  "accText": "accText",   // Content description of the view
  "text": "Sign up",      // Text displayed on the view
  "type": "image",        // or "scrollable" indicating if the view is an image or "scrollable"
}
```

#### 2.1 Element Properties Table

Below is a table summarizing the element properties available for constructing a simple identifier:

| **Property** | **Description**                                                                                              | **Type** |
| ------------ | ------------------------------------------------------------------------------------------------------------ | -------- |
| `id`         | Unique resource identifier                                                                                   | String   |
| `accText`    | Accessible text (content description)                                                                        | String   |
| `text`       | Display text on the view                                                                                     | String   |
| `type`       | Indicates if the view is an `image` or `scrollable` or `editable` or `switch` or `radioButton` or `checkbox` | String   |

### 3. Relational Element Identifier

In cases where a view cannot be uniquely identified using simple properties, **Relational Element Identifiers** provide additional context by considering the view’s relation to other UI elements.

#### 3.1 Relation with Parent Element

If the target element is nested within a parent view, include the parent’s identifier using the `insideOf` key. This combination helps in uniquely specifying the target element.

**Example**

To click on an image view with `id: nav_bar_item_icon_view` located within a container having `id: nav_tab_saved`:

```json
{
  "id": "nav_bar_item_icon_view",
  "type": "image",
  "insideOf": {
    "id": "nav_tab_saved"
  }
}
```

{% hint style="info" %}
Refer [this](../usecase-custom-identifier#relational-element-identifier-with-insideof-attribute) use case to understand better how to create identifier using insideOf attributes.&#x20;
{% endhint %}

#### 3.2 Relation with Descendants

When the target element contains descendant elements, the `containsDescendants` key is used. This key holds an array of identifiers for the descendant elements, ensuring the target element is uniquely recognized.

**Example**

For a search container that includes a label with `text: "Search"` and an image with `id: "icon_search"`:

```json
{
  "id": "search_container",
  "type": "image",
  "containsDescendants": [
    {
      "text": "Search"
    },
    {
      "id": "icon_search",
      "type": "image"
    }
  ]
}
```

{% hint style="info" %}
Refer [this](../usecase-custom-identifier#relational-element-identifier-with-insideof-and-containsdescendants-attribute) use case to understand better how to create identifier using insideOf and containsDescandants attributes.&#x20;
{% endhint %}

#### 3.3 Spatial Relation with Other Elements

Spatial relations can also be used when the target element is positioned relative to other elements on the screen. Keys like `rightOf` help define the relative positioning.

**Example**

For a checkbox located within a recycler view (`insideOf`) and placed to the right of an element with `text: "Setings"`:

```json
{
  "id": "checkbox",
  "insideOf": {
    "text": "recycler_view"
  },
  "rightOf": {
    "text": "Setings"
  }
}
```

***

3.4 Relational Identifier table

Below is a table summarizing the available for constructing relational identifier:

<table data-header-hidden><thead><tr><th width="201.60546875">Text</th><th width="215.3203125">Text</th><th width="318.26953125">Text</th></tr></thead><tbody><tr><td>Relational Identifiers</td><td>Type</td><td>Description</td></tr><tr><td><code>insideOf</code></td><td>ElementIdentifier</td><td>The element is a descendant of this parent element.</td></tr><tr><td><code>containsDescendants</code></td><td>Array of ElementIdentifier</td><td>The element <em>contains</em> these children elements. Perfect for finding containers by their content.</td></tr><tr><td><code>rightOf</code> </td><td>ElementIdentifier</td><td>The element is spatially to the right of an anchor element.</td></tr><tr><td> <code>leftOf</code></td><td>ElementIdentifier</td><td>The element is spatially to the left of an anchor element.</td></tr><tr><td><code>topOf</code> </td><td>ElementIdentifier</td><td>The element is spatially top of an anchor element.</td></tr><tr><td> <code>bottomOf</code></td><td>ElementIdentifier</td><td>The element is spatially bottom of an anchor element.</td></tr></tbody></table>

### 4. Selecting One View Among Many Similar Elements

When multiple views match the same identifier properties (e.g., several views with `text: "Submit"`), the `index` parameter specifies which instance to interact with. Indexing is zero-based.

**Example**

To select the 3rd view (index 2) with `text: "Submit"`:

```json
{
  "text": "Submit",
  "index": 2
}
```
