Sign in or start for free

Configuration

Suggest Edits

👍

Covered in this doc

  • Getting started with Percy's SDK config
  • How to use the config CLI command
  • How configuration files work in @percy/cli
  • Complete configuration options for @percy/cli

📘

You are viewing docs for the new @percy/cli.Most SDKs have been updated to utilize the new CLI, so check the appropriate SDK doc for instruction for your specific SDK!

Percy SDKs can be configured in many different ways. To quickly get started, run percy config:create in your project's root directory (or wherever percy is run from). This config file allows you to globally set configuration options for each build (run percy config:create --help to see the various options).

Running this command will create a skeleton config file (with pre-populated defaults):

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

Once the configuration file is created, running percy exec should automatically detect the file and use the specified options for all snapshots in the build!

CLI command

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

$ 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

$ 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

$ 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

$ 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

Files

Percy SDKs can be configured by using a configuration file, or by adding a "percy" entry to your package.json. Percy will look for the following configs, in order, in 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 CommonJS module

Failing to find a config in the current directory, Percy will continue to search up the directory tree, checking for each of these configs in each directory, until it finds some acceptable configuration (or hits the home directory).

You can also specify the path directly to a config file by passing a --config or -c option to the percy exec command:

$ percy exec --config ./configs/percy.conf.yml -- ...

All options

Percy currently support for the following configuration options:

snapshot

  • 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.

static

  • 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.

discovery

  • 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.
  • 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.
  • 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 browsers 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

upload

  • 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

version: 2
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: ""

{
  "version": 2,
  "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": ""
  }
}

module.exports = {
  version: 2,
  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: ""
  },
}

{
  // ...
  "percy": {
    "version": 2,
    "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": ""
    }
  },
  // ...
}

Per-snapshot configuration

All Percy SDKs that support @percy/cli can accept snapshot options as the final argument of the SDK's percySnapshot function. These snapshot options will override or be merged with (where applicable) their equivalent Percy config file options.

percySnapshot(name, OPTIONS)
percySnapshot(driver, name, OPTIONS)
// ...etc

👍

Use your preferred casing style!

The underlying CLI API accepts the following options in camelCase, PascalCase, snake_case, or kebab-case!

  • widths: An array of numbers, in pixels, representing the widths you'd like to capture for each snapshot; overrides global snapshot widths.
  • min-height: A number specifying the minimum height in pixels each snapshot should be.
  • percy-css: A string containing Percy specific CSS; appended to any global percy-css.
  • enable-javascript: A boolean that enables JavaScript for all snapshots in the build. This may cause side-effects like animations or redirects making your snapshots less reliable.
  • scope: A string of a selector to scope the given screenshot to.
  • discovery: A subset of discovery options to use for this snapshot's asset discovery.
    • allowed-hostnames: An array of additional hostnames to save asset contents from; merged with any existing allowed-hostnames.
    • 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; merged with any existing request-headers.
    • authorization: A username/password combo to authenticate requests for Percy.
    • disable-cache: Disables asset discovery caches.
    • user-agent: Custom user-agent string used when requesting assets

Migrating from v1

Migrating from v1 of the Percy config is quick and easy with the percy config:migrate command. Running this command in the directory with the v1 config will convert the old config to v2.

$ percy config:migrate
[percy] Found config file: .percy.yml
[percy] Migrating config file...
[percy] Config file migrated!

Debugging

If you're having trouble with setting up a configuration file, you can run the validate command (percy config:validate), which will print out any errors with the current config.

Keep in mind, Percy will look for configs based on where you're executing the percy command from. If you're still having trouble with setting up a config file, feel free to file an issue.

Updated about 1 month ago