Pix-Diff

A lightweight protractor plugin for image comparison

##Installation

Install this module locally with the following command:

npm install pix-diff

Save to dependencies or dev-dependencies:

npm install --save pix-diff
npm install --save-dev pix-diff

##Usage

The package can be used directly in individual tests or via onPrepare in the Protractor configuration file.

Example:

exports.config = {
   // your config here ...

    onPrepare: function() {
        var PixDiff = require('pix-diff');
        browser.pixDiff = new PixDiff(
            {
                basePath: 'path/to/screenshots/',
                width: 1280,
                height: 1024
            }
        );
    },
}

PixDiff provides two comparison methods checkScreen and checkRegion along with Jasmine toMatchScreen and Mocha matchScreen matchers. Two helper methods saveScreen and saveRegion are provided for saving images. PixDiff can also work with Cucumber.js. There are no comparison methods provided for Cucumber.js because Cucumber.js doesn't have its own expect methods.

Jasmine Example:

describe("Example page", function() {

    beforeEach(function() {
        browser.get('http://www.example.com/');
    });

    it("should match the page", function () {
        expect(browser.pixDiff.checkScreen('examplePage')).toMatchScreen();
    });

    it("should not match the page", function () {
        element(By.buttonText('yes')).click();
        expect(browser.pixDiff.checkScreen('examplePage')).not.toMatchScreen();
    });

    it("should match the title", function () {
        expect(browser.pixDiff.checkRegion(element(By.id('title')), 'examplePageTitle')).toMatchScreen();
    });

    it("should match the title", function () {
        expect(browser.pixDiff.checkRegion(element(By.id('title')), 'examplePageTitle', {
            blockOut: [{x: 10, y: 132, width: 100, height: 50}]})).toMatchScreen();
    });
});

Cucumber Example:

var expect = require('chai').expect;

function CucumberSteps() {
    this.Given(/^I load the url$/, function () {
        return browser.get('http://www.example.com/');
    });

    this.Then(/^Pix\-Diff should match the page$/, function () {
        return browser.pixDiff.checkScreen('examplePage')
            .then(function (result) {
                return expect(result.differences).to.equal(0);
            });
    });

    this.Then(/^Pix\-Diff should not match the page$/, function () {
        element(By.buttonText('yes')).click();
        return browser.pixDiff.checkScreen('examplePage')
            .then(function (result) {
                return expect(result.differences).to.not.equal(0);
            });
    });

    this.Then(/^Pix\-Diff should match the title$/, function () {
        return browser.pixDiff.checkRegion(element(By.id('title')), 'examplePageTitle')
            .then(function (result) {
                return expect(result.differences).to.equal(0);
            });
    });

    this.Then(/^Pix\-Diff should match the title with blockout$/, function () {
        return browser.pixDiff.checkRegion(element(By.id('title')), 'examplePageTitle', {
            blockOut: [{x: 10, y: 132, width: 100, height: 50}]})
            .then(function (result) {
                return expect(result.differences).to.equal(0);
            });
    });
}

module.exports = CucumberSteps;

####PixDiff Parameters:

basePath Defines the path to the reference images that are to be compared.
baseline Toggles saving the screen when not found in reference images (default: false)
width Browser width (default: 1280)
height Browser height (default: 1024)
autoResize Auto (re)size the browser (default: true)
formatImageName Naming format for images (default: "{tag}-{browserName}-{width}x{height}")

####Function options:

blockOut Object or list of objects with coordinates that should be blocked before comparing. (default: none)
debug When set, then block-out regions will be shown on the output image. (default: false)

####Cropping Images can be cropped before they are compared by using the checkRegion function. The function will calculate the correct dimensions based upon the webdriver element selector (see example above).

####Block-Out Sometimes, it is necessary to block-out some specific areas in an image that should be ignored for comparisons. For example, this can be IDs or even time-labels that change with the time. Adding block-outs to images may decrease false positives and therefore stabilizes these comparisons (see example above).

####Different webdriver implementation There is a difference in the webdriver implementation in taking screenshots. Firefox and Internet Explorer (not tested Edge yet) take a screenshot of the complete page, even if the page needs to be scrolled. Chrome and Safari only take a screenshot of the visible portion of the page. Keep this in mind when comparing screenshots of screens with each other.

Conventions

There are directory and naming conventions that must be met.

Directory structure

path
└── to
    └── screenshots
        ├── diff
        │   └── examplePage-chrome-1280x1024.png
        ├── examplePage-chrome-800x600.png
        ├── examplePage-chrome-1280x1024.png
        ├── examplePageTitle-chrome-800x600.png
        └── examplePageTitle-chrome-1280x1024.png

The basePath directory must contain all the approved images. You may create subdirectories for better organisation, but the relative path should then be given in the test spec method. Failed comparisons generate a diff image under the diff folder.

Image naming

Images should obey the following default format:

{descriptionInCamelCase}-{browserName}-{browserWidth}x{browserHeight}.png

The naming convention can be customized by passing the parameter formatImageName with a format string like:

{browserName}_{tag}__{width}-{height}

The following variables can be passed to format the string

browserName The browser name property from the capabilities
dpr The device pixel ratio
name The name from capabilities
logName The logName from capabilities
deviceName The deviceName from capabilities

Images specified via name in the spec method will be selected according to the browsers current resolution. That is to say that multiple images can share the same name differentated by resolution.

##Documentation

todo

##Tests

Run all tests with the following command:

npm test

Run all tests by framework:

npm test -- jasmine/mocha/cucumber

###Dependencies

###Dev-Dependencies

##License

The MIT License

josephlaw/pix-diff

Pix-Diff

Conventions