grunt-reg-viz

Compares pictures and shows their differences for visual regression test automation.

Table of Contents

• Installation
• Configuration
  • Task Options
  • Task Data
  • Loading
• Build
• Contributing
• Release History
• License

Installation

You need node >= 4, npm and grunt >= 0.4.5 installed and your project build managed by a Gruntfile with the necessary modules listed in package.json. If you haven't used Grunt before, be sure to check out the [Getting Started] guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

$ npm install grunt-reg-viz --save-dev

Configuration

Add the reg-viz entry with the task configuration to the options of the grunt.initConfig method:

grunt.initConfig({
  'reg-viz': {
    all: {
      expected: 'screenshots/expected',
      actual: 'screenshots/actual',
      different: 'screenshots/different',
      report: 'screenshots/report.html'
    }
  }
});

Default options support the most usual usage scenario:

'reg-viz': {
  options: {
    thresholdRate: null,
    thresholdPixel: null,
    concurrency: null,
    enableAntialiasing: false,
    additionalDetection: 'none',
    force: false
  },
  ...
}

Task Options

force

Type: Boolean Default value: false

If set to true, it suppresses failures, which result from different images, or from other errors. Instead of making the Grunt fail, the errors will be written only to the console.

thresholdRate

Type: Number Default value: null

Rate threshold for detecting change. When the difference ratio of the image is larger than the set rate detects the change.

thresholdPixel

Type: Number Default value: null

Pixel threshold for detecting change. When the difference pixel of the image is larger than the set pixel detects the change. This value takes precedence over thresholdRate.

concurrency

Type: Number Default value: CPU count

How many processes launches in parallel. If omitted, the count of installed CPUs.

enableAntialiasing

Type: Boolean Default value: false

Enable antialiasing. If omitted false.

additionalDetection

Type: String Default value: 'none'

Enable additional difference detection(highly experimental). Select "none" or "client" (default: "none").

Task Data

expected

Type: String Default value: './expected'

Path to the directory with expected images, which will be used as baseline in comparisons.

actual

Type: String Default value: './actual'

Path to the directory with actual images, which will be used as new ones to compare against.

different

Type: String Default value: './different'

Path to the directory with images showing the differences between the baseline and the new images.

report

Type: String Default value: './report.html'

Path to the HTML report file, which will be written after performing all comparisons. One more file will be written to the same directory; the JSON report file. It will share the same name as the HTML report file, just the extension ".json" wil be different.

Loading

Load the plugin in Gruntfile.js:

grunt.loadNpmTasks('grunt-reg-viz');

Build

Call the reg-viz task:

$ grunt reg-viz

or integrate it to your build sequence in Gruntfile.js:

grunt.registerTask('default', ['reg-viz', ...]);

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 2018-01-29 v0.0.1 Initial release

License

Copyright (c) 2018-2019 Ferdinand Prantl

Licensed under the MIT license.