Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Covered in this doc

Integrating Percy with Capybara feature tests in any Ruby web framework including Rails, Sinatra, etc.

Percy Capybara on GitHub


If you've written feature tests (or "UI tests", "acceptance tests", etc.), you know how hard it can be to get them right and to get your app in the correct UI state. Percy Capybara lets you take all the time you've spent building your feature tests and expand them with screenshots and visual regression tests to cover all the visual changes in your app, even behind complex UI states.

The examples below assume you are using RSpec, but they can be easily adapted for other testing frameworks.

Beta release

This documentation is for Percy Capybara version 4.0.0.pre.beta2 and above. Earlier versions of Percy Capybara had a different, and incompatible, API.

See the Upgrading to v4 guide or the old docs.


Add this line to your application's Gemfile:

gem 'percy-capybara', '~> 4.0.0.pre.beta2'

And then run:

$ bundle install

Or install it yourself with gem install percy-capybara.

You will also need to install the Percy agent. This is a process runs alongside your tests, uploading snapshots to Percy on your behalf. You will need to use npm to install it.

If your project does not already have a package.json file in the root directory, run npm init and follow the prompts. package.json is like a Gemfile for Node packages.

To install @percy/agent locally for your project:

$ npm install --save-dev @percy/agent

This will create a ./node_modules/ directory containing the agent and its dependencies. The agent's executable binary will be located in ./node_modules/.bin/percy.

Next, import the Percy Capybara library into the file(s) from which you want to take snapshots:

require 'percy'

Now you can use Percy.snapshot(...) to generate a snapshot from your test:

describe 'Test with visual testing', type: :feature, js: true do
  it 'loads homepage' do
    visit ''
    Percy.snapshot(page, name: ' homepage')

The page object you pass into Percy.snapshot is the Capybara::Session object that represents the web page under test. It should be available in your Capybara tests.

Finally, wrap your test runner command in a percy exec command. This will start a local Percy agent to receive snapshots from your tests and upload them to your Percy dashboard.

You can invoke percy using its full path (typically ./node_modules/.bin/percy), or by calling npx percy (npx is a Node utility that lets you execute package binaries). If you're using an npm version before 5.2 that does not support npx, you can use $(npm bin)/percy instead.

For example, if you're using RSpec to run your tests, your new test command becomes:

$ npx percy exec -- rspec

Note the double dash, --, between npx percy exec and your test run command.

You'll want to add this npx percy exec -- <test runner> command as the new way for your CI system to run your tests.

That's it! Now, whenever your CI runs, a snapshot of the app in that state will be uploaded to Percy for visual regression testing!


Percy.snapshot(page, options)

page is the Capybara::Session object representing the web page you want to snapshot. Required.

options is an optional hash that can include:

  • name: A string identifying this snapshot. It can be any string that makes sense to you to identify the page and its state. It needs to be unique and remain the same across builds. If you don't provide it, Percy will use the full URL of the page under test. If you are taking multiple snapshots with the same URL, you will need to manually provide snapshot names in order to disambiguate between the two snapshots. For more details on generating snapshot names, see Autogenerated snapshot names.
  • widths: An array of integers representing the browser widths (in pixels) at which you want to take snapshots.
  • min_height: An integer specifying the minimum height of the resulting snapshot (the snapshot might turn to be higher than this value, depending on the contents of the page). Defaults to 1024px.


Percy.snapshot(page, { name: 'Responsive snapshot', widths: [768, 992, 1200] })
Percy.snapshot(page, { min_height: 2000 })

Global Configuration

You can also configure Percy to use the same options over all snapshots. To see supported configuration, including widths, read our Configuration doc.

Waiting for elements with Capybara

Capybara has a robust internal wait system that can be used to efficiently wait for certain page elements to appear before continuing. You should never need to write a flaky sleep call with Capybara.

With RSpec tests

expect(page).to have_css('#new-project')
expect(page).to have_content('New Project')

This will efficiently wait for the #new-project element to exist.

Without RSpec

You can use Capybara's generic has_css?/has_content?/has_xpath? methods to make sure that the page state is correct before continuing on. You probably will want to raise an exception to stop execution if the query for the element returns false.

raise 'element missing!' unless page.has_css?('#new-project')
raise 'element missing!' unless page.has_content?('New Project')

More info

What's next

Once you've added Percy to your Capybara tests, the next step is to add Percy to your CI service.

CI integration overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.