CodeceptJS pixelmatch helper

Integrates visual regression tests in → CodeceptJS using the → pixelmatch library. It works with all current CodeceptJS drivers: Playwright, Webdriver, Puppeteer, Appium, TestCafe.

Two screenshots are compared for differences, using a custom tolerance. When both images are equal enough, the test passes. When there are too many differences, the test fails.

What's special about this helper?

⭐️ It's fast and private!

Comparison is done in memory on your machine by comparing pixel details. The images are not rendered into a hidden canvas, no data is sent or loaded to any web service.

⭐️ It supports parallel execution

This helper can be used with NodeJS Workers to enable → parallel testing in CodeceptJS.

⭐️ Match against multiple base images

The flexible matching logic can recognize and match multiple base images for a single screenshot. This is very helpful if you have slight pixel variations between two devices or browsers: Provide one base image for every browser or device and finally prevent false failures!

⭐️ Free and open-source

This package is open-source and only relies on other (free) open-source packages!

⭐️ Multiple areas

You can define a bounding rectangle, as well as multiple ignore-areas to only compare pixels that are relevant for the test.

⭐️ Accurate calculation

When using a bounding rectangle or ignore-areas, the library accurately counts relevant pixels to calculate the total difference between both images. Every pixel that's outside the bounds or inside an ignored area is not included in that calculation.

⭐️ Complete documentation

Browse the GitHub Wiki to learn everything about this library. Also, the code is clean, short and contains inline comments to document the behavior.

Quick Guide

Install the package. → Details

npm install codeceptjs-pixelmatchhelper

Include the helper in your codecept.json config file. → Details

helpers: {
    PixelmatchHelper: {
        require: "codeceptjs-pixelmatchhelper"
    }
}

Use → checkVisualDifferences() to compare your images.

// Compares the two images to determine if they are identical.
//
// Actual image:    output/screenshot.png
// Expected image:  screenshots/base/screenshot.png
//
// Note: You need to create those two images before running the
// test. For example by using I.takeScreenshot("screenshot.png")
await I.checkVisualDifferences("screenshot.png");

Methods

• → I.checkVisualDifferences()
• → I.getVisualDifferences()
• → I.takeScreenshot()

Documentation, Samples, Notes

Browse the full package documentation inside the → GitHub wiki!

Found an issue? → Report it via GitHub!

Want to contribute? → Read our guide!

Thanks to

• This package is inspired by codeceptjs-resemblehelper.
• Thanks to everyone who contributes to pixelmatch, it's a great library to learn from
• The entire CodeceptJS community