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 additional flags (e.g., isImage, isScrollable). 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
  "isImage": true,        // Boolean indicating if the view is an image
  "isScrollable": true    // Boolean indicating if the view is 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
isImage	Indicates if the view is an image	Boolean
isScrollable	Indicates if the view supports scrolling	Boolean

---

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",
  "isImage": true,
  "insideOf": {
    "id": "nav_tab_saved"
  }
}

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",
  "isImage": true,
  "containsDescendants": [
    {
      "text": "Search"
    },
    {
      "id": "icon_search",
      "isImage": true
    }
  ]
}

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

---

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
}