Welcome to the Ranorex Support Portal

Advanced image-based automation

As we’ve seen on the previous page, image-based testing is sometimes the solution to an issue. However, as with any other testing approach, you need to apply it correctly or it will fail.

Proper image-based testing can get challenging when the recorded and the actual image during test execution don’t match. This can be caused by simple things like a UI element being highlighted or icons changing during test execution. False positives, can also be an issue, when instead of the intended UI element, a similar-looking one is identified.

On this page, we’ll show you how to use advanced image-based settings to solve these two issues. At the end of the page, you’ll

In this chapter

Issue: Image not found

Sometimes minor changes, such as background or font color changes, can cause test failures. The challenge here is to ensure that UI elements are identified correctly despite these minor changes. Read on to find out how to do so.

Create the failing test

We’ll first create the test so it fails for the above reason. Then, we’ll fix it using the solution further below.

To create the failing test:

  1. Create a new recording module, start recording and turn on image-based recording.

  2. In the calendar view of the Ranorex Studio Demo Application, click a date and then stop recording.

  3. Check the resulting action in your actions table.

Run the test

Now let’s run the test and see when it’s successful and when it fails.

  1. Successful test run

  • When you run the test and the recorded calendar date is not selected in the demo app, the run succeeds.
  1. Failed test run

  • When you run the test and the recorded calendar date is selected in the demo app, the run fails.
  • This is because the date’s appearance changes slightly – clicking it gives it a gray background.
  • This change is enough for Ranorex Studio to not recognize the element using the default image-based properties.
  1. Error message in report


To solve this issue, we need to make changes to the image-based properties of the recorded action.

  1. Select the action and press F4 to open its properties.

  2. Click Image-based.

  1. Change the following properties:

  1. Preprocessing

  • The preprocessing properties let you apply various filters to your comparison image.
  • These filters can make image identification robust against changes in color, sharpness, brightness, and more.
  • For our example, select the filters Edges, EdgesSobel, and Grayscale.
  1. Similarity

  • Preprocessing filters can remove a good deal of image differences, but not all of them.
  • The similarity property lets you set an overall value of how similar the comparison image and the actual one need to be. The default is 1.0, i.e. 100 % or identical images.
  • For our example, reduce the similarity to 0.98.

Further reading

For more information on preprocessing filters and similarity, refer to

Ranorex Studio advanced > Image-based testing > ⇢ Image-based properties.

Rerun the test

Now rerun the test with the changed properties.

  1. Modified calendar view with date and gray background

  2. Thanks to the changed properties, the date is identified correctly and the test run is successful.

Issue: Wrong UI element found

When running an image-based test, it may sometimes happen that Ranorex Studio doesn’t find the recorded UI element, but a different, incorrect one that looks like the one recorded – a false positive. There are two ways to solve this issue. We’ll show you both. We also recommend combining them for best results.

Create the failing test

We’ll first create the test so it fails for the above reason. Then, we’ll fix it using the solution further below.

To create the failing test:

  1. Start a recording, enable image-based recording, and in the calendar view of the demo app, click a single-digit calendar date.

  2. Note the size of the frame around the action spot, where the mouse click will be performed. This is the image-find region where Ranorex Studio will look for the 7. Its size is part of the issue. We’ll fix this later as part of solution 1.

  3. Stop the recording and check the resulting action in the actions table.

Run the test

Now let’s run the test to see how it fails.

  1. June 7th is the date we initially recorded. Compared to the recording it now has a gray background and therefore cannot be identified by Ranorex Studio (see note above).

  2. In its search for a matching UI element, Ranorex Studio finds a different 7: the one in today’s date below the calendar

Solution #1

Remember the action spot we noted when creating the failing test? The image-find frame around it is too narrow here, i.e. doesn’t contain enough information to make it unique. This is why it catches other 7s as well. We need to extend it using the built-in image editor.

  1. Frame of the default action spot: Surrounds the element very closely. This is why it also catches similar elements.

  2. Extended action spot frame: A wider frame includes more information (even if it’s just whitespace here) and is therefore less likely to catch incorrect elements.

Change the frame in the image editor

To extend the frame, open the built-in ⇢ image editor:

  1. Select the action and click the breadcrumb button next to the referenced image.

  2. In the image editor toolbar, click the button Select image find region and drag an extended image-find region around the 7, including more whitespace than before (zoom in using the magnifying glass buttons if necessary).

  3. Click OK.

The test should now only find the correct 7 when you run it again. As mentioned above, this is one way to solve the issue. Read on to find out about the second way, which works even better if you combine it with the first.

Solution #2

The second way to fix this issue makes use of the image-ignore region feature. Here, this feature lets you define regions in the reference screenshot where Ranorex Studio won’t look for the image feature defined in the image-find region.

This way, we can simply ignore the part of the image that causes a false positive: the bottom part showing today’s date. To do so:

  1. In the ⇢ image editor, click the button Select image ignore region.

  2. Drag a frame around the section showing today’s date.

Now when you run the test, Ranorex Studio will ignore this section and not look for the action spot/the image-find region there, preventing a false positive.

Tips for image-based testing

Image-based testing can often require lots of experimentation and a good deal of experience. Follow these tips to make your life easier:


The images you want to identify should be as unique as possible, with no, or few, alternative matches. Also use image-ignore regions to exclude similar features and prevent false positives.


Make your comparison image as small as possible and as large as necessary. This may require some testing and experimenting.


A similarity of 1.0 will only find an identical image. This is often counterproductive. A similarity of 0.99 is usually a better idea. Sometimes, you may need to go lower, but you should rarely go beyond 0.95. At this similarity value, images can already differ significantly.

Preprocessing filters

Use preprocessing filters! They can make your test more robust against changes in color, detail, and brightness. For example, if you have a UI element with a unique shape that may change its color due to input, you can use grayscale and the Edge filters. This way, Ranorex Studio will still find it despite color changes.


Further reading

Similarity and preprocessing properties are explained in

Ranorex Studio advanced > Image-based testing > ⇢ Image-based properties.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved