Take snapshots via CLI

How to grab Percy snapshots via CLI

The Percy snapshot is a powerful command that allows you to capture visual snapshots of web pages, lists, sitemaps, or static directories.

On this page, we’ll explore the different usage of Percy snapshot command through CLI and respective examples for the same. You have the option to either capture a full screenshot or take a screenshot of a single element.

Percy snapshot command

Run the Percy snapshot command via the command-line interface (CLI) as shown below. You can specify a snapshots file, a static directory, or the URL of a sitemap that you wish to capture snapshots of.

percy snapshot [options] <file|dir|sitemap>

Options

Use the below options along with percy snapshot command. For details, refer the below table:

Examples

Snapshot a file

When you have a file containing a list of snapshots, it must be in YAML, JSON, or a JavaScript format exporting a list of pages. Each snapshot should include at least a URL that can be navigated to using a browser.

• snapshots.yml (YAML):

- http://localhost:8080
- http://localhost:8080/two

• Command:

percy snapshot snapshots.yml

Snapshot options

You can provide a name, waitForTimeout, and waitForSelector to customize snapshot behavior.

• snapshots.json (JSON):

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

• Command:

percy snapshot snapshots.json

Advanced options

With the snapshot command, you can interact with the page by providing an execute option. This can be any valid JavaScript that runs inside a browser, except for certain non-serializable functions. For more information, refer to what makes JavaScript non-serializable.

document.querySelector('.my-button-example').click()

The execute option can also accept an object with these keys:

• afterNavigation - called after the page navigates to the given URL
• beforeResize - called before the page viewport is resized to one of the passed width(s)
• afterResize - called after the page viewport is resized to one of the passed width(s)
• beforeSnapshot - called before Percy captures a snapshot

- name: Execute Example
  url: http://localhost:8080/example
  execute:
    afterNavigation:
    beforeResize:
    afterResize:
    beforeSnapshot:

[{
  name: 'Execute Example',
  url: 'http://localhost:8080/example',
  execute: {
    afterNavigation() {},
    beforeResize() {},
    afterResize() {},
    beforeSnapshot() {}
  }
}]

For advanced use cases, you can specify an execute function and additionalSnapshots for each snapshot to execute JavaScript within the page execution context before taking subsequent snapshots.

• snapshots.js (JavaScript):

module.exports = [{
  name: 'My form',
  url: 'http://localhost:8080/form',
  waitForSelector: '.form-loaded',
  execute() {
    document.querySelector('.name').value = 'Name Namerson';
    document.querySelector('.email').value = 'email@domain.com';
  },
  additionalSnapshots: [{
    suffix: ' - submitting',
    execute() {
      document.querySelector('.submit').click();
    }
  }, {
    suffix: ' - after submit',
    waitForSelector: '.form-submitted'
  }]
}]

• Command:

percy snapshot snapshots.js

The snapshot command also accepts a JavaScript file that exports an array of objects (with the keys name & url present). You can export sync or async functions from this file.

For example, a common use case is to build an array of pages dynamically and then iterate over that array to snapshot pages. You can export that array to the snapshot command. As a snapshots.js file:

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

Instead of an array of snapshots, list files can also contain an object that defines additional top-level options along with a snapshots option containing the array of snapshots. This allows dynamically filtering lists with include/exclude options, and enables utilizing features such as YAML anchors and references.

• Example snapshots.yml

base-url: https://example.com
exclude:
  - /page/(\d+)
references:
  dismiss-cookie-banner: &dismiss-cookie-banner |
    document.querySelector('.cookie-banner .dismiss').click();
snapshots:
  - url: /foo
    execute: *dismiss-cookie-banner
  - url: /foo
    name: "/foo - with cookie banner"
  - url: /bar
    execute: *dismiss-cookie-banner

See per-snapshot configuration options for additional common per-snapshot options (like widths, percy-css, etc).

Snapshot a static directory

When providing a static directory, it will be served locally and with below use cases:

• Pages matching the files argument (excluding the ignore argument) will be navigated to and snapshotted.
• Pages matching the include argument (and excluding the exclude argument) will be navigated to and snapshotted.

percy snapshot ./public

• Static Options
  For snapshotting static directories, you can configure options in the Percy configuration file.

.percy.yml (YAML):

version: 2
static:
  base-url: /
  clean-urls: false
  include: **/*.html
  exclude: []
  rewrites: {}
  options: []

• Example using include/exclude options

// .percy.js
module.exports = {
  version: 2,
  static: {
    include: [
      'blog/**/*.html',          // glob
      'pages/page-(?!10).html$', // pattern
      /about-(.+)\.html/i        // regexp
    ],
    exclude: [
      // function that returns true when matching
      ({ name }) => DISALLOWED.includes(name)
    ]
  }
};

• Example using rewrite

# .percy.yml
version: 2
static:
  base-url: /blog
  rewrites:
    /:year/:month/:title: /posts/:year-:month--:title.html
    /:year/:month: /posts/index-:year-:month.html
    /:year: /posts/index-:year.html

• Example using options

# .percy.yml
version: 2
static:
  options:
  - files: /foo-bar.html
    waitForSelector: .is-ready
    execute: |
      document.querySelector('.button').click()

Snapshot a sitemap URL

When providing a sitemap URL, the document must be an XML document. You can use --include and --exclude flags to filter snapshots. The Percy configuration file also accepts options.

• Command:

percy snapshot https://percy.io/sitemap.xml --dry-run

• Sitemap options:

# .percy.yml
version: 2
sitemap:
  include: **/*.html
  exclude: []
  overrides: []

• Command:

percy snapshot snapshots.js

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 }))
}

Screenshot a single element

Sometimes capturing a full-page screenshot isn’t necessary. For example, if there are dynamic parts of the page that you don’t need to test or are only interested in a very specific region to test. For these cases, you can pass a scope snapshot option and Percy will only capture the scoped element on the given widths. This can be passed as a per-snapshot option. The scope selector accepts any valid selector you would be able to pass to document querySelector.

Screenshot a single element using selector

```yaml
version: 2
snapshot:
	scope: '.selector'

Screenshot a single element using xpath

```yaml
version: 2
snapshot:
	scope: '/html/body/header/div/div[6]/h1'

Screenshot a scrollable single element

```yaml
version: 2
snapshot:
	scope: '.selector'
	scope-options:
	  scroll: true

The Percy Snapshot Command is a versatile command for capturing and comparing visual snapshots, making it an indispensable part of your web development and testing workflow.

Use cases

<html>
  <head>
    <title>Example</title>
  </head>
  <body>
    <h1 class="underline">My example</h1>
    <p class="underline">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas tristique convallis sem, vitae sodales risus accumsan in</p>
    <p class="underline">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas tristique convallis sem, vitae sodales risus accumsan in</p>
  </body>
</html>

version: 2
snapshot:
	scope: ‘h1.underline’

<!-- Skipping most of the stuff for brevity -->
<!-- Original DOM -->
<div class="selector">
  <canvas> </canvas>
  <canvas> </canvas>
  <video> </video>
</div>
<!-- Post DOM Serialization -->
<div class="selector">
  <img> </img>
  <img> </img>
  <img> </img>
</div>

version: 2
snapshot:
	scope: '.selector img:nth-of-type(1)' // selects first canvas