Skip to main content
Transform your testing process with: Company-wide Licences, Test Observability & App Percy

What is a Percy snapshot?

Introduction to Percy snapshots and the different ways to grab them

Percy Snapshots are a fundamental component of Percy. These are static images of your web pages or components and provide a visual baseline of how your application should look, making it easier to detect any unexpected visual changes introduced by code modifications.

On this page, we’ll explore the available options to take Percy snapshots, the process of creating your custom configuration files, the default settings provided by Percy, the available configurations for utilizing this command, and the rules governing the precedence of configuration files.

There are two ways to use Percy snapshot method:

  • Taking snapshots via CLI.
  • Taking snapshots via test scripts.

Configuration file

To begin, run percy config:create within your project’s main directory (or from wherever you run percy). This configuration file allows you to globally set configuration options for each build.

There are various options to customize the configuration of Percy Software Development Kits (SDKs). Run percy config:create --help to see the all options.

Running percy config:create command will generate a basic configuration file with default settings already filled in as shown:

Copy icon Copy snippet

Once the configuration file is created, run percy exec and it automatically detects the file and use the specified options for all snapshots in the build.

Config CLI command

The Percy CLI has a config CLI command, which helps managing Percy config.

Copy icon Copy snippet
Copy icon Copy snippet
Copy icon Copy snippet
Copy icon Copy snippet

All configuration options

Percy currently support for the following configuration options:

For Percy

Option Description
token A Percy project token can be provided here. Note: PERCY_TOKEN environment variable would override token provided in config file.
defer-uploads Upload all snapshots post tests are complete. This is only required in a few cases, refer Capture Responsive DOM snapshots for details.

For Snapshot command

Option Description
widths An array of numbers, in pixels, representing the widths you’d like to capture for each snapshot. Default: [375, 1280]
min-height A number specifying the minimum height in pixels each snapshot should be. Default: 1024.
percy-css A string containing Percy specific CSS that will be applied to each snapshot (per-snapshot Percy CSS is concatenated to the end of this value).
enable-javascript A boolean that enables JavaScript for all snapshots in the project. This may cause side-effects like animations or redirects making your snapshots less reliable. Default: false.
scope A string of a selector to scope the given screenshot to.
enableLayout A boolean to enable layout testing while capturing the screenshot. Default:false.
scope-options This option is specific to the scope element and works only if the scope is passed.
scroll: a boolean to scroll on scope element passed. Learn more

Below options are only applicable with Percy on Automate integration.

Option Description
freeze-animated-image To determine whether Percy will perform stabilization on the DOM. Default: false.
freeze-animated-image-options To freeze specific animated images that do not appear to freeze. Default: false.
freeze-image-by-selectors To freeze specific animated images by selectors. Note: To be passed under freeze-animated-image-options option.
freeze-image-by-xpaths To freeze specific animated images by xpaths. Note: To be passed under freeze-animated-image-options option.
ignore-regions To ignore a particular set of elements or sections in DOM.
ignore-region-selectors Ignore particular sections of DOM based on strings of CSS selectors array. Default: []. Note: To be passed under ignore-regions option.
ignore-region-xpaths Ignore particular sections of DOM based on strings of Xpaths array. Default: []. Note: To be passed under ignore-regions option.
consider-regions To counteract the effects of IntelliIgnore.
consider-region-selectors Consider particular sections of DOM based on strings of CSS selectors array. Default: []. Note: To be passed under consider-regions option.
consider-region-xpaths Consider particular sections of DOM based on strings of Xpaths array. Default: []. Note: To be passed under consider-regions option.
full-Page To capture fullpage screenshots. Default: false.

Check the following configuration file to understand how to set the options when using Percy on Automate.

Configuration file

Copy icon Copy snippet

For Static directory

Option Description
base-url If your static files will be hosted in a subdirectory, instead of the web server’s root path, set that subdirectory with this flag. Default: /
files Glob or array of globs for matching static file paths to snapshot. Default: **/*.{html,htm}
ignore Glob or array of globs for matching static file paths to ignore.

For asset discovery

Option Description
allowed-hostnames An array of additional hostnames to save asset contents from. By default Percy only captures assets from the hostname that the snapshot was taken on. More Info
disallowed-hostnames An array of hostnames to immediately abort requests from.
request-headers An object containing HTTP headers to be sent for each request made during asset discovery.
authorization A username/password combo to authenticate requests for Percy. More Info
cookies Cookies to use for discovery’s browser session.
disable-cache Disables asset discovery caches.
device-pixel-ratio A number specifying the pixel density to render the page in. Default: 1.
user-agent Custom user-agent string used when requesting assets.
network-idle-timeout The amount of time where the snapshotted page has had zero network requests (in milliseconds). Once this has been reached, asset discovery closes.
concurrency The amount of parallelism asset discovery has for processing snapshots.
launch-options Options to pass to the asset discovery that is being launched.
- executable: A path to a Chromium browser executable on disk.
- headless: Hide or show the asset discovery browser. Default: true
- args: Browser flags/args to pass when launching the executable.
- timeout: Timeout for how long the browser will try to launch. Default: 30000. More Info
capture-mocked-service-worker A boolean flag that enables the capturing of Mock Service Worker (MSW) responses. Default: false .
capture-srcset A boolean flag that enables the capture of image assets found in srcset. Note: This will increase the time required for asset discovery.
retry A boolean flag that will retry asset discovery up to 3 times. Set this to true if you encounter intermittent log lines like this: [percy] Encountered an error taking snapshot: (name of the snapshot) for the same snapshot across multiple builds.

For file upload

Option Description
files Glob or comma-seperated string of globs for matching the file types to upload. Default: */.{png,jpg,jpeg}.
ignore Glob or comma-separated string of globs for matching the files to ignore.

A complete config

Copy icon Copy snippet
Copy icon Copy snippet
Copy icon Copy snippet
Copy icon Copy snippet

Configuration file precedence

Percy SDKs can be configured through either a configuration file or by adding a “percy” entry in your package.json. Percy will search for the following configurations, in the below order, within the current working directory:

  • a "percy" property in package.json
  • a JSON or YAML, extensionless .percyrc file
  • a .percy.* file with the extensions .json, .yaml, .yml, or .js
  • a percy.config.js if you are using “CommonJS” module
  • a percy.config.cjs if you are using “type”: “module” in the package.json file

If a configuration is not found in the current directory, Percy will proceed to search the directory hierarchy, inspecting each directory along the way for these configurations, until it discovers a suitable configuration or reaches the home directory.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy