Transform your testing process with: Company-wide Licences, Test Observability & App Percy
No Result Found

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:

Yaml
Copy icon Copy 
version: 2
snapshot:
  widths:
    - 375
    - 1280
  minHeight: 1024
  percyCSS: ""
  disableShadowDOM: false
discovery:
  allowedHostnames: []
  disallowedHostnames: []
  networkIdleTimeout: 100
  captureMockedServiceWorker: false
  retry: false
upload:
  files: "**/*.{png,jpg,jpeg}"
  ignore: ""
  stripExtensions: false

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 
$ percy config --help
manage Percy config files
USAGE
  $ percy config:COMMAND
COMMANDS
  config:create    Create a Percy config file
  config:migrate   Migrate a Percy config file to the latest version
  config:validate  Validate a Percy config file
Copy icon Copy 
$ percy config:create --help
Create a Percy config file
USAGE
  $ percy config:create [FILEPATH]
ARGUMENTS
  FILEPATH  config filepath
OPTIONS
  --js    create a .percy.js file
  --json  create a .percy.json file
  --rc    create a .percyrc file
  --yaml  create a .percy.yaml file
  --yml   create a .percy.yml file
EXAMPLES
  $ percy config:create
  $ percy config:create --yaml
  $ percy config:create --json
  $ percy config:create --js
  $ percy config:create --rc
  $ percy config:create ./config/percy.yml
Copy icon Copy 
$ percy config:migrate --help
Migrate a Percy config file to the latest version
USAGE
  $ percy config:migrate [FILEPATH] [OUTPUT]
ARGUMENTS
  FILEPATH  current config filepath, detected by default
  OUTPUT    new config filepath to write to, defaults to FILEPATH
OPTIONS
  -d, --dry-run  prints the new config rather than writing it
EXAMPLES
  $ percy config:migrate
  $ percy config:migrate --dry-run
  $ percy config:migrate ./config/percy.yml
  $ percy config:migrate .percy.yml .percy.js
Copy icon Copy 
$ percy config:validate --help
Validate a Percy config file
USAGE
  $ percy config:validate [FILEPATH]
ARGUMENTS
  FILEPATH  config filepath, detected by default
EXAMPLES
  $ percy config:validate
  $ percy config:validate ./config/percy.yml

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. For more information, see Screenshot a single element.

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 
snapshot:
  minHeight: 1024
  enable-javascript: false
  freeze-animated-image: true
  freeze-animated-image-options:
    freeze-image-by-xpaths: ['/html/body/footer/div[2]/div[1]/a/figure/img']
  ignore-regions:
    ignore-region-xpaths: ['/html/body/footer/div[2]/div[1]/a/figure/img']
  consider-regions:
    consider-region-xpaths: ['/html/body/footer/div[2]/div[1]/a/figure/img']

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

Copy icon Copy 
version: 2
percy:
  token: abcde....
  defer-uploads: false
snapshot:
  widths: [375, 1280]
  min-height: 1024 # px
  scope: '.main'
  percy-css: |
    iframe {
      display: none;
    }
static:
  base-url: /blog/
  files: '**/*.html'
  ignore: '**/*.htm'
discovery:
  allowed-hostnames:
    - cdn.example.com
  disallowed-hostnames:
    - ad.network.net
  device-pixel-ratio: 2
  authorization:
    username: "user"
    password: "pass"
  request-headers:
    Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
  network-idle-timeout: 150 # ms
  disable-cache: false  # default
  concurrency: 15
  launch-options:
  	executable: '/path/to/chromium/executable'
    headless: true # default
    args: [] # browser arguments/flags
    timeout: 30000 # default
upload:
  files: "**/*.{png,jpg,jpeg}"
  ignore: ""
Copy icon Copy 
{
  "version": 2,
  "percy": {
    "token": "abcd....",
    "defer-uploads": false
  },
  "snapshot": {
    "widths": [
      375,
      1280
    ],
    "min-height": 1024,
    "percy-css": "iframe {\n  display: none;\n}\n"
  },
  "static": {
    "base-url": "/blog/",
    "files": "**/*.html",
    "ignore": "**/*.htm"
  },
  "discovery": {
    "allowed-hostnames": [
      "cdn.example.com"
    ],
    "authorization": {
      "username": "user",
      "password": "pass"
    },
    "request-headers": {
      "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
    },
    "network-idle-timeout": 150,
    "disable-cache": false,
    "concurrency": 15,
    "launch-options": {
      "executable": "/path/to/chromium/executable",
      "headless": true,
      "args": [],
      "timeout": 30000
    }
  },
  "upload": {
    "files": "**/*.{png,jpg,jpeg}",
    "ignore": ""
  }
}
Copy icon Copy 
module.exports = {
  version: 2,
  percy: {
    token: "abcd....",
    deferUploads: false
  }
  snapshot: {
    widths: [
      375,
      1280
    ],
    minHeight: 1024,
    percyCSS: 'iframe {\n  display: none;\n}\n'
  },
  static: {
    baseUrl: '/blog/',
    files: '**/*.html',
    ignore: '**/*.htm'
  },
  discovery: {
    allowedHostnames: [
      'cdn.example.com'
    ],
    authorization: {
      username: 'user',
      password: 'pass'
    },
    requestHeaders: {
      Authorization: `Basic ${Buffer.from('username:password').toString('base64')}`
    },
    networkIdleTimeout: 150,
    disableCache: false,
    concurrency: 15,
    launchOptions: {
      executable: '/path/to/chromium/executable',
      headless: true,
      args: [],
      timeout: 30000
    }
  },
  upload: {
    files: "**/*.{png,jpg,jpeg}",
    ignore: ""
  },
}
Copy icon Copy 
{
  // ...
  "percy": {
    "version": 2,
    "percy": {
    	"token": "abcd....",
    	"defer-uploads": false
  	},
    "snapshot": {
      "widths": [
        375,
        1280
      ],
      "min-height": 1024,
      "percy-css": "iframe { display: none; }"
    },
    "discovery": {
      "allowed-hostnames": [
        "cdn.example.com"
      ],
      "authorization": {
        "username": "user",
        "password": "pass"
      },
      "request-headers": {
        "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      "network-idle-timeout": 150,
      "concurrency": 20,
      "disable-cache": false,
      "launch-options": {
        "executable": "/path/to/chromium/executable",
        "headless": true,
        "args": [],
        "timeout": 30000
      }
    },
    "static": {
      "base-url": "/blog/",
      "files": "**/*.html",
      "ignore": "**/*.htm"
    },
    "upload": {
      "files": "**/*.{png,jpg,jpeg}",
      "ignore": ""
    }
  },
  // ...
}

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

  • ON THIS PAGE

    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 Check Circle