Add a locator to specify an element

What is a [Locator]

The locator is an Autify feature that allows you to specify a custom CSS Selector or XPath to identify the target element of a given step.
As explained in the following sections, you can use it to explicitly specify the target element of a particular step.

When to use [Locator]

Autify Maintenance AI comprehensively judges multiple characteristics of elements to find the one with the highest degree of match, so that elements can be continuously selected even if there are changes on the page.However, there are cases where you want to select a specific element without relying on Autify AI, or cases where a more stable test can be run by combining it with a locator. Based on the characteristics of the settings, consider using them differently for each step depending on the characteristics of your web application and your test execution policy.

1. When not using a locator (Leaving it to Autify's Maintenance AI)

Find elements using only Autify AI. If there are few changes to the structure of the website or you want to leave it to Autify AI, it is better to operate without locators.

2. When using only a locator

This is suitable when the HTML structure of the website is stable and there are no frequent changes, or when you always want to strictly identify an element with a specified locator rather than leaving it to the AI's flexible search. Specifically, specifying a locator may stabilize the test in the following cases:

• When you always want to select the Nth element in a table or list where data changes every time the test is run.
• When you always want to specify an element with a specific attribute (such as class or ID) without being influenced by other characteristics of the element.
• When Autify AI is likely to find the wrong element because the target website has a structure like the following (provided there is a stable alternative selector or XPath):
  • There are multiple elements that have the same class, id, or other attributes.
  • The element does not have any class, id, or other attributes to characterize itself.
  • The values of attributes such as class and id assigned to an element change frequently.
    If you want to speed up the step (because Autify AI is not triggered and the element is searched by the locator), use only the locator.
    

Notes

• Steps using locators will not benefit from maintenance by Autify AI. Keep the use of locators to a minimum.
• If no element matching the specified CSS selector/XPath is found, an error stating Target element not found. will occur, and the step will fail.
• If multiple elements match the specified CSS selector/XPath, the first element will be selected.

3. When combining a locator and Autify's Maintenance AI

If you specify a locator and check the Learn this element from my locator, then match it automatically feature, the initial execution will search using the specified locator. If the element is found, its characteristics are saved. In subsequent executions, Autify AI will search for the element based on the saved characteristics without using the locator.

This is suitable when changes to the UI or screen structure of the target website occur frequently, but the characteristics of the element itself remain constant. It is also suitable when you want to reduce the maintenance effort for locator updates by setting the locator as the "initial foothold" only during initial configuration, and leaving it to Autify AI thereafter.

Notes

• If Autify AI cannot find it, it will fail. If the confidence level of the found element is low, it may be marked as Needs Review. If it becomes Needs Review, be sure to check the execution results.
• Even if the correct locator is set, the search will be conducted by Autify AI without using the locator from the second time onwards, so it may fail.
• If you update the scenario itself without updating the locator settings or the step itself, the behavior of the step will not be affected, and the search by Autify AI will continue. On the other hand, if you update the locator, the locator will be used the first time after the update, and it will not be used from the next time onwards.

Summary

※Checkbox: "Learn this element from my locator, then match it automatically" feature

How to use [Locator]

1. Record a [Scenario].

2. Open the details of the step for which you want to use the [Locator], and click [Add a locator].

3. Select [CSS Selector] or [XPath] from the pull-down menu.

4. Fill in the [CSS selector] or [XPath] for the element on the page to be tested in the field.

What is a CSS Selector

From CSS selectors | MDN:

A CSS selector is the first part of a CSS Rule. It is a pattern of elements and other terms that tell the browser which HTML elements should be selected to have the CSS property values inside the rule applied to them. The element or elements which are selected by the selector are referred to as the subject of the selector.

Here are some examples of CSS selectors.

The key is to use CSS selectors that are as short as possible and uniquely identify the element.

What is an XPath

From XPath | MDN:

XPath stands for XML Path Language. It uses a non-XML syntax to provide a flexible way of addressing (pointing to) different parts of an XML document. It can also be used to test addressed nodes within a document to determine whether they match a pattern or not.

Notes on using locators

• About elements in the ShadowDOM
  • CSS selector: it can be selected by specifying the elements in the shadow-root. However, if an element matching the specified CSS selector is found in the normal DOM, the element in the normal DOM will be selected.
  • XPath: It can’t select an element inside of a ShadowDOM.
• You cannot save a scenario while the locator field is empty. If the locator is no longer needed, click the Delete Locator link to remove it.

Test results

On the details screen for each step in the test results, you can check whether the element was found by the locator or by Autify AI.

Related articles

• How do I interact with the elements in a table or list the way I intended?
• Using CSS selectors effectively
• Introduction to using XPath in JavaScript | MDN