Covered in this doc
How to integrate Percy intoĀ static websites with the npm
percy
package
Configuringpercy
for testing locally and with CI
This documentation is for @percy/agent
If you are using
@percy/cli
(the new generation of SDKs), the snapshot docs are here: https://docs.percy.io/docs/cli-snapshotThis page will soon be deprecated (in favor of
@percy/cli
)
Environment setup
The percy
package relies on theĀ PERCY_TOKEN
Ā environment variable for authenticating and authorizing access to each project. The first step is to make your PERCY_TOKEN
available in your environment.
On Linux and Mac, run:
$ export PERCY_TOKEN=aaabbbcccdddeeefff
On Windows, run:
$ set PERCY_TOKEN=aaabbbcccdddeeefff
Important
Keep your
PERCY_TOKEN
secret.Ā Anyone with access to your token can consume your account quota, though they cannot read data.
Generating snapshots
If your generated static site exists in a directory calledĀ _site
, simply run:
$ npx percy snapshot _site/
And that's it! Percy will create a build and snapshot by default all of the HTML files inside _site/
.
For example:
$ npx percy snapshot _site/
Creating build...
percy has started.
serving static site at http://localhost:5339/
snapshot taken: 'http://localhost:5339/index.html'
snapshot taken: 'http://localhost:5339/404.html'
snapshot taken: 'http://localhost:5339/contact.html'
shutting down static site at http://localhost:5339/
stopping percy...
done!
finalized build...
CI Configuration
You can do the above steps locally for testing, but to get continuous visual integration for your static site youāll need to run the npx percy snapshot _site/
command in CI.
You'll also want to make sure your PERCY_TOKEN
is setup for that run. See theĀ CI setupĀ guides for how to securely set environment variables in your CI service.
For example, in CircleCI if we were using Hugo to generate your site, we can add these steps toĀ .circleci/config.yml
:
version: 2
jobs:
build:
docker:
- image: cibuilds/hugo:latest
working_directory: ~/hugo
steps:
- run: apk add --update nodejs npm # install node, npm, and npx
- checkout # checkout the repository
- run: hugo -v -d ~/hugo/public . # build the site
- run: npx percy snapshot ~/hugo/public # run Percy
Installing percy with npm
The npx
command has the benefit of being able to install and run any node package without having to worry about creating or maintaining a package.json
, package-lock.json
or similar file. However, the downside is that the percy
package will be downloaded and installed every time. This can add time to your test runs.
When running Percy in CI (or even locally) consider using a package.json
file to install and easily version percy
. Using npm
will install the latest version of percy
locally and save the version in a package.json
file. Both npm
and npx
are available in Node 8.2 or newer.
If you don't already have a package.json
file, you can create one by running:
$ npm init
Next install the percy
package.
$ npm install --save-dev percy
The npx
command will then look for this local binary before downloading and installing a different version. A package.json
file will also make it easier to use a specific version of percy
.
With a package.json
file added to your codebase, your CI setup can now benefit from installing a cached version of percy
by running one command before running Percy.
$ npm install
$ npx percy snapshot _site/
CLI options
--snapshot-files, -s
Glob or comma separated string of globs for matching the files to snapshot.
The default value is **/*.html,**/*.htm
.
$ npx percy snapshot _site --snapshot-files _site/**/*.html,_docs/**/*.html
TIP: You can test your globs on globster.xyz
--ignore-files, -i
Glob or comma separated string of globs for ignoring the files to snapshot.
The default value is empty.
$ npx percy snapshot _site --ignore-files _old-site/**/*.html
--base-url, -b
If your static files are hosted in a sub-directory instead of the webserver root, you will need to provide theĀ --base-url
Ā flag. The base URL must begin with a slash.
The default value is /
.
$ npx percy snapshot _site/ --base-url /my-subdir
--network-idle-timeout, -t
The idle time (in ms) that percy
will wait for assets to load before moving on to the next page. Your site will be hosted locally and then percy
will visit each page. If your assets have not loaded by the time the timeout is reached, then your snapshots in Percy might not correctly render on our servers. Consider raising this time if you see this occur on your snapshots.
The default value is 50
(ms).
$ npx percy snapshot _site/ --network-idle-timeout 250
Additional configuration options
Additional widths and a minimum viewport height can be set via the percy.yml file.
Updated about a month ago