How it works?
The Snapshot testing approach is really awesome but it has one downside: it cannot be used to make visual regression tests of your components. Thanks to the Puppeteer API it's now possible to use Chromium browser in Jest and create real screenshots of your components!
You can install the plugin using NPM:
npm install jest-puppe-shots --save-dev
or by Yarn:
yarn add jest-puppe-shots --dev
npm install jest react-dom
jest-puppe-shots API is written on top of the Puppeteer which means the currently supported version of Node is 7.6+.
You will also have to setup your Babel configuration to use the Async/Await from ES7.
Here you can find the tutorial how to setup your Babel settings to use it.
Before starting using the
jest-puppe-shots you will need to change your Jest configuration file.
jest.config.json file in your project and add additional entry:
If you are are using the
jest.config.js file, then instead adjust your configuration like this:
moduleexports =// You config goes herepreset: 'jest-puppe-shots-preset'
After setting up the configuration you can start writing your first integration test that will take screenshots.
jest-puppe-shots it utilizing a couple of concepts and tools under the hood:
- It's using Puppeteer to start Chromium browser in the headless mode
- It takes a Screenshot of the component and stores it as a Snapshot inside your repository under the
__image_snapshots__directory. If you are not familiar with the Jest Snapshots testing take a look at Jest documentation page.
- Uses the
.toMatchImageSnapshot()matcher to compare the base screenshot with the current version token during the test execution.
Writing First Integration Test
Take a look at the example test code:
const openNewPage = ; // 1. Require the jest-puppe-shots module into your test; // or use the ES module import if you like; // 2. Import your React componentlet page;;;
Running this code for the first time by Jest, will produce a Base Screenshot and store it inside the repository at
To update the Base Screenshot run Jest with
Mounting additional CSS
If your components are based on additional CSS code from your code base like ex.
reset.css you might like to mount the static content on the page:
Mounting the CSS directory might also help you with loading static content files like images or font.
Loading external CSS and JS files
You can also load and put an external CSS and JS files on your page:
loadExternalJs function can accept multiple arguments so you can pass as URLs as you want.
- Transform the
*.sassfiles into CSS code when importing component modules by Jest
- Better support for the
Eznymelike API. You should be able to use ex.
findfunctions after mounting component
- Making screenshots of component parts by ex. selecting DOM nodes
- More built-in renderers and support for custom renderers (pass a function)
- Debugging: allow to start test without the headless mode and see what browser is doing
What version of Jest do I need to use?
What Node version is supported?
Since both Puppeteer and
jest-puppe-shots are heavily depending on the
async/await API you will have to use Node 7.6+ that enabled the support for it.
I don't want to run Puppeteer each time I'm running my tests. It takes ages to start Jest and it's getting slow!
No problem! You don't need to launch Puppeteer for you regular Unit Tests. You will just have to adjust your environment a little bit. Take a look at the example:
- Edit your
package.jsonfile and provide additional entries for running screenshot tests:
We are using the
cross-env package in order to set environment variables for all the operating systems.
- Rename your
jest.config.jsand adjust the source code to use
jest-puppe-shotspreset only when we need it.
let config =/* Your Jest config goes here */;if processenvTAKE_SCREENSHOTSconfigpreset = 'jest-puppe-shots-preset';moduleexports = config;
- Right now you can run unit tests as usual by
npm run testand you can launch integration tests by running
npm run test:screenshots
styled-components to provide my CSS code. Is it supported?
That's fine. Good news for you is that
jest-puppe-shots is supporting
All you need to do is to inform runner that you would like to use a custom renderer.
Edit your Jest config file
jest.config.json and add new
globals entry to the configuration:
Currently, there are two supported renderers: