Configuration
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 inpackage.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