grunt-vigo

A simple event based declarative visual regression testing tool using phantomJS 2 for NodeJS and Grunt

Getting Started

This plugin requires Grunt ~0.4.5

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-vigo --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-vigo');

The "vigo" task

Overview

In your project's Gruntfile, add a section named vigo to the data object passed into grunt.initConfig().

grunt.initConfig({
   vigo: {
      default_options: {
        options: {
          baseImages : "test/expected/",
          outputImages : "test/results/"
        },
        files:  {
          example_testSuite : ['test/example_testSuite.js']
        }
      }
    },
});

Options

options.baseImages

Type: String Default value: ./base/

A string with a directory path in which Vigo can store and reference the base expectation screenshots for the test suite. If an image is missing from this directory when the test suite is run Vigo will automatically copy the first screenshot into this direcotry and use it as it's base of reference.

options.outputImages

Type: String Default value: ./results/

A string with a directory path in which Vigo can store any images generated as part of the test run to compare with the base images.

files

Type: Object Default value: {}

An object that includes references to javascript testsuite files that should be run as part of the build.

Usage Examples

simple configuration example

In this example, the first code snippet is the grunt configuration, which sets the base image directory, the output image directory and also includes one test suit 'example_testSuite.js'

grunt.initConfig({
   vigo: {
      default_options: {
        options: {
          baseImages : "test/expected/",
          outputImages : "test/results/"
        },
        files:  {
          example_testSuite : ['test/example_testSuite.js']
        }
      }
    },
});

simple test suite example

{
    "vigo": [
        {
            "name": "main navigation",
            "url": "http://trisis.co.uk",
            "selector": "#mainContent",
            "viewport" : { "width": 1280, "height": 1024}
        },
        {
            "name": "whole page",
            "url": "http://trisis.co.uk",
            "viewport" : { "width": 1280, "height": 1024}
        }
    ]
}

vigo

Type: array Default value: []

An array of objects each object is a test to run in the test suite.

vigo.object.name

Type: String Default value: ``

Required. The name of the test, should be unique and describe the test, will also be used as the filename to record screenshots under. Spaces will be replaced with underscore.

vigo.object.url

Type: String Default value: ``

Required. The url for phantomjs to open to run the test.

vigo.object.selector

Type: String Default value: ``

Optional. If you want to capture only specific parts of your page, you can include a DOM selector here, it must work with document.querySelector(selector)

vigo.object.viewport

Type: String Default value: { width: 1280, height: 1024 }

Optional. If you want to capture the page with different screensizes (helpful for responsive testing) you can specify different resolutions

Contributing

Contact me via github with any pull requests.

Release History

0.1.4 = first fully functioning release.