The Capybara API
Even though we have used only four of Capybara’s methods at this point, we have actually explored the most essential parts already. Let’s take a look at more of Capybara’s API.
The methods in the Capybara API can be grouped in six categories: navigating, clicking links and buttons, interacting with forms, querying, finding, and scoping. The following sections list the most common methods. Make sure you consult Capybara’s own documentation for more comprehensive details.
Navigating
|
visit(path) |
Navigates to the page at path, issuing a GET request. |
Clicking Links and Buttons
|
click_link(locator) |
Finds a link by ID or text and clicks it. This may cause Capybara to load a new page. |
|
click_button(locator) |
Finds a button by ID, text, or value and clicks it. This may cause Capybara to submit a form. |
|
click_on(locator) |
Finds a button or link by ID, text, or value and clicks it. |
Interacting with Forms
|
fill_in(locator, {:with => text}) |
Locates a text field or text area and fills it in with the given text. The field can be found via its name, ID, or label text. |
|
choose(locator) |
Finds a radio button and marks it as checked. The radio button can be found via name, ID, or label text. |
|
check(locator) |
Finds a checkbox and marks it as checked. The check box can be found via name, ID, or label text. |
|
uncheck(locator) |
Finds a checkbox and marks it as unchecked. The checkbox can be found via name, ID, or label text. |
|
attach_file(locator, path) |
Finds a file field on the page and attaches a file given its path. The file field can be found via its name, ID, or label text. |
|
select(value, {:from => locator}) |
Finds a select box on the page and selects a particular option from it. If the select box is a multiple select, select can be called multiple times to select more than one option. The select box can be found via its name, ID, or label text. |
Querying
|
page.has_css?(css_selector) |
Checks whether an element identified by CSS or XPath is on the page or inside the current element. |
|
page.has_button?(locator) |
Checks whether an element identified by locator is on the page or inside the current element. |
|
page.has_content?(text) |
Checks whether the page or current node has the given text content, ignoring any HTML tags and normalizing whitespace. |
All of the has_xxx? methods return true or false, and they also have an opposite has_no_xxx? that can be used to verify the absence of elements.
These has_xxx? and has_no_xxx? methods should always be used in conjunction with assertions—either using Minitest or RSpec. For example, to check that the page has the text orange juice, you would write the following using Minitest:
assert(page.has_content?("orange juice"))
Or using RSpec:
expect(page).to have_content("orange juice")
Finding
|
find_field(locator) |
Finds a form field on the page. |
|
find_link(locator) |
Finds a link on the page. |
|
find(selector) |
Finds the matching element on the page using a CSS selector or raises an error. |
|
find(:xpath, selector) |
Uses XPath to find the matching element on the page. You can tell Capybara to use XPath by default with Capybara.default_selector = :xpath. |
|
all(selector) |
Returns all elements (as an Array) matching the given selector. |
A full reference can be found at http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Finders.
All find* methods will poll for a maximum of two seconds until an element is found before it gives up and raises an exception. At first glance, they might seem similar to the has_xxx? and has_xxx? Query methods, but the find* methods do not return true or false. Instead, they return a Capybara::Element object on which you can invoke methods. For example:
| | page.find('#main-nav').click_link('Login') |
If you are familiar with the jQuery JavaScript library, you will find some similarities here.
Scoping
|
within(locator, &block) |
Executes the given block for a particular scope on the page. Finds the first element matching the given locator and executes the block scoped to that element. |
Using scoping can be useful when we want to click, fill in, query, or find elements in a specific area of a page. This can help avoid picking the wrong element if there are several similar elements on the page. For example, if we had more than one Search button on our page and wanted to make sure we were clicking the one inside our form with id="search", we could have scoped it like so:
| | within('#search') do |
| | click_button('Search') |
| | end |
Scoping is a powerful technique, especially for complex pages that have a lot of markup. For simpler pages you may not need it at all—just search globally on the page as we did in our Squeaker examples.