Image-based validation example | Ranorex Studio User Guide
Help CenterUser GuideRanorex Studio fundamentals

Image-based validation example

In this chapter, we’ll demonstrate the concept of image-based validation based on a simple example. Before working with this example, make sure you’re familiar with the ⇢ basic concept of test validation.

In this chapter

    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

    Download sample file

    Install the sample solution:

    Unzip to any folder on your computer.

    Start Ranorex Studio and open the solution file ImagebasedValidation.rxsln

    tipp 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 we start recording our test, let’s define it. The test consists of 5 steps:

    1. Start the demo application.

    2. Click the Image-based automation tab.

    3. Make the image visible.

    Verifying an image existance in the demo application

    4. Verify that the image is displayed.

    5. Exit the Demo Application.

    Recording preparation

    Before recording any steps, choose your testing technology and add the application under test (AUT).

    Technology & test application selection

    Click RECORD in Ranorex Studio

    In the Recorder view of Ranorex Studio, click RECORD.
    Click Desktop, because the Ranorex Demo Application is a desktop application.

    Selecting the application under test

    Selecting the application under test (AUT)

    To add the application, click Add app…
    In the Explorer dialog that appears, browse to where you saved the Demo Application.
    Select the program file RxDemoApp.exe and click Open.

    Record the test: part one

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

    To start recording, click Record. Ranorex Studio is minimized to the taskbar automatically.
    The Recorder control center shows that recording is active.

    Starting the test recording

    Starting the test recording

    The application under test comes into focus. Click the tab Image-based automation.
    To make the image appear, click the checkbox Show image.

    Displaying demo application image

    Image-based validation

    The purpose of the test validation in this example is to verify, if the turned-on image in the demo application is displayed and if this image corresponds to the reference image during the specification of the test validation.

    Due to the fact, that the validation element is an image the validation is called image-based validation!

    Image-based validation

    The purpose of the test validation in this example is to verify whether the image of the cat is displayed when the checkbox is selected.

    Since this requires us to validate an image, we’re carrying out an image-based validation.

    Let’s go through the steps:

    Activate image-based validation

    In the Recorder controls, check the box Image based to activate image-based automation.
    Click Validate.
    The Recorder pauses recording and switches to image-based validation mode.

    Activate image-based validation

    Select validation element

    Select validation element

    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.
    Selecting image-based validation element

    Confirm validation element

    To confirm the UI element, click Next.

    Confirm validation element

    UI element location within GUI

    • Here you can correct the previous choice by selecting any other UI element for validation.
    • The UI element tree represents the hierarchical GUI structure of the application.

    UI element states and attributes

    • Here, all the attributes of the selected UI element are displayed.

    Screenshot of validation UI element

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

    Define validation attributes

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

    Specification of image-based validation

    The Image tab is selected in the validation dialog instead of the Attributes tab.
    You can draw a rectangle to select which part of the image you want to use for validation.
    Different image validation modes are available:

    • None = deactivates image validation.
    • Contains = compares if the the validation image is contained in the actual image found during the test.
    • Compare = compares if the validation image and the actual image found during the test are the same.

    Record the test: part two

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

    Finalize & end recording
    Click the Exit button of the Demo Application.
    In the Recorder control center, click Stop to end the recording.


    Once you’ve stopped recording, you’ll be returned to Ranorex Studio. You’ll see the actions table with  5 recorded actions. Action #4 is the validation action.

    Recording result of image-based validation example

    Recording result of image-based validation example

    Validation type operator

    • This operator defines what type of validation will be carried out.
    • There are 9 different validation type operators.
    Validation match operators for image-based validation

    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.

    The validation screenshot against which the actual image found during testing will be matched.
    The repository item the action is linked to, i.e. the UI element on which the validation is performed.

    Interpreting the validation

    Spelled out, the validation reads as follows:

    Image-based validation interpretation

    Image-based validation interpretation