@brikcss/shots

Shots

Shots is a browser screenshot tool, made especially to simplify visual UI regression testing. It tests in Google (Headless Chrome) with Google's Puppeteer and compares screenshots with Pixelmatch. The process is simple: Take baseline shots, run regression tests during development. When desired changes are made, easily approve screenshots to promote them as the new baseline.

---

Environment support

Node	CLI	UMD	ES Module	Browser
✔	✔	x	x	x

Install

npm install -D @brikcss/shots

Methods

baseline()

Sets up baseline images which are used to compare with future shots.

CLI:

shots baseline <options>
# or with NPM scripts:
npx shots baseline <options>

Node:

shots.baseline(options = {});

test()

Runs a regression test. Takes current screenshots and compares them against the set of baseline images.

CLI:

shots test <options>
# or with NPM scripts:
npx shots test <options>

Node:

shots.test(options = {});

approve()

Approves the most recently run tests and promote them to baseline shots.

CLI:

shots approve <options>
# or with NPM scripts:
npx shots approve <options>

Node:

shots.approve(options = {});

Configuration options

• cases {Array} required Configuration for your test cases. Each test case requires an id and path property. The id determines the base filename, and path is the path to the page you wish to test.

• url {String} shots requires you to set up and run your own local server. You may alternative use the local file:// protocol. config.url simply tells shots where to find your app.

• viewports {Array} A screenshot will be created for each viewport size. This setting is passed directly to Puppeteer's page.setViewport(viewport) method.

• beforeShot {Function} beforeShot(test, { browser, page, config }) => {} Callback which runs after Puppeteer has created the browser page and navigated to the URL, and before each screenshot is taken. This allows you to take full advantage of the Puppeteer API to manipulate the page before the shot is taken. Useful, for example, to only show the elements you wish to test.

• afterShot {Function} afterShot(test, { browser, page, config }) => {} Callback which runs immediately after each screenshot is taken and before the browser page closes. This allows you to tie in to Puppeteer's API to do anything you want.

• threshold {Number} Number between 0 and 1, passed directly to pixelmatch to set the threshold level at which a screenshot comparison will pass or fail.

• browserSync {Object or Boolean} Browser-sync configuration. Some options are unavailable, as browser-sync only runs invisibly. Set to false to disable browser-sync, in which case you will need to manually run your own server before running shots.

• config {String} Path to a config file to load. A config file must be a JS or JSON file which can be require()d by node.

• baseDir {String} Directory to save baseline tests to.

• currentDir {String} Directory to save the most recent test to.

• id {String} For the approve() method only. Rather than approving all shots in a test set at once, use this setting to pass a comma-separated list of specific test IDs you wish to approve.