Skip to main content

Selection methods for Web objects

Last updated: October 2026

This article guides you through choosing different locator strategies for Web objects in Katalon Studio.

In the test object editor, you can add multiple locators to an object but you must select one of them as a default locator. The default locator is used for detecting the object during test execution. You can make use of multiple locators of an object when using the self-healing function in Katalon Studio. Learn more at Self-healing.

Object selection method

You can switch from one selection method to another. The detailed content of each selection method is saved automatically.

  • Selection Method: Choose a selection method among XPath, Attributes, CSS, Image, or Smart Locator.
  • Selected Locator: Input the value for your locator.

Set the default selection method​

To set the default selection method used in the Spy or Recorder activity of a project, do as follows:

  1. In Katalon Studio, go to Project > Settings > Test Design > Web UI.

    Selection methods for Web objects

  2. Under Default element locator value of test objects generated by Recorder or Spy, select one of these options:

    • XPath: Once a test object is captured using Spy/Recorder, a set of XPath locators is generated. The first value is the object's default XPath locator.
    • Attributes
    • CSS
    • Image
    • Smart Locator

  3. If you choose XPath or Attributes, you need to configure additional settings. To learn more, see below:

  4. When you are done, click Apply and Close.

Configure XPath​

This setting controls how Katalon Studio generates XPath locators when you capture Web test objects with Spy or Recorder. It is a project-level setting; it does not edit the XPath entries already stored in an individual Web test object.

You can set priorities for the generated XPath strategies by dragging and dropping them in the list. Katalon Studio uses the first generated XPath as the object's default locator. If that locator fails and self-healing is enabled, the other available locators can be evaluated as candidates from top to bottom.

To return to the default order, click Reset Default.

Below is a list of XPath capture strategies:

XPath capture strategyDescription
xpath:linkBuild XPath locators for the link element.
For example: //a[contains(text(),'Go to Homepage')]
xpath:imgBuild XPath locators for the image element.
For example: //img[@alt='Katalon']
xpath:attributesBuild XPath locators based on the tag name and attributes of the selected element.

There are 5 preferred attributes to build element locators: id, name, value, type, action, onclick.

If the element has more than one of those attributes, the locator combines the attributes with an operator.

