Skip to main content

Web Image-based Testing

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.


  • An active Katalon Studio Enterprise license.

Enable Image-based object recognition

Image-based object recognition is enabled by default for web test execution in Project Settings > Self-Healing > WebUI.

Capture screenshots for object recognition

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

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

  1. From the main toolbar, select Spy Web.
  2. In the displayed Object Spy dialog, specify your URL. In this example, we use the following demo site:
  3. Click the Start button to start capturing.
    Katalon Studio will launch the web page automatically.
  4. Navigate to the web element you want to capture, right-click and select Capture Object.
  5. In the Captured Objects section, select the object, then click Add Screenshot button on the bottom right corner.
    The Spy utility verifies the image with the message "Screenshot taken!".

  6. Click Save to save the captured object and its screenshot.
    • 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

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 as the main locator for the object:
  1. Select the object in Object Repository.
  2. In the Object view, check Image as the selection method.
    Object view - image locator

    To add screenshots stored outside the project folder, provide the absolute path to the screenshot in the Path property when enabling the image locator.

    object screenshot absolute path

Katalon Studio will use the specified image to identify the object.

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: