Web Test Object

In Manual View

Create a test object

You can create a test object in two ways:

  • From the main menu, select File > New > Test Object; Or
  • Right-click on Object Repository > select New > Test Object

In the displayed New Test Object dialog, 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.

Moreover, you can capture objects using Web Spy or Recorder.

Create an object's locator

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. From 7.6, you can use Self-healing mechanism to utilize multiple locators of an object.

Katalon Studio supports the following selection methods: XPath, Attributes, CSS and Image. You can freely switch from one selection method to another. The detailed content of each selection method is saved automatically.

  • XPath/CSS: Enter a desired XPath locator in Selected Locator.

  • Image: Browse an image to compose an image locator for the object. Learn more

  • Attributes: Check on one or multiple Detect object by in the Object's Properties table to compose a Selected Locator of this method for the object.

    You can add multiple object properties to the Object's Properties table. Please note that object properties cannot share the same name in an object.

  1. In a Test Object's view, select Attributes as the default Selection Method.

  2. In the Object's Properties table, click Add.

  3. In the displayed Add property dialog, specify the required information:


  • Name: The object property's name. You can select one of the provided options (class, css, id, name, title, xpath) or enter a name manually.

  • Match condition: The condition is used for detecting the target object during execution.

  • Value: The value to complete a match condition.

    The new property is added to the properties list as configured above. You can also change 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.

In Script view

Script View allows defining Test Objects programmatically. The following example demonstrates how to define the Medicare option with the Attributes, XPath and CSS selection methods.

  1. Create a new object programmatically using the TestObject class:

    // Create a new object programmatically
    TestObject myNewObject = new TestObject('ObjectID')
  2. Add an object locator

  • With the Attributes selection method, add a property to an object using the 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 or CSS selection method: 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 Java 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 <TestObjectProperty> 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.

Validate a test object

You can add test objects to the Web Object Spy dialog to verify the detection in 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.

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.

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 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.

Enable Image-based object recognition

From 7.6 onwards

Image-based object recognition is enabled by default for web test execution in Project > Settings > Self-Healing > Web UI > Test Execution (See Self-healing Tests).

Before 7.6

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.

Capture screenshot and create screenshot property of an object

The ingredients required for the image-based object location to work include:

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

There are two ways to create the required ingredients:

In Tests 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.

Work 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).

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