### [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:

And then run:

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:

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:

1. Import `percy` into your test.

2. Call `Percy.snapshot(page)` wherever you want to save a snapshot from your test.

3. 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:

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

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:

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

`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

# 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

1. Fork it (<https://github.com/percy/percy-capybara/fork>)

2. Create your feature branch (`git checkout -b my-new-feature`)

3. Commit your changes (`git commit -am 'Add some feature'`)

4. Push to the branch (`git push origin my-new-feature`)

5. Create a new Pull Request

[Throw a ★ on it!](🔗)