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:
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.
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. Note: When you capture the DOM, JavaScript remains enabled regardless of the “enable-javascript” option. JavaScript is only disabled in our rendering environment. You can use JavaScript to set the DOM state, take a Percy snapshot, and we will render it with JavaScript enabled or disabled based on the flag. |
| 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
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-separated 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
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 inpackage.json - a JSON or YAML, extensionless
.percyrcfile - a
.percy.*file with the extensions.json,.yaml,.yml, or.js - a
percy.config.jsif you are using “CommonJS” module - a
percy.config.cjsif you are using “type”: “module” in thepackage.jsonfile
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
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!