storysnap

Storysnap

A navigation and CSS regression utility based on headless Chrome.

Install

• You must have Chrome >= 59 installed on the machine where this script is running.*

npm i storysnap

You can also install it globally using '-g' flag and access it as simply storysnap.

Usage

Storysnap provides a CLI and a programatic way of using it's functionality.

CLI usage

./node_modules/.bin/storysnap --script [navigationScript.js] --test --screenshotDir ./screenshots --reporters xunit,progress --threshold 0.1

The arguments are as follows:

1. --script - (Required) Points to a path where the JS script that drives the browser lives. Checkout the 'examples/' folder for 2 examples of driving the browser using the API provided by storysnap.
2. --test - (Optional) Whether or not Storysnap runs in test mode. When in test mode it will trigger a comparison of the screenshots taken during navigation with know baseline screenshots.
3. --screenshotDir - (Optional) Location where the screenshots taken during nav will be saved.
4. --reporters - (Optional) Comma separated list of reporters when Storysnap is in test mode. Currently only xunit and progress reporters are provided out of the box. Default to progress.
5. --threshold - (Optional) Numeric threshold when comparing the actual and the baseline images when Storysnap is run in test mode. If the differences are greater than the specified threshold the test is considered failed. Uses PixelMatch for doing the comparisons.
6. --delay - (Optional) Timeout in milliseconds until the navigation starts. This was added in order to allow a certain amount of time for servers to kick off etc before doing a navigation. Default to 0(navigation starts immediately)
7. --xunitFile - (Optional) If reporter is set to xunit, this represents the XML file path and name where the results would be written.

Any other arguments can be passed and they'll be available in the navigation scripts( eg check out how React Storybook scrapper example gets the --storybookUrl param )

NodeJS programatic usage

Check out the 'examples/' folder for a couple of examples:

• storybook-scrapper - Is an example of how you can implement a simple scrapper that connects to React Storybook and does screenshots of all the components it can find. You can run it like so:

./node_modules/.bin/storysnap --script ./node_modules/storysnap/examples/storybook-scrapper.js --test  --storybookUrl http://localhost:9009 --screenshotDir ./screenshots --reporters xunit,progress

Make sure React storybook is running before trying to take any screenshots and that --storybookUrl points to the correct URL!

• programatic-usage - A barebones programatic usage example that opens up Google, does a screenshot, types a text and then does another screenshot.

All APIs are promise based.

The API is comprised of:

• NavAPI - Contains the main method for performing navigation actions: clicking, typing, taking screenshots
• ImageManager - Is notified by the NavAPI whenever screenshots are being taken and takes care of recording them and comparing at the end of the test run.( if --test is ON )
• Reporters - Object having the shape

{
    ProgressReporter,
    XUnitReporter
}

A reporter has a single public method report(comparisonResults, opts) where comparisonResults are being generated by ImageManager and opts are all the command line args the user passed when invoking storysnap.

Basic navigation script structure

module.exports = (api, options) => Promise

eg,

module.exports = (api, options) => {
    const { NavAPI, ImageManager, Reporters } = api;
    if(options.test) {
        // ... do something when in test mode.
        // Access also custom args, like options.storybookUrl etc
    }
}