Ranorex Studio Image-based automation
Help CenterUser GuideRanorex Studio advanced

Image-based automation

Automated software testing usually is based upon the recognition of user-interface elements (UI-elements). Many of them may be identified based on text. Alternatively, the recognition of pixel images instead of text is necessary for test automation. Here – image-based automation is a well-proven method to identify, detect and apply UI-elements. Everything needed to make use of this method is introduced and explained herein.

tipp icon


The setting Asynchronous dispatching of mouse and keyboard events should be enabled when performing image-based automation. In most cases, disabling it will cause errors in image-based automation. Enable the setting in Ranorex Studio under Settings > Advanced.

In this chapter

    Sample solution

    The herein introduced concepts are put into a sample solution which can be downloaded. You are invited to experiment with the sample solution and improve your knowledge.

    Training! What do I do?

    Theme: Image-based automation
    Time: Less than 30 min

    Download sample file


    Unzip the project directory 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 need to agree to the automatic solution upgrade for versions 8.2 and higher.

    Turning image-based automation on/off

    Image-based automation is turned on and off in the Recorder control center any time during recording.

    Turning image-based automation on/off

    Turning image-based automation on/off

    Image-based switch in Ranorex Recorder (turned off)
    Image-based automation turned on

    Activation of image-based automation through Recorder hotkeys

    Activation of image-based automation through Recorder hotkeys

    Switch on hotkeys

    Press I to activate image-based recording.

    Why image-based automation?

    The reasons for using image-based automation within automated testing of GUI software might not be obvious. This section is to show you at least one reason where text-based automation fails, and image-based automation is the solution.

    Example preparation

    We’ll use the Ranorex Studio Demo Application for our example. To record our actions, we’ll use the instant recording functionality of the Ranorex Recorder.

    Example for image-based automation

    Example for image-based automation

    Start the demo application and select Image-based automation as working environment.
    In Ranorex Studio, create a new solution without the Solution Wizard and open Recording1 in this solution.

    In the recording module view of Recording1, click RECORD.

    Text-based recording

    Track & record three (3) consecutive dates in the calendar view of the demo application in the default text-based automation mode and see the result.

    Tracking & recording calendar dates in text-based automation

    Tracking & recording calendar dates in text-based automation

    Verify that default text-based automation is turned on (i.e. image-based automation is not selected)
    Recording (clicking) the three dates ’24’, ’25’ & ’26’ of the calendar leads to …
    … an action table with three corresponding action items representing the calendar mouse clicks

    Test recording result

    See the result of the successful test recording when the test run is started:

    • 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

    Successful test run of calendar dates recording

    Change of test conditions

    Assume that the test conditions change – and – that the calendar view changes to a different month due to time progress between recording and replaying the test.

    Change in test conditions

    Change in test conditions

    Change calendar view from January 2018 to February 2018 with an obviously different calendar view. The recorded dates ’24’, ’25’ & ’26’ are now at a different position within the calendar.

    Watch the result of the test run with the previous recorded calendar dates:

    Test result with changed test conditions

    Test result with changed test conditions

    Result interpretation

    • The test runs without failure and reports a success (see test report)
    • But – the result is wrong, as dates at the originally tracked positions in the calendar are identified during the test run, and not, the correct dates at their changed position!
    tipp icon


    Sometimes, Ranorex is not able to identify a UI-element for an individual click point (as of dates within a calendar). Then, text-based automation stores absolute and relative positions rather than graphical UI-elements which leads to the herein described problem.


    In the next chapter, we show you how image-based automation overcomes this challenge.