{"id":13726007,"url":"https://github.com/macku/jest-puppe-shots","last_synced_at":"2026-02-24T02:05:00.128Z","repository":{"id":57280422,"uuid":"120227541","full_name":"macku/jest-puppe-shots","owner":"macku","description":"A Jest plugin for creating screenshots of React components with a little help of Puppeteer","archived":false,"fork":false,"pushed_at":"2020-01-05T21:40:37.000Z","size":209,"stargazers_count":84,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-09T05:26:13.536Z","etag":null,"topics":["chrome","css","enzyme","javascript","jest","jest-matchers","js","matcher","puppet","puppeteer","react","react-components","screenshot","snapshot","testing","unit-testing","unittest","visual-regression","visual-testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/macku.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-04T22:04:33.000Z","updated_at":"2025-06-01T23:43:18.000Z","dependencies_parsed_at":"2022-09-19T15:51:07.124Z","dependency_job_id":null,"html_url":"https://github.com/macku/jest-puppe-shots","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/macku/jest-puppe-shots","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macku%2Fjest-puppe-shots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macku%2Fjest-puppe-shots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macku%2Fjest-puppe-shots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macku%2Fjest-puppe-shots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macku","download_url":"https://codeload.github.com/macku/jest-puppe-shots/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macku%2Fjest-puppe-shots/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265550353,"owners_count":23786548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome","css","enzyme","javascript","jest","jest-matchers","js","matcher","puppet","puppeteer","react","react-components","screenshot","snapshot","testing","unit-testing","unittest","visual-regression","visual-testing"],"created_at":"2024-08-03T01:02:46.987Z","updated_at":"2026-02-24T02:04:55.089Z","avatar_url":"https://github.com/macku.png","language":"JavaScript","funding_links":[],"categories":["Packages","JavaScript"],"sub_categories":["Library extensions"],"readme":" jest-puppe-shots\n=================\n\n[![NPM version](https://badge.fury.io/js/jest-puppe-shots.svg)](https://www.npmjs.com/package/jest-puppe-shots)\n[![node](https://img.shields.io/node/v/jest-puppe-shots.svg)](https://www.npmjs.com/package/jest-puppe-shots)\n[![Build Status](https://travis-ci.org/macku/jest-puppe-shots.svg?branch=master)](https://travis-ci.org/macku/jest-puppe-shots)\n[![dependencies Status](https://david-dm.org/macku/jest-puppe-shots/status.svg?path=packages/jest-puppe-shots)](https://david-dm.org/macku/jest-puppe-shots?path=packages/jest-puppe-shots)\n[![devDependencies Status](https://david-dm.org/macku/jest-puppe-shots/dev-status.svg?path=packages/jest-puppe-shots)](https://david-dm.org/macku/jest-puppe-shots?path=packages/jest-puppe-shots\u0026type=dev)\n[![peerDependencies Status](https://david-dm.org/macku/jest-puppe-shots/peer-status.svg?path=packages/jest-puppe-shots)](https://david-dm.org/macku/jest-puppe-shots?path=packages/jest-puppe-shots\u0026type=peer)\n\nA [Jest](https://facebook.github.io/jest/) plugin for creating screenshots of [React](https://reactjs.org/) components with a little help of [Puppeteer](https://github.com/GoogleChrome/puppeteer)\n\nHow it works?\n=============\nA `jest-puppe-shots` is a **Jest** plugin that can help you create **Visual Regression** tests for your React components.\nIf you ever used [**Enzyme**](http://airbnb.io/enzyme/) or [**Snapshots**](https://facebook.github.io/jest/docs/en/snapshot-testing.html) you will love the `jest-puppe-shots`.\n\nThe Snapshot testing approach is really awesome but it has one downside: it cannot be used to make visual regression tests of your components.\nThanks to the [Puppeteer API](https://github.com/GoogleChrome/puppeteer) it's now possible to use **Chromium browser** in Jest and create **real screenshots** of your components!\n\nInstallation\n============\n\nYou can install the plugin using [**NPM**](https://www.npmjs.com):\n\n```bash\nnpm install jest-puppe-shots --save-dev\n```\n\nor by [**Yarn**](https://yarnpkg.com/):\n\n```bash\nyarn add jest-puppe-shots --dev\n```\n\n## Additional dependencies\nYou will have to install [`jest`](https://www.npmjs.com/package/jest) and [`react-dom`](https://www.npmjs.com/package/react-dom) if you don't have them yet:\n\n```bash\nnpm install jest react-dom\n```\n\n## Async/Await\nThe `jest-puppe-shots` API is written on top of the **Puppeteer** which means the currently supported version of **Node is 7.6+**.\nYou will also have to setup your **Babel** configuration to use the [Async/Await from ES7](https://developers.google.com/web/fundamentals/primers/async-functions).\n\n[Here you can find the tutorial](https://babeljs.io/docs/plugins/transform-async-to-generator/) how to setup your **Babel** settings to use it.\n\nJest Configuration\n==================\nBefore starting using the `jest-puppe-shots` you will need to change your Jest configuration file.\n\nOpen the `jest.config.json` file in your project and add additional entry:\n\n```json\n{\n  \"preset\": \"jest-puppe-shots-preset\"\n}\n```\n\nIf you are are using the `jest.config.js` file, then instead adjust your configuration like this:\n \n```js\nmodule.exports = {\n  // You config goes here\n\n  preset: 'jest-puppe-shots-preset'\n}\n```\n\nTaking Screenshots\n==================\n\nAfter setting up the configuration you can start writing your first integration test that will take screenshots.\nThe `jest-puppe-shots` it utilizing a couple of concepts and tools under the hood:\n\n - It's using [**Puppeteer**](https://github.com/GoogleChrome/puppeteer) to start Chromium browser in the headless mode\n - It takes a Screenshot of the component and stores it as a  **Snapshot** inside your repository under the `__image_snapshots__` directory.\n   If you are not familiar with the Jest Snapshots testing take a look at [Jest documentation page](https://facebook.github.io/jest/docs/en/snapshot-testing.html).\n - Uses the [`.toMatchImageSnapshot()`](https://www.npmjs.com/package/jest-image-snapshot) matcher to compare the base screenshot with the current version token during the test execution.\n\n# Writing First Integration Test\nTake a look at the example test code:\n\n```js\nconst { openNewPage } = require('jest-puppe-shots'); // 1. Require the jest-puppe-shots module into your test\nimport { openNewPage } from 'jest-puppe-shots'; // or use the ES module import if you like\n\nimport MyComponent from './MyComponent'; // 2. Import your React component\n\nlet page;\nbeforeEach(async () =\u003e {\n  page = await openNewPage(); // 3. Open new page for taking screenshots\n});\n\ntest('should render \u003cFoo\u003e component', async () =\u003e {\n  const component = await page.mount( // 4. Mount your component\n    \u003cMyComponent className=\"my-component\"\u003e\n      \u003cstrong\u003eHello World!\u003c/strong\u003e\n    \u003c/MyComponent\u003e\n  );\n\n  const screenshot = await page.takeScreenshot(component); // 5. Take a screenshot of your component\n\n  expect(screenshot).toMatchImageSnapshot(); // 6. Assert image snapshots and you're done!\n});\n```\n\nRunning this code for the first time by Jest, will produce a **Base Screenshot** and store it inside the repository at `your-test-location/__image_snapshots__` directory.\n\nTo update the **Base Screenshot** run Jest with `--updateSnapshot` or `-u` parameter.\n\n# Mounting additional CSS\n\nIf 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:\n\n```js\nimport path from 'path';\nimport { openNewPage } from 'jest-puppe-shots';\n\nlet page;\nbeforeEach(async () =\u003e {\n  page = await openNewPage();\n  await page.mountCssContext(path.resolve('../path/to/my-assets-dir', [\n    'css/reset.css',\n    'css/custom-styles.css'\n  ]))\n});\n```\n\nMounting the CSS directory might also help you with loading static content files like **images** or **font**.\n\n# Loading external CSS and JS files\n\nYou can also load and put an external CSS and JS files on your page:\n\n```js\nimport { openNewPage } from 'jest-puppe-shots';\n\nlet page;\nbeforeEach(async () =\u003e {\n  page = await openNewPage();\n  await page.loadExternalCss(\n    'https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css',\n    'https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css'\n  );\n\n  await page.loadExternalJs(\n    'https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js'\n  );\n});\n```\n\nBoth `loadExternalCss` and `loadExternalJs` function can accept multiple arguments so you can pass as URLs as you want.\n\n\nRoadmap\n=======\n\n - [ ] Transform the `*.less` and `*.sass` files into **CSS**  code when importing component modules by Jest \n - [ ] Better support for the [`Enzyme`](http://airbnb.io/enzyme) like API. You should be able to use ex. `get`, or `find` functions after\n   mounting component\n - [ ] Making screenshots of component parts by ex. selecting DOM nodes\n - [ ] More built-in renderers and support for custom renderers (pass a function)\n - [ ] Debugging: allow to start test without the headless mode and see what browser is doing\n\nFAQ\n===\n\n##  What version of Jest do I need to use?\nYou will have to install Jest 22+. The main reason of that is [version 22 introduced](https://github.com/facebook/jest/blob/master/CHANGELOG.md#features-9) the [`globalSetup` and `globalTeardown`](https://github.com/facebook/jest/pull/4716) options APIs.\n\n## What Node version is supported?\nSince 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](https://blog.readme.io/using-async-await-in-node-js-7-6-0/).\n\n## 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!\n\nNo 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:\n\n1. Edit your `package.json` file and provide additional entries for running screenshot tests:\n\n### Before\n```json\n{\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"jest --watch\"\n  }\n}\n```\n\n### After\n```json\n{\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"jest --watch\",\n    \"test:screenshots\": \"cross-env TAKE_SCREENSHOTS=true jest\",\n    \"test:watch:screenshots\": \"cross-env TAKE_SCREENSHOTS=true jest --watch\"\n  }\n}\n```\n\nWe are using the [`cross-env`](https://www.npmjs.com/package/cross-env) package in order to set environment variables for all the operating systems.\n\n2. Rename your `jest.config.json` to `jest.config.js` and adjust the source code to use `jest-puppe-shots` preset only when we need it.\n\n### Before\n```json\n{\n  \"preset\": \"jest-puppe-shots-preset\"\n}\n```\n\n### After\n```js\nlet config = {\n  /* Your Jest config goes here */\n};\n\nif (process.env.TAKE_SCREENSHOTS) {\n  config.preset = 'jest-puppe-shots-preset';\n}\n\nmodule.exports = config;\n```\n\n3. Right now you can run unit tests as usual by `npm run test` and you can launch integration tests by running `npm run test:screenshots`\n\n## I'm using `styled-components` to provide my CSS code. Is it supported?\nThat's fine. Good news for you is that `jest-puppe-shots` is supporting [`styled-components`](https://www.styled-components.com/).\nAll you need to do is to inform runner that you would like to use a custom renderer.\n\nEdit your Jest config file `jest.config.json` and add new `globals` entry to the configuration:\n\n```json\n{\n  \"globals\": {\n    \"__JEST_PUPPE_SHOTS_RENDERER__\": \"STYLED_COMPONENTS\"\n  }\n}\n```\n\nCurrently, there are two supported renderers:\n\n - `REACT_SERVER` (default) - It's using the [`react-dom/server`](https://www.npmjs.com/package/react-dom) package to render component as string\n - `STYLED_COMPONENTS` - It's using the `ServerStyleSheet` from [`styled-components`](https://www.npmjs.com/package/styled-components) to intercept the produced CSS styles and inject them on the page\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacku%2Fjest-puppe-shots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacku%2Fjest-puppe-shots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacku%2Fjest-puppe-shots/lists"}