Covered in this doc
- Integrating Percy with Capybara feature tests in any Ruby web framework including Rails, Sinatra, etc.
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
$ npm install --save-dev @percy/cli
$ gem install percy-capybara
In your test setup file, require
percy/capybara. For example if you're using rspec, you would add the following to your
Now you can use
page.percy_snapshot to capture snapshots.
Note: you may need to add
js: trueto 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!
name(required) - The snapshot name; must be unique to each snapshot
options- See per-snapshot configuration options
You can also configure Percy to use the same options over all snapshots. To see supported configuration, including widths, read our SDK configuration docs
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 [email protected]^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
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.
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 (
If you were using this SDK outside of Capybara, you'll likely find the Ruby Selenium SDK a better fit
@percy/cli & removing
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
$ npm uninstall @percy/agent $ npm install --save-dev @percy/cli
If you have a previous Percy configuration file, migrate it to the newest version with the
$ percy config:migrate
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.
You can use Capybara's generic
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')
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
test: ... # Extract and emit a css file extract_css: true
Updated about 1 year ago
Once you've added Percy to your Capybara tests, the next step is to add Percy to your CI service.