The Capybara 2.0.0 beta is out. I’ll walk you through the most important changes, and show you how to upgrade.
The bad news: If you upgrade to Capybara 2.0.0, you may have to make some changes to your test suite to get it passing.
The good news: Once you’re compatible with Capybara 2.0.0, you can probably go back and forth between 1.1.2 and 2.0.0 without any changes, should you decide that 2.0.0 is not for you (yet).
Also, Capybara 2.0 will likely drop Ruby 1.8.7 compatibility.
How to Upgrade
The latest 2.0.0 beta release is two months old. I recommend you use Capybara master, since it has some fixes, and is generally in better shape than the beta:
1 2 3
Update: Capybara master is having some changes that still need to be
synchronized with rspec-rails
(#809). If you are using
RSpec, specify the
ref: as above in the meantime.
There is one major change that will likely cause breakage in your test suite, and that is how Capybara handles ambiguous matches:
find method, as well as most actions like
now raise an error if more than one element is found. While in Capybara 1.1.2,
it would simply select the first matching element, now the matches have to be
Here is a common way this can break your test suite:
fill_in will fail now, because searching for “Password” will match
both the “Password” label, and the “Password confirmation” label (as a
sub-string), so it’s not unambiguous.
The best way to fix this is to match against the name or id attribute – such
fill_in 'password', with: 'secret' – or, when there’s no good name or id,
.js-password-confirmation classes. (The
prefix is for behavioral classes as recommended in the
I find that using
.js- classes instead of matching against English text is
actually a good practice in general to keep your tests from getting brittle.
Should you absolutely need to get the old behavior, you can use the
You can assume that these don’t affect you unless something breaks:
The RackTest driver – that’s the fast default driver, when you’re not usingUpdate: The behavior matches Capybara 1.1.2 again (#793), so long as you have
js: true– no longer respects Rails’s
data-methodattribute unless you tell it to.
require 'capybara/rails'(like you should in any case).
find(:my_id)symbol syntax is no longer supported (#783). Write
find('#my_id')instead, as recommended in the documentation.
has_content?checks for substrings in
text, rather than using XPath
contains(...)expressions. This means improved whitespace normalization, and suppression of invisible elements, like
unselectdon’t allow for substring matches anymore.
Capybara.prefer_visible_elementsare no longer needed and have been removed.
wait_untilhave been removed, as well as the Selenium driver’s
:resynchronizeoption. In general, if you have to wait for Ajax requests to come back, like before you should try using
page.should have_cssto search for some change on the page that indicates that the request has completed. The check will essentially act as a gate for the Ajax request, as it will poll repeatedly until the condition is true. If that doesn’t work for you, you could implement your own simple
wait_forhelper method (see e.g. this gist). See also this thread about
These won’t break your code when you upgrade, but they’re sweet new additions:
Lots of new selectors, like
find(:field, '...'), etc. These can come in handy if you find yourself doing intricate node finding. Check the
add_selectorcalls in lib/capybara/selector.rb for a list.
Any speed bumps I forgot to mention? Leave a comment.
Even better, send a pull request! We’ll love you for it.