Switching From Legacy Image Matching to New Matching Modes

Learn about how to migrate from legacy matching modes to our new matching models in the visual editor.


We have enhanced the way our virtual machines match elements to see more like humans and better tolerate small updates. For every screenshot in your tests, we will now give you a choice of two matching modes:

  1. Intelligent (the new default)
  2. Strict



Any screenshot currently using a legacy matching mode or legacy with text fallback will remain unchanged unless you update the matching mode for that screenshot within its test.

Intelligent matching mode is designed to evaluate elements on the screen like a human would. This means it’ll successfully match screenshots and elements while ignoring visual differences that most people wouldn’t notice, including:

  • minor differences in color, font size, spacing, or rendering,
  • appearance of text and mouse cursors over elements, and
  • unimportant differences in white space (i.e., padding and margins).

Strict mode will only pass exact matches between screenshots and elements. Any failure to find an exact match between a screenshot and an element on the screen will result in a FAIL.

Why We’ve Built Intelligent Matching Mode

We found that some of our customers’ runs would fail because the legacy matching mode couldn’t ignore small visual differences between screenshots and elements. For example, here’s what would happen with a slight difference in underline thickness between two images:

IF you’ve captured this elementAND your website or app shows this elementAND you’ve selected this Matching ModeTHEN the result would be thisBUT you expect

Here are some situations to consider:

  • If your tests fail due to slight visual differences, switching to Intelligent matching mode is likely to help.
  • If your element is currently matched using the legacy with text fallback mode, switching to Intelligent matching mode will be the more strict option.
  • Intelligent matching mode looks at text content, but requires text content be the same and text appearance to be somewhat similar to pass. So if, for example, the font size changes by a very noticeable amount, the action might fail to find a match.

How to Switch Matching Modes

  1. Navigate to an existing test
  2. On the left sidebar, click on the “element” part of an action
  3. Under “Matching Mode”, click “Change”
  4. Under “Select Matching Mode”, click the desired matching mode
  5. Click the back arrow (←) to confirm

Any new elements created will automatically use the new Intelligent matching mode.

When to Keep Using Legacy Matching Modes

You might want to keep using the legacy matching mode if you want to detect minor visual changes. For instance:

  1. You want to make sure that some elements are laid out exactly as you intended them to be.
  2. Finding a button should fail if the padding changes slightly.

In contrast, you might want to use Legacy with text fallback when both of these apply:

  • you don’t really care about the appearance, only that specific text is visible on the page,
  • you’re confident the same text will not appear on the same page multiple times (e.g. in the window title bar and the main page itself).

How Legacy Matching Modes Work

When you add an action in the Visual Editor, Rainforest QA asks you to click and drag over the virtual machine to capture an interface element. After capturing an element you select a matching mode. In previous versions, Rainforest offered two matching modes: purely pixel-based or pixel-based with a text matching fallback (chosen by toggling "Allow Text Matching"). Whenever you run a test, Rainforest QA will try to match the element you’ve captured against the element that shows up in your app. Based on the matching mode you've selected, and the closeness of the two screenshots, your action will result in a PASS or FAIL*. For instance:

IF you’ve captured this elementAND your website or app shows this elementAND you’ve selected this Matching ModeTHEN the result would be
Legacy with text fallbackPASS

If you have any questions, reach out to us at [email protected].