Skip to main content
Transform your testing process with: Company-wide Licences, Test Observability & App Percy

Run Percy tests on Jekyll

A guide to integrating your Jekyll static site with BrowserStack Percy. Catch visual differences in your web application on time.

Prerequisites

  • Node 10.0.0 or higher
  • A PERCY_TOKEN. Your token can be found on your Percy project settings page.

Environment setup

The first step is to make your PERCY_TOKEN available in your environment. The percy package relies on the PERCY_TOKEN environment variable for authenticating and authorizing access to each project.

Copy icon Copy snippet
Copy icon Copy snippet

Keep your PERCY_TOKEN secret. Anyone with access to your token can consume your account quota, though they cannot read data.

Generating snapshots

Before your site can be visually tested with Percy, you must build your Jekyll site. If you’re using the defaults provided by Jeykll, your built site is output into a _site/ directory.

Copy icon Copy snippet

To take snapshots of the built site, simply run:

Copy icon Copy snippet

And that’s it! Percy will create a build and snapshot by default all of the HTML files inside _site/.

For example:

Copy icon Copy snippet

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.

An example CircleCI .circleci/config.yml file might look something like the config below. We have added a few comments throughout the file to explain:

Copy icon Copy snippet

Advanced configuration

Changing the base url

Jeykll allows you to set the path your built site becomes hosted at by configuring a baseurl option in the _config.yml file.

If you have configured a baseurl, you will want to also pass that as a command line option to the snapshot command. For example, if your site outputs to _site and your baseurl is set to blog, you’ll pass the --base-url /blog flag.

Copy icon Copy snippet

Ignoring files

You may want to exclude a section of your website from being visually tested. You can configure this with the --ignore-files flag.

For example, let’s say you want to snapshot everything on your website except draft blog posts. You can do so like this:

Copy icon Copy snippet

Example Integration

A reference integration of Percy and Jeykll is available.

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

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