Upgrading to Percy Capybara v4


Covered in this doc

Steps to migrate from older versions of Percy Capybara to Percy Capybara version 4

Percy Capybara version 4 introduces improvements to snapshotting and simplifies using Percy in your Capybara tests.

Note: If you're new to Percy Capybara, and are looking to integrate it into your tests for the first time, please refer to the Capybara docs instead.


What's new in version 4

Percy Capybara version 4 is based on the Percy agent. The agent is a process that runs alongside your tests, creating snapshots and uploading them to Percy on your behalf.

The agent understands how to snapshot complex modern web pages out of the box, without requiring you to use custom loaders or pass special parameters to your snapshots. It also processes and uploads the snapshots to Percy for you outside of your test process.

Migration steps


v4 introduces a much simpler API, and removes many legacy code paths. It should only take you a few minutes to upgrade from v3 to v4, and is mostly removing or renaming a few calls.

Please follow each of the steps below carefully.


Update your Gemfile to depend on the newer percy-capybara:

gem 'percy-capybara', '~> 4.0.0'

Install the Percy agent using npm.


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

To install it 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. You can invoke this binary using its full path, or by calling npx percy (npx is a Node utility that lets you execute package binaries).

Update your code

1. Use Percy.snapshot

  • Require the Percy module in your test helper file: require 'percy'
  • Replace all calls to Percy::Capybara.snapshot(page, <options>) with Percy.snapshot(page, <options>).
# Rename:
# to -->

You can leave most of the options unchanged, except for minimum_height, which now becomes min_height. (The is_iframe option is no longer needed and will be ignored.)

For details on the parameters and usage of Percy.snapshot(...), refer to the Usage section of the Percy Capybara documentation.

2. Use .percy.yml config

If you have used Percy.config.default_widths:

# Move this config to .percy.yml:
Percy.config.default_widths = [375, 1280]

You should move this configuration into a .percy.yml file in your root project directory:

version: 1
  widths: [375, 1280]

See Configuration for all configuration options.

3. Remove legacy initializers

You no longer need the initialize or finalize calls at all.

# Remove these lines from spec_helper.rb:

4. Use the new test runner command

The final step in your upgrade is to wrap your test runner command in percy exec -- , e.g. if you're using RSpec:

$ npx percy exec -- rspec

npx is one way to run the percy binary without worrying about its location on your system. You can also execute it by providing the full path to ./node_modules/.bin/percy, or you can use $(npm bin)/percy to dynamically find the path to the binary.

You will still be able to run your tests without wrapping them in percy exec -- , but in that case snapshots will not be uploaded to Percy.

5. Remove other legacy options

  1. Remove any references to Percy::Capybara.use_loader and any custom loaders, they are no longer needed.
  2. Remove any references to Percy.disable! or Percy::Capybara.reset!.
  3. Remove any references to Percy.config.


Percy Capybara version 4 is a major change and is no longer compatible with:

  • The Poltergeist Capybara driver for PhantomJS is no longer supported. If you are using this driver, you'll need to upgrade to use the selenium-webdriver driver instead.
  • Rack::Test snapshots are no longer supported. Tests are now required to be marked js: true and run in a real browser.

For details on switching Capybara drivers, please refer to the Capybara documentation.