Skip to content

A simple Jest or Chai matcher to compare screenshots, using Applitools Eyes

License

Notifications You must be signed in to change notification settings

wix-incubator/match-screenshot

Repository files navigation

match-screenshot

Build Status npm

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",
 ]

About

A simple Jest or Chai matcher to compare screenshots, using Applitools Eyes

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published