# Elements

> Create elements by recording them or entering locators by hand, pick locator types, set precedence, and handle Shadow DOM, iframes, and dynamic locators.

An element is a UI component a test step acts on, such as a field, a button, or a link. Testsigma stores elements in a repository, so a step refers to an element by name and every step using it picks up a change at once.

Create elements by recording them from the running application, or by entering the locator yourself.

## Locator types

A locator tells Testsigma how to find the element on screen. Web applications support 7 types.

| Locator | What it matches | Example |
|---|---|---|
| XPath | A path through the page's structure, using elements and attributes. Any element can be written several ways, and most other locators can be expressed as an XPath | `//input[@id="email"]` |
| CSS Selector | A pattern combining tag, id, class, and attributes. The only locator that reaches inside a Shadow DOM | `input#email` or `input.inputtext` |
| Link Text and Partial Link Text | The visible text of a link, in full or in part | `Forgot password?`, or `Forgot` for partial |
| ID | The `id` attribute, which the W3C standard expects to be unique | `email` |
| Name | The `name` attribute, which is not strictly unique | `userName` |
| Class Name | The `class` attribute | `inputtext` |
| Tag Name | The tag itself, useful for pulling the content inside it | `input` |

ID is the first choice when an element has a unique one. Link text has to be unique on the page: when several links share it, such as repeated header and footer menus, the step acts on the first match.

Android and iOS applications support 5 types, in this order of preference:

- **Accessibility ID**: the first choice. The same value carries across Android and iOS, which makes a test easier to port, and it is the least likely to change when the source is restructured
- **ID**: the second choice. Every element is supposed to have a unique one
- **XPATH**: parses the source to reach the referred element
- **Class Name**: the value of the element's Class Name attribute
- **Name**: the value of the element's Name attribute

If you cannot find IDs for your elements, ask your developer to add them.

A unified mobile element stores an Android locator and an iOS locator under one name, and the types can differ per platform: XPath on Android with Accessibility ID on iOS works, as long as each value uniquely identifies the element on its platform.

## Create an element manually

Manual creation suits dynamic applications, where an element's attributes change between sessions and a recorded locator stops matching.

Go to **Create Tests > Elements**, click **Create Element**, fill in the fields, and click **Create element**. The element is saved to the elements list.

- **Name**: what you call the element in test steps
- **Screen Name**: the screen or page the element sits on, used to group elements
- **Element Type**: **XPATH**, **ID**, **Name**, **Class Name**, or **Accessibility ID**. These are the 5 types the dropdown offers
- **Enter Value**: the locator value for the type you selected

![The Create Element panel, with the name, screen name, element type, and value fields](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_web_elements_3.png)

Click **Record Element** on the **Create Element** page to capture the element instead of typing its locator.

You can also create an element while writing a step. Open a test case, add a step that takes an element, hover over the element placeholder, and select **Create Element** from the dropdown.

Writing a locator by hand needs a working knowledge of XPath and CSS selectors.

### Unified mobile elements

For a Unified Mobile application, the **Create Element** overlay carries an **Android** tab and an **iOS** tab. Select the **Element Type** and enter the value on each tab, for one platform or both: an element with a locator for only one platform is usable when a test case runs on that platform.

Leave **Auto heal element during execution** checked to let Testsigma recover this element's locator if it changes, or clear it to opt out.

Each platform's locator updates independently in the **Update Element** overlay: changing one never touches the other.

### Read a locator off the page

Right-click the element in Chrome and select **Inspect**. The **Elements** panel opens with your element highlighted in blue, showing its HTML.

HTML elements follow this shape, where the tag name, the attribute names, and the values in quotes are all candidates for a locator:

```html
<input type="submit" name="Submit" class="button" id="btnLogin" value="LOGIN">
```

Here the tag name is `input`, and the attributes are `type`, `name`, `class`, `id`, and `value`. Build the element from a single attribute whose value is unique, from a link's visible text, or from an XPath or CSS selector you write against that HTML. ID is the preferred single attribute.

## Record elements

The recorder flow depends on the application type.

Recording needs the Testsigma Chrome extension and an application you can reach.

1. Go to **Create Tests > Elements** and click **Record**.

2. Enter the URL to capture from in the new tab. The recorder opens and waits.

3. Hover over an element until it highlights in green.

4. Click it and wait for it to appear in the recorder.

5. Repeat for every element you want.

