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
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 snapshotoptions
- 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
@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
@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
Updated over 1 year ago
Once you've added Percy to your Capybara tests, the next step is to add Percy to your CI service.