Snapper is a JUnit extension that makes it easy to write visual regression tests with Selenium.
- Snapshot handling: Loads / stores the corresponding snapshot for each test
- Automatic screenshots: Takes screenshots automatically after each test
- Image comparison: Compares screenshots against the baseline and creates diff images to help identify errors
A basic test could be as simple as the following:
@SnapshotTest
public void basicTest() {
driver.get("https://www.google.com");
}
All you have to do is to add a field of type WebDriver
to any class in your test class hierarchy.
Snapper finds that field and takes a screenshot of the browser window controlled by that driver right after the test method finished.
After that, it will try to find the corresponding snapshot, which by default is located in the __snapshots__
directory next to your test files, named {class}_{method}.png
.
Snapper also supports custom snapshot names, simply pass a name of your choice to the SnapshotTest
annotation.
Sometimes it can be helpful to focus only on a specific web element or to ignore certain elements, especially when dealing with dynamic data (e.g. times).
To do so, you need to give the test method a SnapshotContext
parameter. This parameter can then be used to adjust different snapshot options.
A more advanced test that includes the above features might look something like this:
@SnapshotTest(name="customName")
public void advancedTest(SnapshotContext context) {
driver.get("https://www.google.com");
WebElement searchBar = driver.findElement(By.cssSelector(".RNNXgb"));
context.setTarget(searchBar);
WebElement searchIcon = driver.findElement(By.cssSelector(".QCzoEc > svg:nth-child(1)"));
context.addIgnoredElement(searchIcon);
}
In the above example, Snapper will only take a screenshot of the search bar and ignore the search icon.
In order to compare the test screenshots, Snapper must capture snapshots for each test case as a baseline.
By default, this is done whenever the corresponding snapshot file for a test is not found (UpdateMode.MISSING
).
To control which snapshots should be updated, there are three different update modes:
ALL
: Update snapshot for each executed test caseMISSING
: Create a new snapshot if there is no matching snapshot file, otherwise execute the testNONE
: Update no snapshots (i.e. fail if there is no matching snapshot file)
In case of a failed test, Snapper will compare the images and highlight the differences in a diff image.
By default, these diff images are located in the build/reports/snapper
directory.
There are two different diff modes:
Expected image | Diff mode pixel | Diff mode box |
---|---|---|
|
|
|
The above defaults can be changed via the snapper.properties
file or by accessing the SnapshotConfig
directly from your tests.
Property | Description | Default |
---|---|---|
snapshot-dir | Base directory of all snapshots | src/test/java/__snapshots__ |
output-dir | Directory for diff images | build/reports/snapper |
update-mode | Which snapshots to update: all, missing or none | missing |
tolerance | How far the actual color may deviate before it is considered an error, from [0-1] | 0 |
diff-mode | How to highlight differences in the diff image: pixel or box | box |
diff-color | Color used for difference highlighting | #FF0000 |
box-threshold | Minimum distance between two different boxes (only for diff-mode=box) | 10 |
box-stroke-width | Stroke width (only for diff-mode=box) | 3 |