How ignore works

Ignore during diffing

In principal, we create a diff for everything that differs and put that into the result file. Then it is up to the UI (GUI or CLI) to hide ignored differences. This is pretty much inline with how Git works – the diff is there, it just doesn't show up when ignored.

The advantages of this approach are as follows:

Ignore during matching

When creating a diff, recheck first matches every element of the Golden Master (expected) to every element of the current state (actual). Then the diff is created for those "matched" elements. This way, it doesn't matter if the order or placement changes.

But if there are irrelevant attributes that differ, they can confuse the matching algorithm. E.g. for many web pages, the ID attribute is a great identifier. But with some frameworks, the ID attribute is generated randomly. When additional, "real" changes come on top, this can sometimes confuse the matching algorithm. So in those cases, you want to ignore the ID attribute during matching. However, these attributes are usually ignored globally. So for those cases, we have a simple system property that can be set: de.retest.recheck.ignore.attributes contains a list of globally ignored attributes.

Ignore differences by using the recheck.ignore file

We currently support three different mechanisms to ignore elements, attributes or differences. It's also possible to ignore a specific attribute for an element. If a parent element is being ignored, all child elements will be ignored as well.

When recheck runs for the first time, an empty recheck.ignore file is created in the project folder. This file can be edited in three different ways:

Ignore by XPath (default)

During extraction of the golden master, we generate an XPath for each element in the website. A typical ignore with this methods looks like this:

matcher: xpath=HTML[1]/BODY[1]/DIV[3], attribute: outline
matcher: xpath=HTML[1]/BODY[1]/DIV[1]/DIV[1]/DIV[1]

For the first line, the div element found under HTML[1]/BODY[1]/DIV[3] the outline attribute is being ignored. The second line ignores the div element in HTML[1]/BODY[1]/DIV[1]/DIV[1]/DIV[1] and all child elements. If you want to ignore elements that appear and disappear, using XPath is also the recommended approach.

Ignore by ID or tag type

It is also possible to ignore an HTML element by its id attribute or its tag:

matcher: id=title, attribute: font
matcher: id=banner
matcher: type=a

Please note that it is also possible to ignore a specific attribute of an element as shown in the first example where the font attribute of all title element is ignored. As with the first mechanism, one can also completely ignore an element with all it's children, which is shown in the second example.

Ignore by retest ID

Also during creation of the golden master, we generate a stable id for all elements. We call this the retestID and it can also be used for ignoring:

matcher: retestid=div-b4f23, attribute: outline
matcher: retestid=a-d7728

There is nothing really special when compared to the previously shown mechanisms. All learnings still apply here.

Ignore attributes globally

You can also ignore attributes globally:

attribute=class

This will ignore the class attribute for all elements. You can also use Java's regex mechanism and ignore attributes by a given pattern:

matcher: type:input, attribute-regex: border-.*-color
attribute-regex= .*

E.g., this will ignore all border colors and all attributes of all elements respectively. The latter can be sensible if you want to use the "unbreakable" mechanism of recheck, but without actually checking for diffs...

Ignore pixel differences

Minor visual differences (e.g. between different browser types or browser versions) can make traditional, pixel-based approaches fail, which means more manual maintenance effort. In recheck, one can easily ignore pixel differences that are unimportant from a user's point of view:

pixel-diff=5

This would ignore every pixel difference (position- or size change) up to 5 pixels. You can either specify an integer or a float.

Ignore differences using the recheck.ignore.js file

We also added a mechanism to specify "ignore rules" in JavaScript, using the Oracle Nashorn JavaScript engine. This allows users to specify ignore rules very flexibly, by implementing either of the following methods:

matches(element) {}
matches(element, diff) {}

This is a special instance of the filter mechanism. If an element matches or an difference matches, it is ignored.

Using matches allows to specify whether a given difference should be ignored. This gives the flexibility to e.g. ignore all pixel differences smaller than 5px, to ignore the domain in URLs or to ignore switching between equivalent font-families, like "Times New Roman" and "Times Roman". Implementations of these examples can be found in recheck-web.