page.find(:table_row, [‘1’, ‘2’]) == page.find(:css, ‘tr:last-of-type’) # => true

find by

page.find(:table_row, ‘A’ => ‘1’) == page.find(:table_row, ‘B’ => ‘2’) # => true

# find by the [href] attribute
page.find_link(href: '/') == page.find_link(text: 'Home') # => true

page.html # => '<div id="element" data-attribute="value">Content</div>'

# find by the [id] attribute
page.find(id: 'element') == page.find(text: 'Content') # => true

# find by the [data-attribute] attribute
page.find(:element, 'data-attribute': /value/) == page.find(text: 'Content') # => true

page.html # => '<input type="checkbox">'

# find by the absence of the [checked] attribute
page.find_field(checked: false) == page.find_field(unchecked: true) # => true

The predicate block is always optional. When there are results for a selector query, the block is called with each item in the result set. When the block evaluates to true, the item is included from the result set. Otherwise, the item is excluded:

page.html # => '<input role="switch" type="checkbox" checked>'

switch = page.find_field { |input| input["role"] == "switch" }
field = page.find_field(checked: true)

switch == field # => true

Matching

It is possible to customize how Capybara finds elements. At your disposal are two options, Capybara.exact and Capybara.match.

Exactness

Capybara.exact and the exact option work together with the is expression inside the XPath gem. When exact is true, all is expressions match exactly, when it is false, they allow substring matches. Many of the selectors built into Capybara use the is expression. This way you can specify whether you want to allow substring matches or not. Capybara.exact is false by default.

For example:

click_link("Password") # also matches "Password confirmation"
Capybara.exact = true
click_link("Password") # does not match "Password confirmation"
click_link("Password", exact: false) # can be overridden

Strategy

Using Capybara.match and the equivalent match option, you can control how Capybara behaves when multiple elements all match a query. There are currently four different strategies built into Capybara:

1. first: Just picks the first element that matches.
2. one: Raises an error if more than one element matches.
3. smart: If exact is true, raises an error if more than one element matches, just like one. If exact is false, it will first try to find an exact match. An error is raised if more than one element is found. If no element is found, a new search is performed which allows partial matches. If that search returns multiple matches, an error is raised.
4. prefer_exact: If multiple matches are found, some of which are exact, and some of which are not, then the first exactly matching element is returned.

The default for Capybara.match is :smart. To emulate the behaviour in Capybara 2.0.x, set Capybara.match to :one. To emulate the behaviour in Capybara 1.x, set Capybara.match to :prefer_exact.

Transactions and database setup

Note: Rails 5.1+ “safely” shares the database connection between the app and test threads. Therefore, if using Rails 5.1+ you SHOULD be able to ignore this section.

Some Capybara drivers need to run against an actual HTTP server. Capybara takes care of this and starts one for you in the same process as your test, but on another thread. Selenium is one of those drivers, whereas RackTest is not.

If you are using a SQL database, it is common to run every test in a transaction, which is rolled back at the end of the test, rspec-rails does this by default out of the box for example. Since transactions are usually not shared across threads, this will cause data you have put into the database in your test code to be invisible to Capybara.

Cucumber handles this by using truncation instead of transactions, i.e. they empty out the entire database after each test. You can get the same behaviour by using a gem such as database_cleaner.

Asynchronous JavaScript (Ajax and friends)

When working with asynchronous JavaScript, you might come across situations where you are attempting to interact with an element which is not yet present on the page. Capybara automatically deals with this by waiting for elements to appear on the page.

When issuing instructions to the DSL such as:

click_link('foo')
click_link('bar')
expect(page).to have_content('baz')

If clicking on the foo link triggers an asynchronous process, such as an Ajax request, which, when complete will add the bar link to the page, clicking on the bar link would be expected to fail, since that link doesn’t exist yet. However, Capybara is smart enough to retry finding the link for a brief period of time before giving up and throwing an error. The same is true of the next line, which looks for the content baz on the page; it will retry looking for that content for a brief time. You can adjust how long this period is (the default is 2 seconds):

Capybara.default_max_wait_time = 5

Be aware that because of this behaviour, the following two statements are not equivalent, and you should always use the latter!

# Given use of a driver where the page is loaded when visit returns
# and that Capybara.predicates_wait is `true`
# consider a page where the `a` tag is removed through AJAX after 1s
visit(some_path)
!page.has_xpath?('a')  # is false
page.has_no_xpath?('a')  # is true

First expression:

• has_xpath?('a') is called right after visit returns. It is true because the link has not yet been removed
• Capybara does not wait upon successful predicates/assertions, therefore has_xpath? returns true immediately
• The expression returns false (because it is negated with the leading !)

Second expression:

