modshot

modshot is a CLI utility that captures screenshots (png image) of UI modules and compares with an existing baseline image. If a baseline is not present, a new baseline is created. It is a wrapper on top of PhantomCSS, to provide an easy mechanism for visual regression.

modshot can operate in two modes

1. Static HTML - When provided with an input directory (check usage below), modshot recursively scans the directory looking for HTML files. If a file is found loads it with PhantomJS, takes a screenshot and puts them in a screenshots directory adjacent to the HTML file. For subsequent runs, these screenshots are used as baselines. modshot assumes that you follow a modular UI architecture, where each of the UI component lives in its own directory along with the test files and mock HTML.
2. URL - When a URL is provided (check usage below), modshot loads the URL with PhantomJS, takes a screenshot (or multiple screenshots if selectors are provided) and puts them in the provided output directory. For subsequent runs, these screenshots are used as baselines. It is advised to provide CSS selectors of modules as option, so module screenshots are taken instead of the whole page.

If both modes (static HTML & URL) are provided, modshot starts both of them in parallel. If a modshot run fails, but the UI change was intentional, then the developer has to manually delete the baseline. modshot will create a new baseline in the next run.

Prerequisites

• PhantomJS 1.8.2 or greater, but less than 2.0. Installation instructions can be found here. Please install this before installing modshot

Usage

Install modshot

$ npm install -g modshot

To run modshot

USAGE modshot [options]*

Options:
--in-dir | -i       The input directory to recurse and fetch the HTML files. 
                    Uses current working directory if not specified
--url | -u          The web page URL to take screenshots
--out-dir | -o      The output directory to save the screenshots. 
                    Optional when an input directory is provided, as screenshots are saved adjacent to the HTML files.
                    When a URL is provided and output directory is missing, current working directory is used as output directory
--selectors | -s    A list of selectors to be applied on the HTML files or URL
--exclude | -e      Paths|files|directories to be excluded. node_modules excluded by default.
                    A list can be provided -e test -e dist
--tolerance | -t    Mismatch tolerance percentage. Defaults to  0.05%
--delay             The number of milliseconds to wait after page load, to take the screenshot. Defaults to 0
--cookie | -c       The cookie value to be set in the cookie HTTP header
--domain | -d       The domain to set the cookie. By defalut '*' would be used
--prefix | -p       A prefix that would be prepended to the screenshot image name
--help | -h         Displays this information

Example 1:

modshot -i src/ui-modules -s .box -s .test -e temp

Example 2:

modshot -u http://pages.ebay.com/sitemap.html -s h1 -s .btn -o screenshots

Example 3:

modshot -i src/ui-modules -u http://pages.ebay.com/sitemap.html -o screenshots -t 15

Example 4:

modshot -u http://pages.ebay.com/sitemap.html -p projectX -o screenshots

Running modshot with no options, uses the current directory as the input directory and scans for static HTML files.

##Authenticated Pages To run modshot on authenticated pages i.e. pages behind a sign-in, pass in the cookie and its associated domain values. modshot will set the HTTP cookie header before making the page request. For a server this would be a normal cookie based authentication.

modshot -u http://pages.ebay.com/sitemap.html -o screenshots -c "k=v; a=b" -d xyz.com

##Testing The testing suite is available in the test directory. To run the tests - clone/fork the repo, install the package $ npm install and run

$ npm test

##Issues Have a bug or a feature request? Please open a new issue

##Author Senthil Padmanabhan

##License Copyright (c) 2015 eBay Inc.

Released under the MIT License http://www.opensource.org/licenses/MIT