Percy Capybara on GitHub

Percy Capybara is a library for integrating Percy's visual regression testing into your existing Capybara feature tests using any Ruby framework – including Rails, Sinatra, etc.

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.

Installation

📘
Make sure you have completed Setup of your CI service first. You can also test Percy in your local development environment.

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.

Quick Setup

These are the basic steps for adding visual testing to your Capybara test suite:

Import percy into your test.
Call Percy.snapshot(page) wherever you want to save a snapshot from your test.
Wrap your test runner command in percy exec -- , e.g. percy exec -- rspec.

Next, we will go through each of these steps in detail.

Setup

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 example.com homepage' do
    visit 'https://example.com'
    Percy.snapshot(page, name: 'example.com homepage')
  end
end

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!

Usage

Percy.snapshot(page)
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.

Examples

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.

Contributing

Fork it (https://github.com/percy/percy-capybara/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Throw a ★ on it!