• has_no_xpath?('a') is called right after visit returns. It is false because the link has not yet been removed.
• Capybara waits upon failed predicates/assertions, therefore has_no_xpath? does not return false immediately
• Capybara will periodically re-check the predicate/assertion up to the default_max_wait_time defined
• after 1s, the predicate becomes true (because the link has been removed)
• The expression returns true

Capybara’s RSpec matchers, however, are smart enough to handle either form. The two following statements are functionally equivalent:

expect(page).not_to have_xpath('a')
expect(page).to have_no_xpath('a')

Capybara’s waiting behaviour is quite advanced, and can deal with situations such as the following line of code:

expect(find('#sidebar').find('h1')).to have_content('Something')

Even if JavaScript causes #sidebar to disappear off the page, Capybara will automatically reload it and any elements it contains. So if an AJAX request causes the contents of #sidebar to change, which would update the text of the h1 to “Something”, and this happened, this test would pass. If you do not want this behaviour, you can set Capybara.automatic_reload to false.

Using sessions

Capybara manages named sessions (:default if not specified) allowing multiple sessions using the same driver and test app instance to be interacted with. A new session will be created using the current driver if a session with the given name using the current driver and test app instance is not found.

Named sessions

To perform operations in a different session and then revert to the previous session

Capybara.using_session("Bob's session") do
   #do something in Bob's browser session
end
 #reverts to previous session

To permanently switch the current session to a different session

Capybara.session_name = "some other session"

Using sessions manually

For ultimate control, you can instantiate and use a Session manually.

require 'capybara'

session = Capybara::Session.new(:webkit, my_rack_app)
session.within("form#session") do
  session.fill_in 'Email', with: 'user@example.com'
  session.fill_in 'Password', with: 'password'
end
session.click_button 'Sign in'

XPath, CSS and selectors

Capybara does not try to guess what kind of selector you are going to give it, and will always use CSS by default. If you want to use XPath, you’ll need to do:

within(:xpath, './/ul/li') { ... }
find(:xpath, './/ul/li').text
find(:xpath, './/li[contains(.//a[@href = "#"]/text(), "foo")]').value

Alternatively you can set the default selector to XPath:

Capybara.default_selector = :xpath
find('.//ul/li').text

Capybara provides a number of other built-in selector types. The full list, along with applicable filters, can be seen at built-in selectors

Capybara also allows you to add custom selectors, which can be very useful if you find yourself using the same kinds of selectors very often. The examples below are very simple, and there are many available features not demonstrated. For more in-depth examples please see Capybaras built-in selector definitions.

Capybara.add_selector(:my_attribute) do
  xpath { |id| XPath.descendant[XPath.attr(:my_attribute) == id.to_s] }
end

Capybara.add_selector(:row) do
  xpath { |num| ".//tbody/tr[#{num}]" }
end

Capybara.add_selector(:flash_type) do
  css { |type| "#flash.#{type}" }
end

The block given to xpath must always return an XPath expression as a String, or an XPath expression generated through the XPath gem. You can now use these selectors like this:

find(:my_attribute, 'post_123') # find element with matching attribute
find(:row, 3) # find 3rd row in table body
find(:flash_type, :notice) # find element with id of 'flash' and class of 'notice'

Beware the XPath // trap

In XPath the expression // means something very specific, and it might not be what you think. Contrary to common belief, // means “anywhere in the document” not “anywhere in the current context”. As an example:

page.find(:xpath, '//body').all(:xpath, '//script')

You might expect this to find all script tags in the body, but actually, it finds all script tags in the entire document, not only those in the body! What you’re looking for is the .// expression which means “any descendant of the current node”:

page.find(:xpath, '//body').all(:xpath, './/script')

The same thing goes for within:

within(:xpath, '//body') do
  page.find(:xpath, './/script')
  within(:xpath, './/table/tbody') do
  ...
  end
end

Configuring and adding drivers

Capybara makes it convenient to switch between different drivers. It also exposes an API to tweak those drivers with whatever settings you want, or to add your own drivers. This is how to override the selenium driver configuration to use chrome:

Capybara.register_driver :selenium do |app|
  Capybara::Selenium::Driver.new(app, :browser => :chrome)
end

However, it’s also possible to give this configuration a different name.

# Note: Capybara registers this by default
Capybara.register_driver :selenium_chrome do |app|
  Capybara::Selenium::Driver.new(app, :browser => :chrome)
end

Then tests can switch between using different browsers effortlessly:

Capybara.current_driver = :selenium_chrome

Whatever is returned from the block should conform to the API described by Capybara::Driver::Base, it does not however have to inherit from this class. Gems can use this API to add their own drivers to Capybara.

The Selenium wiki has additional info about how the underlying driver can be configured.