cli-snapshot

@percy/cli-snapshot

Snapshot a list or static directory of web pages.

Commands

• percy snapshot PATHNAME

percy snapshot PATHNAME

Snapshot a list of pages from a file or directory

USAGE
  $ percy snapshot PATHNAME

ARGUMENTS
  PATHNAME  path to a directory or file containing a list of pages

OPTIONS
  -b, --base-url=base-url                          [default: /] the url path to serve the static directory from
  -c, --config=config                              configuration file path
  -d, --dry-run                                    prints a list of pages to snapshot without snapshotting
  -f, --files=files                                [default: **/*.{html,htm}] one or more globs matching static file paths to snapshot
  -h, --allowed-hostname=allowed-hostname          allowed hostnames
  -i, --ignore=ignore                              one or more globs matching static file paths to ignore
  -q, --quiet                                      log errors only
  -t, --network-idle-timeout=network-idle-timeout  asset discovery idle timeout
  -v, --verbose                                    log everything
  --disable-asset-cache                            disable asset discovery caches
  --silent                                         log nothing

EXAMPLES
  $ percy snapshot ./public
  $ percy snapshot pages.yml

Usage

Static Directory

When snapshotting a static directory, the directory will be served locally and each matching page will be navigated to and snapshotted.

$ percy snapshot ./public
[percy] Percy has started!
[percy] Created build #1: https://percy.io/org/project/123
[percy] Snapshot taken: /index.html
[percy] Snapshot taken: /about.html
[percy] Snapshot taken: /contact.html
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/org/project/123
[percy] Done!

Page Listing

When snapshotting a file containing a list of pages to snapshot, the page URLs must all be accessible by a browser. The file must be YAML, JSON, or a JS file exporting a list of pages. Each page must contain a snapshot name and url, with an optional waitFor option to wait for a selector or timeout before snapshotting the page.

YAML

pages.yml:

- name: Snapshot one
  url: http://localhost:8080

- name: Snapshot two
  url: http://localhost:8080/two
  # wait for an element or timeout before snapshotting
  waitFor: .some-element

Snapshotting pages.yml:

$ percy snapshot pages.yml
[percy] Percy has started!
[percy] Created build #1: https://percy.io/org/project/123
[percy] Snapshot taken: Snapshot one
[percy] Snapshot taken: Snapshot two
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/org/project/123
[percy] Done!

JSON

pages.json:

[{
  "name": "Snapshot one",
  "url": "http://localhost:8080"
}, {
  "name": "Snapshot two",
  "url": "http://localhost:8080/two",
  "waitFor": ".some-element"
}]

Snapshotting pages.json:

$ percy snapshot pages.json
[percy] Percy has started!
[percy] Created build #1: https://percy.io/org/project/123
[percy] Snapshot taken: Snapshot one
[percy] Snapshot taken: Snapshot two
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/org/project/123
[percy] Done!

JavaScript

For JavaScript exports, an execute function and additional snapshots may be specified for each page to interact with the underlying Puppeteer Page object before snapshots are taken.

pages.js:

module.exports = [{
  name: 'Snapshot one',
  url: 'http://localhost:8080',
  async execute(page) {
    await page.click('.button')
  }
}, {
  name: 'Snapshot two',
  url: 'http://localhost:8080/two',
  waitFor: '.some-element',
  snapshots: [{
    name: 'Snapshot two - after click',
    async execute(page) {
      await page.click('.button')
    }
  }, {
    name: 'Snapshot two - after double click',
    async execute(page) {
      await page.click('.button', { clickCount: 2 })
    }
  }]
}]

JavaScript files may also export sync or async functions that return a list of pages to snapshot.

module.exports = async () => {
  let urls = await getSnapshotUrls()
  return urls.map(url => ({ name: url, url }))
}

Snapshotting pages.js:

$ percy snapshot pages.js
[percy] Percy has started!
[percy] Created build #1: https://percy.io/org/project/123
[percy] Snapshot taken: Snapshot one
[percy] Snapshot taken: Snapshot two
[percy] Snapshot taken: Snapshot two - after click
[percy] Snapshot taken: Snapshot two - after double click
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/org/project/123
[percy] Done!