Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

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 2 months ago
JSON representation

Differencify is a library for visual regression testing

Host: GitHub
URL: https://github.com/NimaSoroush/differencify
Owner: NimaSoroush
License: mit
Created: 2017-06-14T08:57:08.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2020-06-02T12:59:51.000Z (over 4 years ago)
Last Synced: 2024-10-17T22:29:48.882Z (about 2 months ago)
Topics: headless-chrome, jest, nodejs, puppeteer, visual-regression-testing, visual-testing
Language: JavaScript
Homepage:
Size: 6.61 MB
Stars: 634
Watchers: 14
Forks: 46
Open Issues: 27
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

awesome-puppeteer - differencify
awesome-regression-testing - Differencify - A library for visual regression testing using [Puppeteer](https://github.com/GoogleChrome/puppeteer). (Tools and frameworks)
awesome-regression-testing - Differencify - A library for visual regression testing using [Puppeteer](https://github.com/GoogleChrome/puppeteer). (Tools and frameworks)
awesome-puppeteer - differencify - Library for visual regression testing. (Packages)
awesome-list - differencify
awesome-jest - Differencify
awesome-puppeteer-zh - differencify - 用于视觉回归测试的库. (包 / 贡献)

README

        





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/)



## 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|

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

|||

## How it works



## 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



## 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