Welcome to the Ranorex Support Portal

Image-based validation example

This chapter contains a simple tutorial for image-based validation. Before working with this example, make sure you’re familiar with the ⇢ basic concept of test validation.

In this chapter

Note Icon


The screencast “Basic image-based validation” walks you through the information found in this chapter.:

Watch the screencast now

Download the sample solution

To follow along with this tutorial, download the sample solution file from the link below.


Sample solution

Theme: Build a test
Time: 15 minutes

Install the sample solution:

  1. Unzip to any folder on your computer.

  2. Start Ranorex Studio and open the solution file ImagebasedValidation.rxsln

Note Icon


The sample solution is available for Ranorex versions 8.0 or higher. You must agree to the automatic solution upgrade for versions 8.2 and higher

Test definition

Before you start recording, let’s define the test.  It consists of 5 steps:

1. Start the demo application.

2. Click the Image-based automation tab.

3. Make the image visible.

4. Verify that the image is displayed.

5. Exit the Demo Application.

Recording preparation

  1. Create a desktop-test solution using the Solution Wizard and in step 2 of the setup, select the Demo Application as your AUT.

  1. Demo App selected as AUT and is launched automatically when you start recording.

  1. When the Solution Wizard has finished, click the Recording1 tab in the Ranorex Studio working environment.

Record the test: part one

Note Icon


Remember, if you’re not using whitelisting, all user interactions are captured once recording has started, even if they are not performed on the AUT.

  • Click Pause to pause recording. Click Continue to resume recording.
  • Click Stop to end recording.

Learn more about the Recorder control center in Ranorex Studio fundamentals > Ranorex Recorder > ⇢ Recorder control center & hotkeys.

Read about whitelisting in Ranorex Studio fundamentals > ⇢ Whitelisting.

  1. In the recording module view of Recording1, click RECORD. Ranorex Studio is minimized to the taskbar automatically.
    The Recorder control center shows that recording is active.

Starting the test recording
  1. The application under test comes into focus. Click the tab Image-based automation.

  2. To make the image appear, click the checkbox Show image.

Image-based validation

The goal of the example validation is to verify whether the image of the cat appears when the checkbox is selected. Since this requires us to validate an image, it’s an image-based validation.

Follow the steps below:

Activate image-based validation

  1. In the Recorder controls, activate the switch Image based recording.

  2. Click Validate. The Recorder pauses recording and switches to image-based validation mode.

Select validation element

  1. Select the UI element to validate:

  • Mouse over the image of the cat. A purple frame follows your mouse movement.
  • The purple frame indicates which element is currently selected for validation.
  • Once your selection matches the image, click it.

Confirm validation element

  1. To confirm the UI element, click Next.

  1. UI element location within GUI

  • The UI element tree represents the hierarchical GUI structure of the application.
  • You can click a different UI element to select it for validation, if desired.
  1. UI element states and attributes

  • All the attributes of the selected UI element appear in this area.
  1. Screenshot of validation UI element

  • Use the screenshot to quickly check whether you’ve selected the correct UI element.

Define validation attributes

  1. Define the image that will be used for the validation. For our example, simply leave everything as it is and click OK to confirm.

  1. The Image tab is selected in the validation dialog instead of the Attributes tab.

  2. Draw a rectangle to select a part of the image when using the “Contains” validation mode.

  3. Different image validation modes are available:

  • None: deactivates image validation.
  • Contains: determines whether the validation image is contained in the actual image found during the test.
  • Compare: determines whether the validation image and the actual image found during the test are the same.

Finish recording

Once you’ve finished the validation action, Ranorex automatically continues recording. The next step is to end the test recording.

  1. In the Recorder control center, click Stop to end the recording.


After recording stops, you are returned to Ranorex Studio. You’ll see the actions table with three recorded actions. Action #3 is the validation action.

Recording result of image-based validation example
  1. Validation type operator

  • This operator identifies the type of validation to perform.
  • There are nine different validation type operators.
Validation type operators for image-based validation.

Further reading

A detailed description of all validation match operators can be found in > Ranorex Studio fundamentals > Actions > ⇢ Action properties.

  1. The validation screenshot to which the actual image found during testing will be matched.

  2. The repository item linked to the action, i.e. the UI element on which the validation is performed.

Interpreting the validation

If written as a statement, the validation would read as follows:

If Screenshot1 is contained (ContainsImage) in the UI-element referenced by the repository item TheCat, THEN the validation returns the value ‘True‘.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved