Capybara

👍

Covered in this doc

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

🚧

Percy Capybara v5

This documentation is for Percy Capybara version 5.x and above. Earlier versions of Percy Capybara had a different, and incompatible, API. See the upgrading section to learn how to upgrade to v5.x

You can find the v4 docs here

Installation

npm install @percy/cli:

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

gem install percy-capybara package:

$ gem install percy-capybara

Usage

In your test setup file, require percy/capybara. For example if you're using rspec, you would add the following to your spec_helper.rb file:

require 'percy/capybara'

Now you can use page.percy_snapshot to capture snapshots.

Note: you may need to add js: true to your specs, depending on your driver setup

describe 'my feature, type: :feature do
  it 'renders the page' do
    visit 'https://example.com'
    page.percy_snapshot('Capybara snapshot')
  end
end

Running the test above normally will result in the following log:

[percy] Percy is not running, disabling snapshots

When running with percy exec, and your project's PERCY_TOKEN, a new Percy build will be created and snapshots will be uploaded to your project.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [test command]
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Snapshot taken "Capybara example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Configuration

page.snapshot(name[, options])

• name (required) - The snapshot name; must be unique to each snapshot
• options - See per-snapshot configuration options

Global Configuration

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

Upgrading

Automatically with @percy/migrate

We built a tool to help automate migrating to the new CLI toolchain! Migrating can be done by running the following commands and following the prompts:

$ npx @percy/migrate
? Are you currently using percy-capybara? Yes
? Install @percy/cli (required to run percy)? Yes
? Migrate Percy config file? Yes
? Upgrade SDK to percy-capybara@^5.0.0? Yes
? The Capybara API has breaking changes, automatically convert to the new API? Yes

This will automatically run the changes described below for you, with the exception of changing the require.

Manually

Require change

The name of the require has changed from require 'percy' to require 'percy/capybara'. This is to avoid conflict with our Ruby Selenium SDK's require statement.

API change

The previous version of this SDK had the following function signature:

Percy.snapshot(driver, name, options)

v5.x of this SDK has a significant change to the API. There no longer is a stand alone module to call and you no longer need to pass the page/driver. It's available on the current Capybara session (page):

page.percy_snapshot(name, options)

If you were using this SDK outside of Capybara, you'll likely find the Ruby Selenium SDK a better fit

Installing @percy/cli & removing @percy/agent

If you're coming from a 4.x version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command. You will also want to uninstall @percy/agent, as it's been replaced by @percy/cli.

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

Migrating config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate

Troubleshooting

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_no_css?/has_no_content?/has_no_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 true.

raise 'element missing!' if page.has_no_css?('#new-project')
raise 'element missing!' if page.has_no_content?('New Project')

More info

• https://github.com/teamcapybara/capybara#querying
• https://github.com/teamcapybara/capybara#asynchronous-javascript-ajax-and-friends

Missing styles

If your screenshots are missing styles and you're using Webpacker to build your apps front end assets, you will need to configure it to extract the CSS when building for tests. By default, Webpack will generate CSS as a blob asset, which cannot be discovered or saved when we're doing asset discovery. In your webpacker config file you will need to specify extract_css: true:

test:
  ...
  # Extract and emit a css file
  extract_css: true