Skip to main content

Web Image-based Testing in Katalon Studio

Katalon Studio provides an image locator method to associate Test Objects with images. With this method, you can perform image-based testing when elements of the web application under tests (AUT) retain their appearance even though the underlying structures have changed.

This guide shows you how to configure image-based object recognition, capture screenshots, and reduce the chance of failures in image-based testing.


  • Katalon Studio version 7.2.2 onwards.
  • An active Katalon Studio Enterprise license.

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. Go to Project > Settings > Execution and check Enable Image Recognition to turn on this fallback strategy.

Capture screenshots for object recognition

Using built-in tools

To produce images associated with captured Test objects, Katalon Studio includes the Add Screenshot button in both Web Recorder and Spy utility.

Here we use the Spy Web Utility to capture screenshots. Follow these steps:

  1. To open the Spy Web Utility, from the main toolbar, select Spy Web.


  2. In the displayed Object Spy dialog, specify the URL of your AUT and the web browser. Click on the Start button to start capturing.

    Object Spy dialog

  3. To capture an object, hover your mouse cursor over the web element and press the combination of \ keys. You can also right-click on the web element and select Capture.

    Capture object

  4. In the Captured Objects view, select the captured object and click the Add Screenshot button on the bottom right corner.

    Add screenshot

  5. After the Spy utility verifies the image with the message "Screenshot taken!", click on the Save button to save the captured object and its screenshot.

    Screenshot taken message

  • The image comparison algorithm in Katalon Studio compares a screenshot of an object with the displayed image of the corresponding web element on the active browser, pixel by pixel. Therefore, if you capture object images using other tools, you have to resize the images to the displayed sizes of the web elements on the active browser.

Add image locator to objects

From 7.6 onwards

After you capture a screenshot using the Web Recorder/Spy utility, Katalon Studio automatically adds an image locator to the associated object.

To use the image locator of an object:

  1. Select the object in the Object Repository.

    Select the object

  2. In the Object view, navigate to Selection Method and select the Image option.

    Select the image locator

Before 7.6

After you capture a screenshot using Web Recorder/Spy utility, Katalon Studio adds a property called screenshot to the associated Test object. This property contains the absolute path to the captured screenshot.

To enable the image locator of an object:

  1. Select the object in the Object Repository.

    Object view

  2. Select Attributes as the Selection Method.

  3. In the Object's Properties table, tick the screenshot property.

    Object's Properties table


To add screenshots captured using other tools, provide the absolute path to the screenshot in the Pathproperty when enabling the image locator.

object screenshot absolute path

Reduce image-based testing failures

Since reliable image-based testing depends on image comparison, you can reduce the chance of failures in two ways:

  • Screen Resolution: The screen resolutions of screenshot capturing devices and test executing devices can affect the accuracy of image comparison. We recommend capturing screenshots and executing tests on the same device for the best results.

  • Capture tool: We recommend using built-in capture tools in Web Recorder and Spy utility since they automatically resize the captured images.

See also: