Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wix-incubator/match-screenshot
A simple Jest or Chai matcher to compare screenshots, using Applitools Eyes
https://github.com/wix-incubator/match-screenshot
applitools chai eyes image-comparison jest matchers puppeteer
Last synced: 2 months ago
JSON representation
A simple Jest or Chai matcher to compare screenshots, using Applitools Eyes
- Host: GitHub
- URL: https://github.com/wix-incubator/match-screenshot
- Owner: wix-incubator
- License: mit
- Created: 2018-05-06T09:06:33.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-19T11:44:37.000Z (almost 2 years ago)
- Last Synced: 2024-11-14T13:44:41.784Z (3 months ago)
- Topics: applitools, chai, eyes, image-comparison, jest, matchers, puppeteer
- Language: JavaScript
- Homepage:
- Size: 808 KB
- Stars: 14
- Watchers: 7
- Forks: 7
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# match-screenshot
[](https://travis-ci.org/wix-incubator/match-screenshot)
[](https://www.npmjs.com/package/match-screenshot)
A simple Jest or Chai matcher to compare screenshots, using [Applitools Eyes](https://applitools.com/) (other platforms will be supported as well, TBD)
## Install & Configure
### Install Package
```bash
npm install --save-dev match-screenshot
```
### Setup eyes env variable
Add `EYES_API_KEY` environment variable, with your eyes [key](https://applitools.com/docs/topics/overview/obtain-api-key.html)
#### CI
##### Travis
go to your build's `options -> settings -> Environment Variables` and add `EYES_API_KEY` + your key
#### locally
add an `.env` file, with:
```
EYES_API_KEY=
```
- this step is not mandatory - you should use it if you want to use eyes when running locally.
- ⚠️ **you should put your `.env` file in git ignore!!!**
### Set the matcher
##### Jest
```js
"jest": {
"setupTestFrameworkScriptFile": "match-screenshot/jest"
}
```
In case you have several custom matchers in your project / you need `setupTestFrameworkScriptFile` for other configurations, just use:
```js
"jest": {
"setupTestFrameworkScriptFile": "/setupTestFrameworkScriptFile.js"
}
```
Inside `setupTestFrameworkScriptFile.js` you can then:
```js
require('match-screenshot/jest');
```
##### Chai
```js
const {Assertion} = require('chai');
const toMatchScreenshot = require('match-screenshot/chai');
Assertion.addMethod('toMatchScreenshot', toMatchScreenshot);
```
## Usage
### Basic
Puppeteer example:
```js
it('my test', async () {
await page.goto('http://www.wix.com');
const screenshot = await page.screenshot();
await expect(screenshot).toMatchScreenshot({key: 'my test'});
});
```
### Creating a new baseline
When you change production code implementation, Eyes will break, and you will have to go to its management Dashboard and approve the change. In order to avoid that, you can assign a new version and create a new baseline:
```js
it('my test', async () {
await page.goto('http://www.wix.com');
const screenshot = await page.screenshot();
await expect(screenshot).toMatchScreenshot({key: 'my test', version: 'v1.0.1'});
});
```
## API
#### toMatchScreenshot([options])
- options
`key` <[string]> A unique key for your screenshot. This key will be used in Applittols Eyes.
`version` <[string]> (optional) Used to create a new baseline. See [Creating a new baseline](https://github.com/wix-incubator/match-screenshot#creating-a-new-baseline) for more details. Default value: 'v1.0.0'.
`viewport` <[string]> (optional) Explicitly pass viewport argument to Applitools api. This will prevent Applitools from [creating a new baseline](https://help.applitools.com/hc/en-us/articles/360007188691-What-is-a-baseline-and-how-is-a-baseline-created-) in case of a change in the screenshot actual viewport. Instead, it will fail the test.
`matchLevel` <[enum]> (optional) Explicitly set [match level](https://help.applitools.com/hc/en-us/articles/360007188591-Match-Levels)
`autoSaveNewTest` <[boolean]> (optional) If you set it to false, every time that eyes will detect a new test(different viewport size, first run) it will fail the test and the baseline will need to be approved in Eyes. Default value: true.
```js
const MatchLevel = require('match-screenshot/matchLevel')
...
await expect(screenshot).toMatchScreenshot({key: 'my test', matchLevel: MatchLevel.Explicit});
```
#### jestWithConfig([options])
Configure your matcher with global options.
Set the matcher:
```js
"jest": {
"setupTestFrameworkScriptFile": "/setupTestFrameworkScriptFile.js"
},
```
Inside `setupTestFrameworkScriptFile.js` you can then:
```js
require('match-screenshot/jestWithConfig')(options);
```
- options
`appName` <[string]> Application name. Will be used inside Applitools as part of test title
## How does it work
Everytime you use `toMatchScreenshot` matcher, a screenshot will be sent to [Applitools Eyes](https://applitools.com/), which will compare the new screenshot with the baseline. The test will fail if they are not equal.
## Typescript defintions
If you are using typescript and are missing type defintions for `toMatchScreenshot`, you can add the following line to your tsconfig:
```js
"files": [
"./node_modules/match-screenshot/index.d.ts",
]
```