Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

Percy Anywhere is a simple wrapper that allows you to easily integrate Percy's visual tests with any `localhost` server or remote web app server.


  • `percy-capybara` gem.

  • `poltergeist` gem, which requires [PhantomJs](🔗) to be installed.

  • A directory of compiled asset files.

  • A local or remote server running the app.

# Installation

Make sure you have completed [Setup](🔗) of your CI service first. You can also test Percy in your [local development](🔗) environment.

## Without Bundler

You can simply install the required gems globally:

## With Bundler

Add the following to your `Gemfile`:

Then, run:

# Usage

Percy Anywhere does not require Rails or any test framework like RSpec. It simply uses the [Capybara](🔗) library and a small Ruby script you write to control a web app.

## Example script

Let's create a file called `snapshots.rb`:

  • `server` is a URL pointing to the local or remote host, such as `http://localhost:8080`.

  • `assets_dir` is an absolute path to a directory of compiled static assets. These can be compiled by any asset pipeline tool, such as Webpack/Broccoli.js/etc.

  • `assets_base_url` (optional): the path where your webserver hosts compiled assets, such as `/assets`. Default: `/`

Now, run:

If you used the Bundler installation method, run:

_Done!_ 🚀 Each time the script is run, Percy snapshots are taken and uploaded for rendering and processing. The script will output a link to the build to view any visual diffs.

## Interacting with elements

This script can be expanded with any complex behavior that interacts with the page. You can use all of the available [Capybara actions](🔗) to interact with the page.

_Clicking on a button_

_Clicking on an element by selector_

See the [Capybara docs](🔗) for many more interactions, best practices, and usage examples.

## Waiting for elements

See [Best Practices](🔗) .

## Responsive visual diffs

You can use Percy [responsive visual diffs](🔗) to test pages at different CSS breakpoints.

Simply set the breakpoint configuration:

With the above configuration, all snapshots will render at both mobile and desktop breakpoints by default.

You can also override widths per-snapshot:

If you're testing components instead of full pages, you may also want to set the `minimum_height` argument to override the default of 1024px. Note that `minimum_height` sets the default viewport height and the resulting screenshot may still be be larger if the page's content height is larger.

# Example app

A working example of this setup can be found here: [https://github.com/percy/example-percy-anywhere](🔗)

# Other resources

  • [Percy::Capybara::Anywhere source](🔗)

  • [Percy::Capybara Reference](🔗) on RubyDoc