6. Click **Stop**.

![The Record Elements panel over the application, listing a captured element and its screen name](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_elements_5.png)

The recorder returns you to the **Elements** page with everything you captured.

The recorder stores a page image with each element, highlighting the element on it, so you keep the visual context alongside the locator. The Testsigma gear icon blinks while recording and stops when you pause.

1. Go to **Create Tests > Elements** and click **Record**.

2. In the **Record Elements** overlay, select the **Test Lab** and **Test Machine**, supply the app under **Upload App Source**, and click **Record**.

3. Wait for the app to load fully.

4. Click the element you want to capture.

5. Check the **Name**, **Screen Name**, **Element Type**, and **Value** in the **Create Element** section.

6. Click **Create**.

To change a captured element, hover over it and click the edit icon, change the details, and click **Update**.

Mobile web recording pairs the recorder with Chrome DevTools.

1. Go to **Create Tests > Elements** and click **Record**.

2. Enter the URL in the new window.

3. Select **Companion Mode** in the action bar.

4. Press **F12** to open Chrome DevTools, and dock it to the right of the window.

5. Click **>>** and select **Testsigma Recorder**. The recorder opens inside DevTools.

6. Select the device dimension to record at.

7. Click the elements to capture them, and click **Stop** when you are done.

If the device you test on is not in the list, select **Edit** in the **Dimensions** dropdown and click **Add custom device**. A device's own characteristics can change how an element displays and behaves, so recording at the right dimension matters.

Recording captures one platform at a time. Recording the same element on the second platform adds that platform's locator to the existing element instead of creating a duplicate.

1. Go to **Create Tests > Elements** and click **Record**.

2. In the **Record Elements** overlay, select the **Test Machine** (Android or iOS) to record on, along with the **Test Lab** and **Upload App Source**, and click **Record**. Upload an IPA when the test machine's OS is iOS, or an APK when it is Android; the overlay does not show the app source uploaded for the other OS, even from earlier in the same session.

3. Wait for the app to load fully.

4. Click the element you want to capture.

5. In the **Create Element** panel, confirm the **Name**, **Screen Name**, **Element Type**, and **Value** for the platform you are recording on, and click **Create**.

6. Repeat for every element you want to capture, then click **Stop Recording**. You return to the **Elements** page with everything you captured.

To add the other platform's locator to an element you already captured, open it from the elements list, click **Edit**, select the tab for the platform you have not captured yet, click **Record**, and record it the same way.

The desktop Element Recorder captures elements into a hierarchical tree with their properties. It needs a Desktop project and application, Testsigma Terminal installed on the Windows system, the **WinTest Automation** folder present in the Testsigma Agent directory, and the application open on your device.

1. Go to **Create Tests > Elements** and click **Record**.

2. In the **Select application** window, select the desktop application to record against. Only applications running on your device are listed; filter with the search field, or click the refresh icon after opening a new application.

3. Click **Start recording**. The Element Recorder opens on the **Selective** tab, with the application name in the recorder header.

4. Capture in either mode:
   - **Selective**: hover over an element until it highlights in green, then click it. To capture elements that disappear on hover, such as menus and dropdowns, click **Freeze** (Ctrl+Shift+F) to hold the current UI state first.
   - **Batch**: click the **Batch** tab to capture every element in the currently open window at once. Switching windows within the same application captures the new window and clears the previous one.

5. Select a captured element in the tree to check it in the **Element properties** panel (Name, Type, Class, AutomationId, FrameworkId), and click **Locate** to highlight it in the application window.

6. Click **Save**. The elements are listed under **Create Tests > Elements**.

**Pause** keeps the application open and retains what you recorded; **Stop** ends the session; **Expand all**, **Collapse all**, and the search field manage the tree, and the footer shows a running count such as **78 elements recorded**. Keyboard shortcuts: **Alt+R** records, **Alt+S** stops, **Ctrl+Shift+F** freezes.

Batch capture records the full control tree of the window, including containers such as the title bar and tab groups. Use the search field to narrow the tree to the elements you need before saving.

