CapybaraExtensions

Capybara has an intuitive API which mimics the language of an actual user. This library extends Capybara's finders and matchers with additional methods for interacting with tables, lists, and list items, as well as many HTML5 elements.

Installation

Add this line to your application's Gemfile to install from RubyGems:

gem 'capybara-extensions'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capybara-extensions

Setup

Ensure that Capybara is properly setup inside of your project. You can view the Capybara README.md here.

Require capybara-extensions (in your test helper file if this is a Rails project):

require 'capybara-extensions'

Usage

CapybaraExtensions extends Capybara's finders and matchers. Our goal is to cull many of the find statements from our tests and remove the verbose CSS and xpath locators that come along with them. Jonas Nicklas, who maintains Capybara, has an excellent post about augmenting Capybara with helper methods; this is what CapybaraExtensions aims to do.

You can read more about the library in this blog post.

Finders

The library contains helper methods for finding elements like form, table, and li, as well as many HTML5 elements like article, aside, footer, header, and nav. A complete reference of the finders added by CapybaraExtensions is available at Rubydoc.info.

So the following code:

within find('form#session-new') do
  ...
end

becomes the following:

within form('Login') do
  ...
end

Each find method also has a corresponding first method. So when you have multiple article elements on a page with the text 'Lorem ipsum,' you can call first_article('Lorem ipsum') without returning an ambiguous match in Capybara. If you don't supply an argument to #first_article, it will return the first article regardless of the article's content.

In instances when you have lists or tables and you'd like to verify the content of a specific li or tr, CapybaraExtensions allows you to target the nth occurence of the element via #list_item_number and #row_number. Counting is 1-based, rather than 0-based, so given the following HTML:

<ul>
  <li>John Doe</li>
  <li>Jane Doe</li>
  <li>Juan Doe</li>
</ul>

You can find the second li with:

list_item_number(2) # => 'Jane Doe'

You can also pass a negative number to these methods, and it will look for the nth occurence from the last element (be it a li or tr). Use these methods for testing how elements are being ordered.

Matchers

CapybaraExtensions extends Capybara's matchers with methods for verifying the presence of images, the value of input fields, and the presence of meta tags. All of these methods return a boolean. A complete reference of the matchers added by CapybaraExtensions is available at Rubydoc.info.

CapybaraExtensions comes with a #has_field_value? method which checks the value of a form field. Ensuring that your records save and update correctly should be the domain of your unit tests, however this method can come in handy when you're not persisting data to the back-end. For example, after performing a search, you may want to ensure that the query persists in the search field after redirect.

within form('Search') do
  has_field_value?('search', 'capybara images')
end
# => true

Asserting that text appears on the page is easy with Capybara's #has_content? method; asserting that a particular image appears has always been a little tougher. #has_image? takes a hash with the src and/or alt attributes you're looking for. You can pass a string for either of these keys, and an instance of Regexp to the src attribute when you want to hone in on a portion of the URL.

page.has_image?(src: 'http://gallery.photo.net/photo/8385754-md.jpg',
alt: 'Capybara')
# => true

Versioning

This gem follows semantic versioning.

Contributing

Please see our contribution guidelines on how to properly submit issues and pull requests.

Legal

Licensed under the MIT license.