Web Test Object

Create a Test Object

  1. Select File > New > Test Object from the main menu. The New Test Object dialog is displayed.

  2. Provide a name for the new test object, then click OK button. The new test object is created under the Object Repository of Katalon Studio.

Add an object property

There cannot be two properties with similar names in the same test object.

  1. In the Test Object Editor, click Add.
  2. The Add property dialog is displayed.


  • Name: The name of the object property. The drop-down list provides some standard options for your selection (XPath, CSS, class, id, title), or you can enter manually.
  • Match condition: to search for the "actual" object in the AUT when executing automation tests.
  • Value: to complete a match condition.
  1. The new property is added to the properties list as specified. You can also edit the properties' values here.

Manage parent object

Nowadays, there are many web applications rendering elements in an iframe. Therefore, you have to tell your script how to traverse a website's iframes and select the correct iframe where the text and its object are present. To do so, you have to use the 'Switch To Frame' keyword before interacting with the elements.

Katalon Studio supports an ability to define parent iframe object within the test object view, so you only need to select the parent iframe, and the execution automatically switches to that iframe.

Properties used for detecting an object

Selection Method

Katalon Studio allows you to choose different ways to locate objects.


  • Katalon Studio supports Relative XPath for better object recognition. If an element cannot be consistently located using its direct attributes, Katalon Studio identifies the element by using its more robust neighbors.


  • Katalon Studio automatically generates its XPath combined with object properties to locate the object. This XPath is displayed in Selector Editor.

  • A test object is typically built up by several properties. During test execution, Katalon Studio uses them to detect an object. Using the Detect object by field, you can determine which properties to be utilized for recognizing objects.

    In the following example, Katalon Studio tries to find any object on AUT with both text and XPath to satisfy the defined criteria during execution.


  • With CSS, you are allowed to input CSS locator for objects in Selector Editor manually.

Validate Test Object on AUT

You can add test objects to the Web Object Spy dialog to verify the detection in the application under test. Refer to Spy Web Utility (version 4.8 and below) for details regarding how to validate captured objects against the application under test.

To add an object to Web Object Spy, right-click on the item to open its context menu and select the option.

Test Objects in Script View

The test case Script View allows you to define Test Objects as needed programmatically. The following is a simple sample demonstrating how to define the Medicare option with the Attributes, XPath and CSS selection methods.

Step 1: Create a new object programmatically using TestObject class:

// Create a new object programmatically
TestObject myNewObject = new TestObject('ObjectID')

Step 2:

  • With the Attributes selection method, add the property to an object using addProperty() method:

    //Add property to Test Object, a property is defined by:
    // property name,
    // condition type,
    // property value,
    // a boolean value to indicate if the property will be used to identify the object during execution
    myNewObject.addProperty('xpath', "//*[@id=\"appointment\"]/div/div/form/div[3]/div/label[1]", true) //Medicare
  • With XPath and CSS: Specify a selection method and set a value to the locator:

    myNewObject.setSelectorValue(SelectorMethod.XPATH,"//*[@id=\"appointment\"]/div/div/form/div[3]/div/label[1]") //Medicare
    myNewObject.setSelectorValue(SelectorMethod.CSS,"#appointment > div > div > form > div:nth-child(3) > div > label:nth-child(1)") //Medicare

The following API docs may prove useful when working with test objects:

Class Method Description
Test Object addProperty(String name, ConditionType condition, String value) Add a new property to the test object.
setProperties(List properties) Set the properties of the test object.
getObjectId() Get an object ID.
findPropertyValue(String name, boolean caseSensitive) Find the value of a property using the property name.

Working with Objects Selection Method for Spy/Record Web

Katalon Studio Object Properties makes Spying and Recording Web feature easier and more powerful. Enhanced Object Properties allows users:

  • Choose objects locating strategies including XPath (Smart XPath), Attributes or CSS.
  • Check only preferred object's properties on the grid.
  • Manually input the desired XPath or CSS locator in Selector Editor.


Learn more about Smart XPath (a.k.a. Relative XPath).

Katalon Studio supports Relative XPath for better object recognition. If an element cannot be consistently located using its direct attributes, Katalon Studio will identify the element by using its more robust neighbors. This method is visually intuitive as it reflects the way users often identify a visible element on the user interface.

If Xpath option is selected, Katalon Studio will automatically generate a list of Relative Xpath based on your Web Locators Setting to identify the element.


If Attributes option is selected, Katalon Studio will automatically generate XPath locator that combined all selected object properties to locate that object. You can checked/unchecked preferred properties in the object properties table.


Test engineers who wish to manually input their own CSS locator for test objects can select CSS option. Once selected, object properties table will be collapsed and Selector Editor field becomes editable. Simply provide CSS locator in the Selector Editor text box. 

