> For the complete documentation index, see [llms.txt](https://docs.qyrus.com/device-farm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qyrus.com/device-farm/element-explorer.md).

# Element Explorer Feature for Appium Automation Testing

## **Introduction**

The **Element Explorer** (also referred to as **Object Spy**) feature simplifies identifying UI elements on Android and iOS devices, making automation script authoring using the Appium framework efficient, robust, and accurate. Element Explorer enables you to inspect the live application user interface, capture screen DOM dumps, highlight elements on an interactive screenshot canvas, inspect complete XML attributes, test XPath locators live, and copy ready-to-use locators directly into your automation codebase.

### Benefits of using Element Explorer:

* **Accelerated Locator Identification**: Eliminates guesswork and manual trial-and-error by generating verified locators instantly.
* **Accurate & Multi-Locator Support**: Generates Accessibility IDs, Resource IDs, Names, Class Names, Index locators, and XPath queries.
* **Live XPath Evaluator**: Validate custom XPath queries directly against the screen DOM before adding them to your test framework.
* **Hierarchical DOM Tree Exploration**: Traverse parent, child, and sibling elements to locate nested or dynamic UI components.

![Element Explorer Start Session](https://2346916530-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkSZu8cT8D2Zwayrr4I91%2Fuploads%2Fgit-blob-77f1904996561739b4998ffced3d744cda60baef%2Fobject_spy_session_new_interface.gif?alt=media)

***

## 1. Accessing Element Explorer

Starting an Element Explorer session is straightforward:

1. Under **Projects**, click **“Sessions”** on your project card.
2. Click **“Mobile Session”** to open the device catalog.
3. Select your desired Android or iOS real device and your application binary.
4. Toggle the **`Element Explorer`** switch to enable Object Spy mode.
5. Click **“Start Session”**.

![Element Explorer Start Session](https://2346916530-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkSZu8cT8D2Zwayrr4I91%2Fuploads%2Fgit-blob-aee812741dbf3a1076f5c96e8e83391d9bb5c780%2Fdevice-farm-object-spy-new-interface-session.png?alt=media)

***

## 2. Capturing Screen Dumps & Inspecting Elements

### 1. Interactive Device View & Screen Dump:

* In the left pane, navigate your app to the specific screen you want to inspect.
* Click the **“Dump Screen”** button (the double-chevron icon) on the center divider.
* The platform captures a high-resolution screenshot and fetches the complete UI component hierarchy.

![Element Explorer Screen Dump and Element Selection](https://2346916530-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkSZu8cT8D2Zwayrr4I91%2Fuploads%2Fgit-blob-afaa8c08af850eead038d82fc4f0066a6d12019e%2Fnew-df-ee-selection.png?alt=media)

### 2. Interactive Screenshot Canvas & Highlighter Colors:

* Click on any visual component directly within the right-hand screenshot canvas.
* The inspected element is instantly highlighted with a bounding box.
* **Color Picker:** Use the eyedropper color picker on the top right to customize your highlighter box color (**Cyan**, **Red**, or **Purple**) for optimal visibility across dark and light app themes.

### 3. Object Finder & Locators:

Once an element is clicked, the **Object Finder** panel displays its available locators:

* **Accessibility ID:** Ideal for cross-platform automation.
* **Name / Text:** The element's displayed label or content-description.
* **ID / Resource-ID:** Android `package:id` or iOS identifier.
* **Class Name:** The underlying UI class (e.g., `android.widget.Button`, `XCUIElementTypeButton`).
* **Id Index, Name Index, Class Index:** Ordinal positions within the hierarchy.
* **One-Click Copy:** Click the copy icon next to any locator value to copy it immediately to your clipboard.

![Element Explorer Object Properties & Locators](https://2346916530-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkSZu8cT8D2Zwayrr4I91%2Fuploads%2Fgit-blob-a941cc5661d60ddfc74a9fd8aa5c3591130fc87d%2Fnew-df-ee-details.png?alt=media)

***

## 3. Advanced Inspection Tools

### 1. More Attributes Modal:

Click **“More Attributes”** at the top of the Object Finder panel to open a full modal table containing all XML attributes associated with the selected element (e.g., `bounds`, `checkable`, `checked`, `clickable`, `enabled`, `focusable`, `focused`, `scrollable`, `selected`, `displayed`).

### 2. XPath Verification Tool:

Test and refine XPath queries interactively without executing test scripts:

1. In the **“Check your Xpath”** input field, enter your candidate XPath expression (e.g., `//android.widget.Button[@text='Login']`).
2. Click **“Verify”**.
3. The evaluator will instantly check the DOM tree and return a success confirmation (e.g., *"1 element found"*) or an error message if the XPath does not match.

### 3. DOM Tree Hierarchy:

The **“Elements in hierarchy”** tree view allows you to browse the complete XML structure:

* Expand and collapse tree nodes (`mat-tree`) to navigate parent containers, layouts, and leaf elements.
* Selecting a node in the tree automatically highlights the corresponding element on the canvas and loads its attributes in the Object Finder.

***

## 4. Using Locators in Automation Scripts

Copy the generated locators and incorporate them into your automation framework:

### Python Example:

```python
from appium import webdriver
from appium.options.ios import XCUITestOptions

options = XCUITestOptions()
options.platform_name = "iOS"
options.device_name = "iPhone 14 Pro"
options.udid = "<DEVICE_UDID>"
options.app = "<APP_URL>"
options.set_capability("appium:AuthToken", "<PROJECT_TOKEN>")
options.set_capability("appium:Authentication", "<USER_API_TOKEN>")

driver = webdriver.Remote('<REMOTE_ENDPOINT>/wd/hub', options=options)

# Using copied Accessibility ID
login_button = driver.find_element(by="accessibility id", value="login_button_id")
login_button.click()

# Using verified XPath
username_field = driver.find_element(by="xpath", value="//XCUIElementTypeTextField[@name='username_input']")
username_field.send_keys("demo_user")
```

### Java Example:

```java
// Using ID locator
WebElement loginBtn = driver.findElement(By.id("com.example.app:id/btnLogin"));
loginBtn.click();

// Using Accessibility ID
WebElement submitBtn = driver.findElement(AppiumBy.accessibilityId("submit_action"));
submitBtn.click();
```

***

## 5. In-Session App Installation

You can install or switch applications on-the-fly during an active Element Explorer session without disconnecting:

1. Click the **Install App** icon on the control bar.
2. Select an existing uploaded binary from your project repository or drag-and-drop a new build file (`.apk`, `.ipa`, `.apks`, `.aab`).
3. Click **Install App** to deploy and launch the application directly on the device.

![In-Session App Installation](https://2346916530-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkSZu8cT8D2Zwayrr4I91%2Fuploads%2Fgit-blob-bce36c1521926e7e5059282d8c71a7d116b55ae0%2Fin-session-app-install.png?alt=media)

***