Salesforce elements are learned automatically when the metadata connection syncs (see [Setup](https://testsigma.com/docs/v2/application-types/salesforce/setup/)), so there is nothing to record or create for standard objects. Auto-learned elements cannot be edited.

Learned elements follow two naming conventions, and names must stay unique:

- **Field names**: **ObjectName_FieldName**, so **Account_CreatedDate** is the **CreatedDate** field on the **Account** object.
- **Screen names**: the object name as displayed on the UI screen, so a screen of account details is **Account**.

To browse the repository, open a test case, add a step, hover over the element and click **Select Element**; the **Elements** overlay lists everything learned. Clicking an element that follows the naming convention and selecting **View/Edit Element** in the **Testsigma Debugger & Recorder** shows an overlay confirming it is a standard, pre-learned Salesforce element.

For an element the sync did not learn, capture it live from a step:

1. Open the test case and click **Copilot**.

2. In the **Debug & Record** overlay, verify that Copilot is live, select a connection under **Salesforce Metadata connection**, and click **Launch**.

3. In the **Testsigma Debugger & Recorder**, click the element in the NLP step and select **Create Element** from the dropdown.

4. Click the UI element to capture. The recorder captures the element details.

5. Verify the element and click **Create**.

## Set locator precedence

Locator precedence tells the recorder which locator type to reach for first, across Link Text, Name, ID, CSS Selector, and XPath. The recorder works down your order and takes the first locator that is static and unique.

1. Go to **Create Tests > Elements** and click **Record**.

2. Click **Locator precedence** in the recorder.

3. Drag the handles into the order you want.

4. Click **Save**.

![The Locator precedence panel in the recorder, with the locator types in draggable order](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/lplpovrly.png)

Testsigma reverts to the default order if you leave without saving.

A precedence applies only to the user who set it, and only to the application it was set for.

## Verify an element while recording

Verify an element during recording rather than waiting for a run to fail on it.

1. Open a test case and click **Record**.

2. Hover over the element in a step, click it, and select **Edit Element**.

3. Click **Verify** in the **Update Element** screen. The element highlights on the page.

4. If the element does not exist, a message says so. Correct the locator and verify again until it highlights.

![The Update Element panel in the recorder, with Verify below the captured element image](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/verify_elements_7.png)

## Update an element

Go to **Create Tests > Elements**, click the ellipsis icon (⋮) next to the element, and click **Edit**. Change the **Name**, **Screen Name**, **Element Type**, or **Element Value** in the **Update Element** overlay, and click **Update**. Clicking the element opens **Element Details**, where **Edit** opens the same overlay.

To update many elements at once, export them, change the fields you need, and import the file back. See [Import and export elements](#import-and-export-elements).

## Image-based elements

An image element identifies a control by pixel recognition instead of the DOM, which helps when dynamic behavior keeps breaking an XPath.

1. Go to **Create Tests > Elements** and click **Create Element**.

2. Click **Record Element** to open the recorder.

3. Enter the **Name** and **Screen Name**, and select **Image** as the **Element Type**.

4. Click **Capture** to take the element from the screen, or **Upload** to supply a screenshot.

5. Select the part of the screen that holds the element, and click **Capture**.

![Capture Element in the recorder, with Image as the element type and Capture or Upload for the image](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_learn_elements_5.png)

Crop the capture tight to the control, with even padding on all sides. A capture that includes surrounding background, or cuts the control off, matches less reliably.

![Tight, evenly padded captures work; loose, cropped, or context-heavy ones do not](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/Dos_donts_padding.png)

The element is saved to the elements list. You can also do this from a test case: click **Record**, create a step that takes an element, click the element, and select **Create Element**.

## Shadow DOM elements

A Shadow DOM attaches a hidden DOM tree to an element, keeping its styles and markup separate from the main page. Those elements do not exist in the main DOM, so ordinary locators cannot reach them. Only a CSS selector can.

To check whether a page uses one, right-click the page, select **Inspect**, expand the `` tag on the **Elements** tab, and look for `#shadow-root`.

| Term | What it is |
|---|---|
| Shadow host | The HTML element the shadow DOM is attached to |
| Shadow tree | The hidden tree of DOM elements inside the shadow DOM |
| Shadow boundary | The line separating the shadow DOM from the main DOM |
| Shadow root | The root node of the hidden tree |

![Chrome DevTools showing a #shadow-root in the element tree, with Copy selector in the context menu](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/captureelement_shadowdom.png)

Capture one from **Create Tests > Elements**: click **Create Element**, click **Record Element** in the overlay, open the page in a new tab, click the element, and click **Capture**.

## iframe elements

The recorder captures the iframe details with the element, so a test case works without the `switch to the frame` NLP.

If you do use `switch to the frame`, edit every iframe element in that test case and clear **present inside nested content**.

Turning on **Present inside nested content** while already inside an iframe fails the test, because Testsigma starts looking for nested iframes.

## Dynamic locators

When part of a locator changes between runs, put the changing part in test data and reference it from the locator. Testsigma accepts parameterized XPath and CSS selectors, taking the variable from a test data profile parameter, from environment data, or from a runtime variable. This is what makes a data-driven test work against elements whose attributes shift.

Reference an environment parameter in the locator with `*|parameter_name|`. If the username on screen is `dev-admin` on Dev and `qa-admin` on QA, store it as an environment parameter and write the locator as `//button[text()='*|username|']`. Testsigma substitutes the environment's value at runtime.

For a value that only exists mid-run, store it into a runtime variable with an NLP first, then reference that variable in the locator. Recording a dynamic element is unreliable, so create these elements manually.

For an element in a table, copy a working XPath first: right-click the element, select **Inspect**, then right-click the highlighted HTML and select **Copy > Copy XPath**. Generalize the row or column position from there.

A date widget marks today's date with its own class, and the class differs by date library but follows a pattern. In a JQuery UI date picker, today carries `ui-state-highlight`, so today, tomorrow, and any later day are:

```text
//td/a[@class='ui-state-default ui-state-highlight']
//td/a[@class='ui-state-default ui-state-highlight']/following::td[1]
//td/a[@class='ui-state-default ui-state-highlight']/following::td[7]
```

An overlay that closes the moment you inspect it can be frozen. Open DevTools, go to the **Sources** tab, bring the application to the state you need, and click **Pause script execution**. When clicking the page closes the overlay first, trigger the click from the console on a delay instead:

```javascript
element1 = document.querySelector("#gbwa");
setTimeout(function() {
  element1.click();
}, 3000);
```

Disabling JavaScript temporarily also works, but not reliably.

## Flutter applications

Mobile automation on Flutter reads the app's semantics tree, not its widget tree. An element is identifiable only when its widget carries a semantic label.

Most built-in Flutter widgets set semantic properties already. Custom widgets often do not, and semantics for several widgets can be merged into one, which hides the individual elements. When an element cannot be identified, the app developer has to set the semantic label on that widget.

## Find and organize elements

Search by name from the search bar on the **Elements List** page.

Sort by **Title**, **Created Date**, or **Updated Date**.

To filter, click **Show Filters > Add Filter** and pick from **Element Value**, **Name**, **Linked to Test Case**, **Labels**, **Screen Name**, **Element Type**, **Created By**, **Created Date**, and **Updated Date**, along with any custom field. Filters stack. Click **Reset** or **All** to clear them.

To keep a filter, click **Save Filter > As New**, name it in **Config Name**, and select **Public** to share it with everyone who can access the project. Saved filters sit under **Saved Filters**, split into Custom and Predefined, where you can edit or delete each one.

Click **View** in an element's affected list to see the test cases, step groups, test suites, and test plans a change to it would reach.

Larger teams can turn on review management for elements, so an element is reviewed before it joins a regression suite, the same way a test case is.

## Import and export elements

Import and export move elements between application versions, in the same project or a different one. They also handle bulk edits: export the elements, change them in the file, and import the file back.

To import, go to **Create Tests > Elements**, click **Import**, click **Browse File** and select your file, choose **Overwrite** or **Ignore** for duplicates, then click **Import**.

![The element Import panel, with the uploaded file and the Overwrite or Ignore choice for duplicates](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_IE_elements_4.png)

To export, go to **Create Tests > Elements** and click **Export**.

Both run in the background, and Testsigma emails you when they finish.

| Column | What it holds |
|---|---|
| UUID | The element's unique identifier, present only on exported elements |
| Name / fieldName | The element's name |
| Screen Name / screenName | The screen the element sits on, used for grouping |
| Locator Type / locatorType | The type of locator |
| Value / fieldDefintion | The locator value for that type |
| Created Using / createType | How the element was created |

To update elements, keep the UUID column intact so each row updates the right element, and change the other fields as needed. To create elements in bulk, clear both UUID columns.

A sample import template is available in the Element Import dialog.

A development team can use the same route to hand over locators for UAT, adding custom attributes to the application to make it more testable and supplying them as a spreadsheet.