Same as Attributesoption, click on Verify and Highlight button to make sure Katalon Studio can locate the web objects. Katalon Studio will display the message on how many elements are found or NOT found with input XPath or CSS locator. If the object is found, it will be highlighted with the **red **border. 

Once finished, click Save to add objects to Object Repository as normal.

Verify and Highlight

Katalon Studio Object Properties has a built-in Verify and Highlight feature to help users double-check if the web objects can be located. Katalon Studio will display the message on how many elements are found or NOT found with generated XPath locator. If the object is found, it will be highlighted with the **red **border.

Once finished, click Save to add the object to Object Repository as normal.

Working with Shadow DOM Objects

Shadow DOM provides a powerful and useful solution for Web Developers. However, it becomes a challenge for automation testing because Shadow DOM elements inside a shadow root technically do not exist in the main document. Therefore, test automation frameworks that relying on XPath or querySelector to discover elements will not work with Shadow DOM.

Katalon Studio allows users to work with Shadow DOM elements. First, users need to use Spy Web feature to capture parent objects that contains Shadow DOM elements.

Next step is to identify the properties of Shadow DOM element and create a new object in Katalon Studio with properties defined accordingly.

In the new object setting, select Shadow Root Parent option and define with parent object from the firs step. This allows Katalon Studio traverse through parent object via generated CSS selector to detect Shadow DOM object by its properties (Refer to Object Properties).

For example, the following test execution log shows Katalon Studio tried to find parent object first. Once parent object was found, Katalon Studio will try to find Shadow DOM element by CSS selector:


  • Only for Chrome browser (53 to latest Version). Other browsers will be considered for future releases.
  • Only allow 1 level of nested Shadow DOM parent
  • Record and Spy feature will not work with Shadow DOM (due to elements do not exist in the DOM).

Change CSS selector of an object at runtime

To change a Test Object's CSS value at runtime:

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

See also:

Modify object properties at runtime

If you have multiple and similar objects you want to quickly interact with during test execution, and you really don't want to spend time writing duplicate steps to interact with them, the approach below will help you reduce the time and make your code nicer:

