match-screenshot

A simple Jest or Chai matcher to compare screenshots, using Applitools Eyes (other platforms will be supported as well, TBD)

Install & Configure

Install Package

npm install --save-dev match-screenshot

Setup eyes env variable

Add EYES_API_KEY environment variable, with your eyes key

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=<your key here>

• 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

"jest": {
  "setupTestFrameworkScriptFile": "match-screenshot/jest"
}

In case you have several custom matchers in your project / you need setupTestFrameworkScriptFile for other configurations, just use:

"jest": {
  "setupTestFrameworkScriptFile": "<rootDir>/setupTestFrameworkScriptFile.js"
}

Inside setupTestFrameworkScriptFile.js you can then:

require('match-screenshot/jest');

Chai

const {Assertion} = require('chai');
const toMatchScreenshot = require('match-screenshot/chai');
Assertion.addMethod('toMatchScreenshot', toMatchScreenshot);

Usage

Basic

Puppeteer example:

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:

  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 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 in case of a change in the screenshot actual viewport. Instead, it will fail the test.

  matchLevel <[enum]> (optional) Explicitly set match level

  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.

  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:

"jest": {
  "setupTestFrameworkScriptFile": "<rootDir>/setupTestFrameworkScriptFile.js"
},

Inside setupTestFrameworkScriptFile.js you can then:

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, 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:

 "files": [
   "./node_modules/match-screenshot/index.d.ts",
 ]