Key takeaways
- Image comparison catches visual breakage that assertions never check for.
- Set a difference threshold, or font rendering will fail the suite on every machine.
- Run in a consistent environment; a different OS produces different pixels.
Jest is a complete and easy to set-up JavaScript testing solution which also provide a Snapshot Testing built-in mechanism.
With the Snapshot Testing functionality you can capture snapshots of React trees or other serializable values to simplify testing and to analyze how state changes over time.
In this article we are going to take advantage of Jest functionality to take screenshots of web pages using Puppeteer and compare generated screenshots with screenshots baseline in order to find regressions in the UI of any web page.
Jest is very easy to use with Puppeteer due to its Global Setup/Teardown and Async Test Environment APIs. More details on using Puppeteer to do visual regression testing can be found here.
With Puppeteer you can choose whether to launch Chromium in headless mode or not (tests run faster in headless mode, but it’s useful to be able to see the browser and run the test in slow motion for debugging purposes).
Prerequisites for Jest screenshot tests with Puppeteer
To take and compare screenshots of your web pages with Jest and Puppeteer, install three packages:
- Install Jest:
npm install --save-dev jest jest-cli
- Install Puppeteer:
npm install --save-dev puppeteer
- Install Jest Image Snapshot:
npm i --save-dev jest-image-snapshot
How to use Jest Image Snapshot with Puppeteer
- Extend Jest’s expect assertion mechanism:
Example: Jest screenshot test
const { toMatchImageSnapshot } = require('jest-image-snapshot');
expect.extend({ toMatchImageSnapshot });
Example: Jest screenshot test with Puppeteer and Jest Image Snapshot with Headless Chrome
The test file below is CommonJS (require), so it runs under Jest’s default setup. It was updated in November 2026 for Puppeteer 25, where the old ignoreHTTPSErrors launch option is called acceptInsecureCerts (pptr.dev, November 2026).
const puppeteer = require('puppeteer');
const { toMatchImageSnapshot } = require('jest-image-snapshot');
expect.extend({ toMatchImageSnapshot });
const browserConfig = {
acceptInsecureCerts: true,
headless: true,
args: ['--no-sandbox', '--disable-setuid-sandbox'],
};
// jest-image-snapshot custom configuration in order to save screenshots and compare them with the baseline
function setConfig(filename) {
return {
failureThreshold: 0.01,
failureThresholdType: 'percent',
customSnapshotsDir: `${__dirname}/../snapshots/`,
customSnapshotIdentifier: filename,
noColors: true,
};
}
describe('screenshot', () => {
let browser;
beforeAll(async () => {
// start Puppeteer with a custom configuration, see above the setup
browser = await puppeteer.launch(browserConfig);
});
it('dummy application page', async () => {
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 1400 });
await page.goto('http://localhost:3000');
const image = await page.screenshot({ fullPage: true });
expect(image).toMatchImageSnapshot(setConfig('image-name'));
}, 15000);
afterAll(async () => {
await browser.close();
});
});
Also, you can automate your visual regression testing by using our built-in visual regression testing service.
Frequently Asked Questions
What does image comparison add to a test suite?
It catches visual breakage nothing else checks. Assertions confirm elements exist; they say nothing about whether the page looks right.
Why does the suite fail on every machine?
Font rendering. Without a difference threshold, antialiasing alone is enough to fail comparisons, particularly across operating systems.
How do I keep it stable?
Run in a consistent environment, ideally the same container everywhere. A different OS produces different pixels for identical markup.