Use CSS or XPath to locate your elements, and then you start changing the IDs (let's say). For example:

TestObject yourObject = WebUI.modifyObjectProperty(findTestObject('Object Repository/Some object'), 'css', 'equals', '#${i}', true)

where 'i' is the loop counter. You can put it all inside of a loop that will read your excel sheet:

for (def i=0; i <= fineTestData('Path to your excel').getRowNumbers(); i++) {}

https://www.katalon.com/resources-center/tutorials/data-driven-testing/ for linking data with test.


Credit to Mate Mrse

Creation of Test Object in Memory at Runtime

You can create a new Test Object in Object Repository during runtime using this custom keyword:

* Construct a Katalon-compatible TestObject in memory.
* @param css (String) The CSS selector used to find the target element.
* @return (TestObject) The constructed TestObject. 
static TestObject makeTO(String css) {
	TestObject to = new TestObject()
	to.addProperty("css", ConditionType.EQUALS, css)
	return to

Credit to Russ Thomas

Parameterize Web Test Objects

With parameterizing test objects, you can update test objects' locators dynamically by using either local or global variables.

This feature comes in handy in these use cases:

  • You want to perform a bulk action on a group of similar elements without defining multiple Test Objects, such as checking on multiple checkboxes;

  • You can only identify an object's locator during runtime because there's a group of similar objects and the chosen one cannot be specified beforehand in test scripts.

Katalon Studio supports parameterizing properties of test objects to handle dynamic objects. Dynamic objects are those that have some particular changes in their properties based on specific business rules. The example below describes how to apply this feature.

Open the Health Care sample project, navigate to Object Repository/Page_Login.

  1. Select the object whose properties you want to parameterize. In this case, the selected test object is txt_Username.
  2. Capture its locator and create a variable with this syntax ${variable_name} as a place holder for its dynamic property. For example, we create the ${id} variable for the id property's value. You can parameterize test objects with different selection methods.
  • Attributes

  • XPath

  • CSS

  1. Using the parameterized test objects.
  • Manual View

    Open your Test Case in the Manual View and double-click on the object that you want to parameterize its properties.

    In the displayed Test Object Input dialog, declare the expected dynamic property as a variable in the Variables panel.

    • Param Type: the variable type (The default type is String).
    • Param: the variable name.
    • Value Type: the type of the variable's value.
    • Value: a specific value of that variable.

    In this case, Katalon Studio uses the id variable with its specific value as 4TH4T934253&#^%( to find the txt_UserName object.

  • Script View

    Once the property is declared, you can switch to the Script View and adjust the perceived value of the property. Typically, users want to pass the property value as a variable or refer to data files.

    The general syntax to find a test object using a dynamic property is as follows:

    findTestObject('{your test object}', [('{property}') : '{value of property}'])

    For example:

    • One dynamic property:

      findTestObject('Page_Login/txtUserName', ['id' : '48415648'])
    • Two dynamic properties:

      findTestObject('Page_Login/txtUserName', ['id' : '48415648', [('name') : 'controler14585']])
    • Using the variable for the dynamic property's value:


There are some cases in which you can identify an object's locator only when it's runtime. In other words, the exact locator of the intended object cannot be specified beforehand in test scripts. In the Cura Healthcare Center appointment web page, for instance, there are three options of the healthcare program, and the selected one is only known with passing data during execution.

How can we specify an option in a test script? By parameterizing its locator. You need to create only one Test Object, and you can determine which the exact object is with the passed data during execution.

Now for the exciting part: How do you determine which attribute(s) you have to adjust to parameterize this object's XPath? The answer to this question is mainly based on your knowledge of the web AUT. Knowing the pattern of how similar objects are grouped is the key. In this case, the index's value of label attribute is the value to parameterize for options on the current web screen.

Depending on your preferred selection method, including XPath (Smart XPath), Attributes or CSS, the captured object has a corresponding selected locator.

Below steps are how to apply parameterizing test objects in this case:

  • Capture the XPath locator of those 3 options and save them to the Object Repository in Katalon Studio.

    • Medicare: //*[@id=\"appointment\"]/div/div/form/div[3]/div/label[1]

    • Medicaid: //*[@id=\"appointment\"]/div/div/form/div[3]/div/label[2]

    • None: //*[@id=\"appointment\"]/div/div/form/div[3]/div/label[3]

      As can be seen in the captured XPath locators of those 3 options, they share this same pattern //*[@id=\"appointment\"]/div/div/form/div[3]/div/label; hence, in this case, the property variation is the label index.

  • In the test object view of the Medicare object, create an XPath property and enter the captured XPath locator as its value.

  • Create a variable as a place holder for the property change in the locator with this syntax: ${Variable_name}. In this case, it's the label index so we create [${index}].

    Modify this XPath value with that variable. There are two options for you: to parameterize the whole XPath value or merely a part of it.

    • ${index} = //*[@id=\"appointment\"]/div/div/form/div[3]/div/label[1].
    • ${index} = [1] => the XPath locator: //*[@id=\"appointment\"]/div/div/form/div[3]/div/label[${index}].

Above is a simple approach to leverage the 'Parameterized Test Object', a powerful feature. There are other approaches you can apply in your test scripts to reduce the efforts of maintaining many Test Objects at the same time.

Escaping, special characters

To use a special character like $ or \ as a regular one in any place that uses parameterized test objects, prepend it with a backslash: \ (the so-called escape character).

 	"productName": ${GlobalVariable.productName},
  	"unit": "\\bottle\",
  	"quantity": 50,
  	"discount": ${ if (productName == "wine") { return 30 } else { return 0}}
	"note": "Currency unit of ${GlobalVariable.productName} is \$."

  • Without \: note: Currency unit of ${GlobalVariable.productName} is $.

  • With \: note: Currency unit of wine is $.

Visual Object Recognition


  • Your Katalon Studio version must be 7.2.2 or later.
  • You need an active Katalon Studio Enterprise license.

Image-based object recognition in web testing is a fallback strategy that allows using an image representing an object to find that object during test execution. This feature proves helpful in case the web elements retain their appearances even though the underlying HTML structures have changed.

Given that a web element has the screenshot property.
When Katalon fails to find a web element by its selected locator.
Then Katalon tries using the associated screenshot to find the web element.

Using the image-based locating algorithm, Katalon Studio identifies the recognition area on the current screen based on the target screenshot. However, because typically a viewport of a browser is limited, what is present on the screen is also limited. Katalon attempts to scroll the page down and apply the image-based locating algorithm repeatedly. The final web element stored in the Matched Elements folder is the one that resembles the screenshot the most.


By default, image-based object recognition is disabled in Project Settings. Please go to Project > Settings > Execution and check Enable Image Recognition to turn on this fallback strategy.

The ingredients required for this feature include:

  • Target screenshots of a web element
  • The screenshot property of that element

There are two ways to create the required ingredients:

In Test Explorer, under the Screenshots folder, you can see the Matched Elements and Targets folders.

  • The Matched Elements folder contains objects that are located by Katalon Studio based on the target images.
  • The Targets folder is for containing the images that Katalon Studio uses for locating objects.

For a sample project, please download here

Factors Affecting Image Comparison

Screen Resolution: The screen resolutions of tests executing machines and screenshots capturing machines may affect the effectiveness of image comparison. We recommende capture screenshots and execute tests on the same machine for a better result.

Capture Tool: To capture screenshots associated with your preferred web elements, we recommend using the built-in screen-capturing feature in Web Recorder and Spy Tools. Particularly, on the expanded view after clicking Show Captured Objects, select the Add Screenshot button on the bottom right corner.