For example: //button[@id='btn-login']
xpath:customAttributesBuild XPath locators based on the tag name and attributes of the selected element. The XPath value combines one or more attributes of all default and customized attributes. (Available from version 8.2.5)
For example: //button[@id = 'btn-login' and @type = 'submit' and (text() = 'Login' or . = 'Login')]
xpath:idRelativeBuild relative XPath locators from the nearest parent that has id attributes.
For example: //section[@id='login']/div/div/div[2]/form/div[4]/div/button
xpath:hrefBuild XPath locators of an element that has href attributes and contains a given value.
For example: //a[contains(@href, 'https://katalon-demo-cura.herokuapp.com/')]
xpath:positionBuild absolute XPath locators of a selected element.
For example: //div[3]/div/input
xpath:neighborBuild XPath locator based on the more robust neighbors of the selected element.
For example: (.//*[normalize-space(text()) and normalize-space(.)='CURA Healthcare Service'])[3]/preceding::button[1]
dom:nameBuild XPath locator based on DOM (Document Object Model). This applies only to elements within a named form.
For example: "document.forms["home"].elements["userName"]"

Configure Attributes​

You can decide which attributes to be used for detecting an object by selecting options in the Detect object by? column.

  • To return to the default setting, click Reset Default.
  • To add new attributes, click Add.
  • To delete an attribute, select the attribute and click Delete.
  • To delete all attributes, click Clear.
Attribute list

XPath​

XPath identifies elements in an XML or HTML document. In Katalon Studio, you can use generated or manually entered XPath values to locate a Web element. Smart XPath (also called Relative XPath) can use an element's surrounding structure when its direct attributes are not reliable.

XPath is configured at two levels:

  • Project level: Configure XPath controls the strategies that Spy and Recorder use to generate locators.
  • Object level: A Web test object's Object's Xpaths table stores the XPath entries available to that object.

When XPath is the default selection method for Spy or Recorder, Katalon Studio generates XPath entries using the configured strategies.

Captured objects with XPath locators

Manage XPath entries for a Web test object​

To manage an object's entries, open it from Object Repository and select XPath as the Selection Method. The Object's Xpaths table appears below Selected Locator.

Use the Object's Xpaths toolbar to manage the entries on the object:

  • Add: Click Add to create an editable row, then enter a name and XPath value such as login-button and //button[@id='login'].
  • Edit: Edit an entry's Name or Value cell inline and save the object to persist the change.
  • Delete: Select one or more rows and click Delete to remove them while preserving the order of the remaining entries.
  • Clear: Click Clear to remove all entries from the table.
  • Use CMD + Z or Ctrl + Z to restore deleted entries.

note
  • Names must be unique within the object and are case-sensitive.
  • Validation checks the entry data, not whether the XPath finds an element at runtime.
  • Unnamed XPath entries remain supported and can be renamed without changing their XPath values.
  • Deleting one identical legacy entry removes only the selected row.
  • Self-healing: When enabled, self-healing can evaluate a manually added XPath after the default locator fails and report the candidate by its Name.

Attributes​

A test object typically contains several properties. During test execution, Katalon Studio uses them to detect an object.

If Attributes is set as the default selection method during spying and recording, Katalon Studio automatically generates XPath locators that combine all the selected object properties to locate that object. In the Detect object by? column of the Object's Properties table, you can check/uncheck preferred properties.

Object attributes

CSS​

CSS (Cascading Style Sheets) locator is a syntax for addressing elements you want to style.

To manually input your CSS locator of a test object, open an object view and select the CSS option. In Selected Locator, enter a CSS locator value.

CSS locator

Change the CSS selector of an object at runtime​

To change the CSS value of a test object at runtime, use the following code snippet:

import com.kms.katalon.core.testobject.SelectorMethod

TestObject to = findTestObject('your_test_object_id')

// Change value of CSS selector
to.setSelectorValue(SelectorMethod.CSS, 'your_desired_value')

// Change selection method from another selector to CSS selector
to.setSelectorMethod(SelectorMethod.CSS)

See also:

Image​

Katalon Studio supports using image as object locator. Browse an image to compose an image locator for the object. You can learn more about how to create image property for an object at Web Image-based Testing.

Image locator

Smart Locator​

requirements

Smart Locators no longer require an unpacked extension when using browsers that support BiDi (Bidirectional communication).

  • Supported browsers include Chrome, Edge, Firefox, and headless browsers.
  • For browsers without BiDi support (such as Safari, remote browsers, or Cloud Execution environments), Smart Locators will still require an extension. If your organization prohibits loading unpacked extensions during test execution, Smart Locators may not operate as expected and will fall back on other locator methods.
  • To disable BiDi for environments that do not support it, set "webSocketUrl": false in the desired capabilities.
  • For test record and playback with restrictions on unpacked extension, consider using Katalon Compact Utility: Katalon Compact Utility.

The Smart Locator approach expands upon the existing locator strategies, significantly enhancing the accuracy and effectiveness of identifying web elements. Smart locators are particularly efficient in test scenarios that involve complex Shadow DOM structures, nested iframes, dynamic ID, or elements inside SVG. Currently, Smart locators are supported in Chrome, Firefox, and Edge Chromium.

Object with Smart Locator selected
note

Smart Locator is not backward compatible with previous versions of Katalon Studio.

  • Smart Locators of a project can be overwritten when you open the project in Katalon Studio with version below 9.3.1.
  • Self-healing suggestions associated with Smart Locators that are not approved in version 9.3.1 will not be visible when the project is opened in previous versions.

Smart locator queries the DOM to find elements through a combination of its query engine and the browser's built-in capabilities. The strategies include:

  • Selector Types: Smart locator supports a variety of selector types, including CSS selectors, XPath selectors, text selectors. Each selector type has its method for querying the DOM. For CSS and XPath selectors, Smart locator leverages the browser's native querying capabilities.
  • Execution Context: When you query for test objects using a Smart locator, the query is executed in the context of the currently active page or frame. Katalon Studio interacts with the browser through the Smart Locator unpacked extension.
  • Combining Selectors: Smart locator can chain and combine selectors to refine searches. This is particularly useful when dealing with complex DOM structures or when you need to locate an element based on multiple criteria. When combined selectors are used, Smart locator sequentially applies each part of the combined selector to narrow down the search and find the target element.
Known Issues
Was this page helpful?

Table of Contents