Text Matching

Learn how to evaluate an element’s content rather than its visual appearance.

Text matching provides a secondary layer for comparing elements by examining their content rather than their appearance. Use text matching to control how strictly elements are evaluated. Doing so can help to avoid test failures and reduce test maintenance. Let’s say a test fails because of some superficial change, such as a new font or button color. With text matching, the test passes as long as the element’s content is the same.

When to Use Text Matching

Text matching is useful when the content of an image is important, but other attributes such as shape and size are not.

In this example, the button on the left was captured from the old UI. The button on the right is the updated version. Notice that, although the colors and shapes are different, the content is the same. Both buttons read, “Buy Now.”


A text-matching comparison.

If text matching is enabled, the test passes because the text “Buy Now” is detected, even though the buttons’ visual stylings are no longer an exact match.

Typically, QA teams are focused on testing functionality over visual appearance. Using text matching ensures tests don’t fail due to small, noncritical changes.

Not using text matching is a good practice when the goal is to test the visual appearance of an app. Let’s say you’re testing a UX-based refresh, and you want to confirm that all the elements have been updated. In this scenario, text matching won’t help.

Enabling and Disabling Text Matching

You can enable or disable text matching at the element level. In this example, text matching is enabled. When the test executes, Rainforest attempts a visual match. If that fails, it tries matching the content. If you don’t want that behavior, you can disable text matching.

If text matching is possible, the text value used for matching will be shown under Allow Text Matching. The value is shown regardless of text matching is enabled or not. The value will, however, only be searched if enabled.

Note: The value cannot be updated manually. It is automatically generated based on the information from the screen capture. A new screen capture may be done if needed by selecting Recapture element.


Enabling and Disabling text matching on an element.

No Valid Text Content Could Be Found

Text matching isn’t available when there isn’t enough text to evaluate. This situation often occurs with elements such as graphics and logos, where there isn’t any discernible text. In these cases, text matching cannot be used, and there’s no way to enable it.

Our detection logic continues to improve, covering a wide range of use cases. If you believe there’s an issue with text matching not working on an element, reach out to us at [email protected].


An element that can only be matched visually.

Too Much Text in an Element

To preserve accuracy, text matching works best with small chunks of text. In the example below, text matching cannot be used, and there’s no option to enable it. Instead of capturing a large area of the screen, try several smaller ones. If you can’t get text matching to work in a test step, reach out to our Support team for assistance.


An element containing too much text.


Multiple Lines of Centered Text

Text matching doesn’t work when an element contains two or more lines of text that are center aligned. We suggest you reduce the image capture to a single line at a time for evaluation.

Note: Even if text matching appears to be enabled, it’s not actually used.

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