About locators

This page explains locators, which are essential for automated testing tools.

Table of Contents

1. Locator Overview
   • What are Locators
   • Types of Locators
   • How to Choose Locators
   • How to check UI tree
2. Utilizing Generative AI
   • Create Locators
   • Modify Locators
   • Getting Explanations for Locators
3. How to Add New Locators
4. How to Choose Locators to Speed Up iOS App Testing

1. Locator Overview

What are Locators

A locator refers to the part that specifies the screen element to be operated on within a test.

Locators are constructed based on HTML or XML that makes up the screens of web pages or mobile apps.

 The figure below shows an example of a search box UI and the HTML that constitutes it.

Types of Locators

id

An id is an attribute used to uniquely identify HTML or XML elements. Since it's unique within a page, it has the advantage of not being confused with other elements. However, there are some that are not suitable for locators, such as dynamic ids that change with each execution, or ids automatically generated by frameworks like React or Vue.js.

XPath

XPath is a path notation method for specifying elements within XML or HTML documents. Like file system paths, it specifies target elements by following the hierarchical structure of elements.

XPath has two main notation methods:

1. Absolute Path (starts with /)

xpath=/html/body/div[1]/form/input[2]

Specifies all hierarchies in order from the document root to the target element. It tends to have low maintainability because it easily stops working when there are changes to the hierarchical structure.

2. Relative Path (starts with //)

xpath=//input[@id='username']
xpath=//div[@class='button']//span[text()='Submit']

• // : Search for matching elements anywhere in the document
• [@attribute='value'] : Search for elements with specified attributes and values
• [number] : Specifies the index when there are multiple matching elements (starts from 1)
• text() : Search by text content within elements

Commonly Used Syntax

• parent:: : Parent element
• child:: : Child element
• following-sibling:: : Following sibling element
• preceding-sibling:: : Preceding sibling element
• contains() : Partial match search

Example：xpath=//button[contains(@name, 'submit-btn')]

Note that the XPath syntax in MagicPod follows XPath 1.0 as defined by W3C as the official documentation.

https://www.w3.org/TR/xpath-10

Please note that XPath 2.0 and later syntax cannot be used because Selenium/Appium, which MagicPod uses behind the scenes, only supports XPath 1.0.

CSS Selector

CSS Selector is a notation used to specify targets to which styles are applied in CSS (Cascading Style Sheets).

Basic Selectors

css=#username // ID Specification（starts with #）
css=button.button-primary // Class Specification（starts with .）

How to Choose Locators

While there are various ways to express locators, MagicPod recommends using maintainable locators—that is, locators that are less likely to be affected even when screen changes occur.

Let's explain using a search box UI as an example.

In this case, the locators that could refer to the "SEARCH" button would be as follows:

However, when the screen is changed as shown in the figure below, locators 2 and 3 would require modification.

By choosing locators that are as resilient as possible to screen changes, you can reduce test maintenance costs and help maintain the continuity of automated testing.

How to check UI tree

By checking the UI tree, you can examine the structure of the UI for which you want to obtain a locator.

1. Click "UI List" in the right-side menu of the test case editing screen
2. Click the "⋮" in the upper right corner of the UI image you want to check > "Show UI Tree"

2. Utilizing Generative AI

This section introduces how to utilize generative AI for locators.

Create Locators

When building XPath expressions manually, you can ask generative AI to suggest examples.

 Prompt example:

Please generate an XPath that points to the "Book this plan" button for the "Room only" plan in the following HTML element.
<Paste HTML here>

Example response from generative AI:

Modify Locators

You can also utilize generative AI when you want to partially modify locators suggested by MagicPod.

Prompt example:

Please modify xpath=//input[@name='username-12345'] to a more stable XPath using contains.

Example response from generative AI:

Getting Explanations for Locators

You can also utilize generative AI to deepen your understanding of locators.

Prompt example:

Please explain the meaning of the following XPath.
xpath=//span[text()='days']/parent::*/preceding-sibling::input[1]

Example response from generative AI:

3. How to Add New Locators

For information on adding and editing locators, please refer to the page below.

Add/Edit a locator

4. How to Choose Locators to Speed Up iOS App Testing

For iOS apps, data shows an approximate 4x speed difference when using an accessibility ID compared to using XPath.

Reference (available in Japanese only):

iOSアプリのテストを高速化するロケーターの選び方
 

For information on adding accessibility IDs, please refer to this page:

How to assign a unique ID