Protractor-snapshot

Protractor HTML snapshot and screenshot utility.

Description

Create HTML snapshots and screenshots from anywhere in your end-to-end tests.

Includes a cycle function that can create snapshots and screenshots for every resolution you support. Very convenient for validating your responsive design.

In conjunction with buenos-uncss you can find unused CSS selectors by evaluating the HTML snapshots.

Works with both Jasmine v1 and v2, but note that v2 needs a small addition to your protractor config! See the onPrepare function in the configuration section.

Installing

$ npm install --save-dev protractor-snapshot

Usage

# some.spec.js
 
var $snapshot = require('protractor-snapshot');
 
describe('The snapshot suite', function () {
 
    it('Should create snapshots from my spec', function () {
 
        // create screenshot
        $snapshot.image();
 
        // create html snapshot
        $snapshot.source();
 
    });
 
    it('Should create a snapshot for each resolution I support', function () {
 
        // iterate over configured resolutions
        $snapshot.cycle(function (resolution) {
 
            // call these functions for each resolution
            $snapshot.image();
            $snapshot.source();
 
        });
 
    });
 
});
 

Configuration

 
// protractor.conf.js
 
module.exports.config = {
    protractorSnapshotOpts: {
 
        // base format for created files
        // replaces %suiteName%, %suiteId%, %specName%, %specId%, %browser%, %resolution% and %increment% with their respective values
        basename: '%resolution%/%suiteId% - %suiteName%/%browser% - %specId% - %specName% (%increment%)',
 
        image: {
 
        	// where to put the screenshots, used by the default callback
            target: './reports/protractor-snapshot/custom/image',
 
            // default callbacks to handle the screenshot data
            callbacks: [
                function (instance, png, customConfig) {
                    // instance = $snapshot instance
                    // png = image data
                    // customConfig = argument provided to .image()
                },
 
                // by default this callback is configured
                require('protractor-snapshot').saveImage
            ]
        },
 
        source: {
 
        	// where to put the html snapshots, used by the default callback
            target: './reports/protractor-snapshot/custom/source',
 
            // remove <meta name="fragment" content="!"> elements from the HTML snapshots
            removeMetaFragments: false,
            
            // default callbacks to handle snapshot data
            callbacks: [
                function (instance, html, customConfig) {
                    // instance = $snapshot instance
                    // html = html contents of page as string
                    // customConfig = argument provided to .source()
                },
 
                // by default this callback is configured
                require('protractor-snapshot').saveSource
            ]
        },
 
        // what resolution to turn back to after cycle(), [width, height, type]
        // type can be 'window' for outer window size, or 'viewport' for viewport size
        defaultResolution: [700, 700, 'window'],
 
        // supported resolutions, array of [width, height, type]
        // type can be 'window' for outer window size, or 'viewport' for viewport size
        resolutions: [
            [1366, 768, 'window'],
            [320, 568, 'viewport']
        ],
 
        // function or array of function, executed on first call of image() or source()
        // each function receives the ProtractorSnapshot instance as argument so you can use its config
        onInit: function ($snapshot) {
            $snapshot.clearTarget('./reports');
        },
 
        // write a log of all created snapshots, set to false to disable
        report: './reports/protractor-snapshot/report.json'
    },
 
    onPrepare: function () {
 
        // For Jasmine V2 a reporter needs to be added to be able to access the suite/spec names
        var $protractorSnapshot = require('protractor-snapshot');
        $protractorSnapshot.addReporter();
 
    }
};

API

ProtractorSnapshot (class)

Instance is created and configured on require().

var $snapshot = require('protractor-snapshot'); // ProtractorSnapshot

ProtractorSnapshot.setConfig([options])

Reconfigure the current instance with new options. options are always extended with the default options.

ProtractorSnapshot.cycle([resolutions], callback)

Provide resolutions to override configured resolutions.

The callback is called when the window is resized to the targeted resolution.

ProtractorSnapshot.image([name || callback])

Creates a screenshot.

When using the default image callback:

• Specify a string to use as custom filename.
• Specify a function to use as a custom callback (called after other callbacks).
• Or leave empty.

When using a custom callback:

• The provided parameter is sent to your callback as third argument.
• Or leave empty.

Returns a promise that is resolved with an array of callback return values.

ProtractorSnapshot.source([name || callback])

Creates an HTML snapshot.

When using the default source callback:

• Specify a string to use as custom filename.
• Specify a function to use as a custom callback (called after other callbacks).
• Or leave empty.

When using a custom callback:

• The provided parameter is sent to your callback as third argument.
• Or leave empty.

Returns a promise that is resolved with an array of callback return values.

ProtractorSnapshot.getSuiteName()

Returns current Jasmine suite name.

ProtractorSnapshot.getSpecName()

Returns current Jasmine spec name.

ProtractorSnapshot.config

Returns current configuration object.

$snapshot.saveImage

Default callback for image saving. Uses image.target property from config to store image files.

$snapshot.saveSource

Default callback for source saving. Uses source.target property from config to store html files.

$snapshot.clearTarget(path)

Utility function to remove or empty a directory. This uses the rimraf.sync module and function.

Roadmap

• implement screenshot comparison utility
• rotate the supported resolutions
• identify resolutions by specifying device name (i.e. iphone5)