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:

{
  "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:

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

Refer this use case to understand better how to create identifier using insideOf attributes.

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":

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

Refer this use case to understand better how to create identifier using insideOf and containsDescandants attributes.

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":

{
  "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:

Relational Identifiers	Type	Description
insideOf	ElementIdentifier	The element is a descendant of this parent element.
containsDescendants	Array of ElementIdentifier	The element contains these children elements. Perfect for finding containers by their content.
rightOf	ElementIdentifier	The element is spatially to the right of an anchor element.
leftOf	ElementIdentifier	The element is spatially to the left of an anchor element.
topOf	ElementIdentifier	The element is spatially top of an anchor element.
bottomOf	ElementIdentifier	The element is spatially bottom of an anchor element.

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":

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