Ask the Community
Run Percy using CLI
How to run Percy via CLI and capture snapshots for visual comparisons.
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.
You can run Percy using the CLI in two ways:
- Use
percy execwhen running with a configuration file. - Use
percy snapshot [options] <file|dir|sitemap>to capture snapshots directly.
This is not applicable when using BrowserStack SDK.
Choose the appropriate method and refer to the following section for details:
To run Percy via the percy exec command, you need to create a configuration file. Let’s get started!
Configuration file
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.
The Percy snapshot is a powerful command that allows you to capture visual snapshots of web pages, lists, sitemaps, or static directories.
In this section, 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.
Options
Use the below options along with percy snapshot command. For details, refer the below table:
| Option | Description |
|---|---|
| General | -b, –base-url --include --exclude |
| Static | –clean-urls: Rewrite static index and filepath URLs to be clean. |
| Percy | -c, –config -d, --dry-run: Print snapshot names only, useful for testing without actually taking snapshots. -h, --allowed-hostname -t, --network-idle-timeout --disable-cache: Disable asset discovery caches. --debug: Enable debug mode for asset discovery and prevent uploading snapshots. |
| Global | -v, –verbose: Log all activity. -q, –quiet: Log errors only. -s, –silent: Disable all logging. –help: Display command help. |
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):
- Command:
Snapshot options
You can provide a name, waitForTimeout, and waitForSelector to customize snapshot behavior.
- snapshots.json (JSON):
- Command:
Advanced options
With the snapshot command, you can interact with the page by providing an execute option. This can be any valid JavaScript you run inside of a browser.
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
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.
All options are also accepted by other file formats. For execute however, a string containing a function body can be provided when the file format prevents normal functions.
- snapshots.js (JavaScript):
- Command:
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:
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
| Option | Description |
|---|---|
| url (required) | URL of the page to visit and snapshot. |
| name | Name of the snapshot (must be unique). |
| execute | JavaScript you would like to execute in browser before capturing a snapshot. |
| waitForTimeout | An amount of time to wait before capturing a snapshot. |
| waitForSelector | A CSS selector to wait to appear on page before capturing a snapshot. |
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
filesargument (excluding theignoreargument) will be navigated to and snapshotted. - Pages matching the
includeargument (and excluding theexcludeargument) will be navigated to and snapshotted.
- Static Options
For snapshotting static directories, you can configure options in the Percy configuration file.
.percy.yml (YAML):
- Example using include/exclude options
- Example using rewrite
- Example using options
| Option | Description |
|---|---|
| base-url | The base URL path the static site should be served under. |
| clean-urls | When true, rewrite index and filepath URLs to be clean. |
| include/exclude | A predicate or an array of predicates matching snapshots to include/exclude. A predicate can be a string glob or pattern, a regular expression, or a function that accepts a snapshot object and returns true or false if the snapshot is considered matching or not. |
| rewrites | An object containing source-destination pairs for rewriting URLs. Paths for resources can sometimes be expected to be in a certain format that may not be covered by the clean-urls option. For such paths, rewrites can map a short, clean, or pretty path to a specific resource. Paths are matched using path-to-regexp. |
| overrides | An array of per-snapshot option overrides. Just like page listing options, static snapshots may also contain per-snapshot configuration options. However, since pages are matched against the files option, so are per-snapshot configuration options via an array of overrides. If multiple overrides match a snapshot, they will be merged with previously matched overrides. |
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.
Sitemaps can contain a lot of URLs, so its best to always start with the --dry-run flag while fine tuning the include and exclude options.
- Command:
- Sitemap options:
- Command:
JavaScript files may also export sync or async functions that return a list of pages to snapshot.
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.
- If there are multiple matching selectors on the page, Percy will select the first matching element.
Screenshot a single element using selector
Screenshot a single element using xpath
Screenshot a scrollable single element
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
Multiple elements with the same selector
If you would like to scope a screenshot to a specific element that has the same matching selector as other elements on the page you’ll have to get more specific with your selector. This can be done by either adding another unique selector to that element or by using standard CSS selectors to get more specific. This is the same way you would write CSS – Percy doesn’t add anything to this process.
For example, given the below DOM:
Instead of using just .underline to select the element, you would want to either specify the element type (h1 / p) or by using CSS tree-structural pseudo-classes like :last-of-type or :nth-child.
Likewise,
-
p.underlinescope selects the ‘first’ paragraph -
p.underline:last-of-typescope selects last paragraph
Selector for elements serialized by Percy
It may happen that your single-element screenshots are not working correctly with canvas/video elements.
During DOM serialization <canvas>, <video> elements are converted to <img>. Check canvas elements in Percy’s SDK Workflow. This can cause the selector to not match, and an incorrect screenshot.
To work around this, we can use CSS tree structural pseudo-classes as suggested in the previous section.
- Instead of
canvasorvideoyou’ll need to change it toimg - If there is only a single canvas/video tag inside
divwe can directly use.selectoras the scope.
Likewise,
-
.selector img:nth-of-type(2)scope selects the ‘second’ canvas -
.selector img:last-of-typescope selects the ‘last’ video
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!