Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/NimaSoroush/differencify

Differencify is a library for visual regression testing
https://github.com/NimaSoroush/differencify

headless-chrome jest nodejs puppeteer visual-regression-testing visual-testing

Last synced: about 1 month ago
JSON representation

Differencify is a library for visual regression testing

Lists

README 

        
Differencify




Differencify 




Regression Testing suite!







[![CircleCI](https://circleci.com/gh/NimaSoroush/differencify/tree/master.svg?style=svg)](https://circleci.com/gh/NimaSoroush/differencify/tree/master)

[![npm version](https://badge.fury.io/js/differencify.svg)](https://badge.fury.io/js/differencify) [![Greenkeeper badge](https://badges.greenkeeper.io/NimaSoroush/differencify.svg)](https://greenkeeper.io/)

Mentioned in Awesome Jest



## About

Differencify is a library for visual regression testing via comparing your local changes with reference screenshots of your website. It is built on top of chrome headless using [Puppeteer](https://github.com/GoogleChrome/puppeteer).



|Reference|Local changes|

|---------|-------------|

|Differencify|Differencify|



## How it works

Differencify



## Installation

> *Note: Differencify uses async/await and targets Node v7.6.0 or greater*



Install the module:

```bash

npm install differencify

```

## Usage

```js

const Differencify = require('differencify');

const differencify = new Differencify(GlobalOptions);

```



Differencify matches [Puppeteer](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md)'s API completely. Look at [API.md](API.md) for more details.



### Validate your changes

```js

(async () => {

  const result = await differencify

    .init(TestOptions)

    .launch()

    .newPage()

    .setViewport({ width: 1600, height: 1200 })

    .goto('https://github.com/NimaSoroush/differencify')

    .waitFor(1000)

    .screenshot()

    .toMatchSnapshot()

    .result((result) => {

      console.log(result); // Prints true or false

    })

    .close()

    .end();



  // or unchained



  const target = differencify.init({ chain: false });

  await target.launch();

  const page = await target.newPage();

  await page.setViewport({ width: 1600, height: 1200 });

  await page.goto('https://github.com/NimaSoroush/differencify');

  await page.waitFor(1000);

  const image = await page.screenshot();

  const result = await target.toMatchSnapshot(image)

  await page.close();

  await target.close();



  console.log(result); // Prints true or false

})();

```

See more examples [here](API.md)



## Usage with JEST



Only need to wrap your steps into `it()` function

```js

const differencify = new Differencify();

describe('tests differencify', () => {

  it('validate github page appear correctly', async () => {

    await differencify

      .init()

      .launch()

      .newPage()

      .goto('https://github.com/NimaSoroush/differencify')

      .screenshot()

      .toMatchSnapshot()

      .close()

      .end();

  });

});

```

As you can see, you don't need to return `result` as `toMatchSnapshot` will automatically validate the result. See more jest examples [here](src/integration.tests/integration.test.js).



### Test PASS










### Test FAIL

















Same way as Jest [snapshots testing](http://facebook.github.io/jest/docs/en/snapshot-testing.html), to update the snapshots, run jest with `--updateSnapshot` or `-u` argument.



## Jest reporter



You can generate an index document of the saved images by using the differencify jest reporter.



```bash

$ npm i -D differencify-jest-reporter

```



Enable the reporter in your jest config:



```

module.exports = {

  reporters: [

    'default', // keep the default reporter

    [

      'differencify-jest-reporter',

      {

        debug: true,

        reportPath: 'differencify_reports', // relative to root of project

        reportTypes: {

          html: 'index.html',

          json: 'index.json',

        },

      },

    ],

  ],

};

```



Alternatively, enable the reporter with the cli:



```

jest --reporters default differencify-jest-reporter

```



### Jest reporter output

differencify-report



## Usage with other test frameworks

If you are using other test frameworks you can still validate your tests. Differencify will return `true` or `false` by the end of execution. This can be used to assert on. See this [example](https://github.com/NimaSoroush/differencify#validate-your-changes).



To Create/Update reference screenshots, simply set environment variable `update=true` and run the same code.



```

> update=true node test.js

```



## Mocking browser requests

Differencify uses [Mockeer](https://github.com/NimaSoroush/Mockeer) to run chrome headless browser in isolation. This will help with more consistent and stable results when it comes dealing with a website that has inconsistent downstream dependencies. (e.g. unique API call returns different results based on request time). More details [here](https://github.com/NimaSoroush/Mockeer)



To use this feature call `mockRequests` during your tests.



```js

(async () => {

  const result = await differencify

    .init(TestOptions)

    .launch()

    .newPage()

    .mockRequests()

    .goto('https://github.com/NimaSoroush/differencify')

    .screenshot()

    .toMatchSnapshot()

    .result((result) => {

      console.log(result);

    })

    .close()

    .end();



  // or unchained



  const target = differencify.init({ chain: false });

  await target.launch();

  const page = await target.newPage();

  await target.mockRequests();

  await page.goto('https://github.com/NimaSoroush/differencify');

  const image = await page.screenshot();

  const result = await target.toMatchSnapshot(image)

  await page.close();

  await target.close();



  console.log(result);

})();

```

More examples [here](src/integration.tests/integration.test.js)



## Debugging

It is possible to debug your tests execution by passing `debug:true` as global config in Differencify class. See full list of configs [below](https://github.com/NimaSoroush/differencify#globaloptions)



```js

const differencify = new Differencify({ debug: true });

```








## Visible mode

By default differencify runs chrome in headless mode. If you want to see the browser in non-headless mode set `headless:false` when launching the browser. See more details [here](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).



```js

const differencify = new Differencify();

(async () => {

  await differencify

    .init()

    .launch({ headless: false })

    .newPage()

    .goto('https://github.com/NimaSoroush/differencify')

    .screenshot()

    .toMatchSnapshot()

    .close()

    .end();

})();

```



## API



See [API.md](API.md) for a full list of API calls and examples.



## GlobalOptions



|Parameter|type|required|description|default|

|---------|----|--------|-----------|-------|

|`debug`|`boolean`|no|Enables console output|false|

|`imageSnapshotPath`|`string`|no|Stores reference screenshots in this directory|./differencify_reports|

|`saveDifferencifiedImage`|`boolean`|no|Save differencified image to test report path in case of mismatch|true|

|`saveCurrentImage`|`boolean`|no|Save the captured image from current test run to test report path|true|

|`mismatchThreshold`|`number`|no|Difference tolerance between reference/test image|0.001|



## TestOptions



|Parameter|type|required|description|default|

|---------|----|--------|-----------|-------|

|`testName`|`string`|no|Unique name for your test case|test|

|`chain`|`boolean`|no|Whether to chain differencify commands or not. See [API.md](API.md) for more details|true|



## Steps API



See [API.md](API.md) for a full list of API calls and examples.



## Interested on Docker image!



A [Docker base image](https://hub.docker.com/r/nimasoroush/differencify/) is available for local and CI usage based on this [Dockerfile](Docker/Dockerfile). To see an example look at this [Dockerfile](Dockerfile).



Usage:



```

FROM nimasoroush/differencify

RUN npm install differencify

...

```



## Links



See the [integration test example](./src/integration.tests) for working usages and CI integration with jest, and mock examples in [API.md](API.md)



Visit project [Gitter Chat](https://gitter.im/differencify/QA) for general Q/A around project



See [CONTRIBUTING.md](CONTRIBUTING.md) if you want to contribute.



Read [this article](https://medium.com/@nima.soroush.h/make-visual-regression-testing-easier-4a3dc7073737) that explain simple usage of this library



Article about how to use [Differencify in Docker](https://medium.com/@nima.soroush.h/using-differencify-in-docker-and-ci-99e3d1ec057c)



[Gist example](https://gist.github.com/NimaSoroush/28c3a5808af393610a33bd32d4c43911) with vanilla node