Image-based testing

In GUI test automation, there are different approaches to identifying UI elements.  Ranorex Studio’s main approach is based on object-oriented testing. This means it is able to directly ⇢ identify and interact with individual UI elements based on the technology they were implemented with.

However, in some cases, this approach may not work that well. For this reason, Ranorex Studio also supports image-based testing. This approach identifies and interacts with UI elements based on the recognition of pixels in an image.

In this chapter, you’ll find out when and how to use image-based testing in Ranorex Studio and how to overcome the challenges of this testing approach.

In this chapter

    Enable image-based recording

    The best way to use image-based testing in Ranorex Studio is through the Recorder. There, you can enable and disable image-based testing while you’re recording. This way, you can combine object-oriented and image-based approaches in a single recording if required.

    tipp icon


    If you want to use image-based testing, ensure the setting Asynchronous dispatching of mouse and keyboard events is enabled. In most cases, disabling it will cause errors in image-based testing. Enable the setting in Ranorex Studio under Settings > Advanced.

    To enable image-based recording:

    While recording, click the Image-based recording switch.
    Image-based recording is now active.
    Turning image-based automation on/off

    Alternatively, you can also use hotkeys:

    While recording, enable hotkeys.

    Press I to enable image-based recording.

    Activation of image-based automation through Recorder hotkeys

    Why image-based testing?

    Image-based testing is useful when the object-oriented approach can’t produce satisfactory results. Here we’ll show you an example where this is the case.

    Example preparation

    We’ll use the Ranorex Studio Demo Application for our example and we’ll record our actions in the Recorder.

    Start the demo application and click the Image-based automation tab.
    In Ranorex Studio, create a new desktop solution with the solution wizard and open Recording1 in this solution.
    In the recording module view of Recording1, click RECORD.

    Example for image-based automation

    Object-oriented recording

    We’ll now record mouse clicks on three consecutive dates in the calendar view of the demo application using the default object-oriented approach.

    Ensure image-based recording is disabled.
    Click the three dates 24, 25, and 26 in the calendar and stop the recording.
    The action table displays the three corresponding actions.

    Tracking & recording calendar dates in text-based automation

    Run the test

    When you run the test, you’ll see that

    • the recorded calendar dates are identified correctly.
    • each click action in the report corresponds to the correct date in the calendar.
    Successful test run of calendar dates recording

    Change of test conditions

    So far, the object-oriented approach has worked flawlessly. Now, assume that you run the test a couple of months from its creation. This means that the calendar view will have changed to a different month. Let’s see how our test performs in this case.

    In the calendar in the demo application, switch to any month where the recorded dates 24, 25, and 26 are at a different position in the calendar.

    Change in test conditions

    Run the test again and see what happens.

    Test result with changed test conditions
    • The test runs without failure and reports a success.
    • However, this is a false positive. The test identifies the wrong dates (21, 22, and 23 in our case instead of 24, 25, and 26).
    tipp icon


    This is because sometimes, Ranorex Studio can’t identify an individual UI element (e.g. dates within certain calendar views). Instead, it then uses absolute and relative positions rather than the actual object, which leads to the above issue.


    On the next page, we’ll show you how you can overcome this challenge with image-based testing.

    Download the sample solution

    You can download the completed solution with all the above steps carried out below.

    Sample solution

    Theme: Image-based testing
    Time: < 30 minutes

    Download sample file

    Install the sample solution:

    Unzip to any folder on your computer.
    Start Ranorex Studio and open the solution file ImagebasedAutomation.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.