Capybara Turbolinks

Extends Capybara with methods that mitigate race conditions introduced by Turbolinks caching.

Turbolinks is a page loading mechanism introduced in Rails 4. It's default behaviour is to cache pages on the client side, so that page loading appears extremely fast. This caching (and Turbolinks itself) can be problematic; the shopify team decided to disable caching entirely. We decided to keep the page caching, because it was so fast. However, we experienced race conditions in our integration tests.

From a Capybara and integration test point of view, the caching is problematic because it loads the page twice; once with the cached page, and a second time with the actual page from the server.

This causes issues with integration tests that block until they see certain page content or selectors, because the integration tests continue before the actual page has been loaded from the server.

This gem's solution is to add a small amount of JavaScript code in the test environment that adds and removes classes to the body tag that correspond to the Turbolinks page lifecycle. This allows us to use Capybara #has_css? to block until we have detected that the Turbolinks request is complete.

Installation

Add this line to your application's Gemfile:

gem 'capybara_turbolinks', group: :test

And then execute:

$ bundle

Or install it yourself as:

$ gem install capybara_turbolinks

This gem requires the inclusion of some JavaScript code. Since the gem is in the :test group in the Gemfile, you'll have to conditionally include the JavaScript depending on the environment. The easiest way to do this is to rename your application.js file to application.js.erb (or application.coffee.erb) and include a guard for the asset like so:

# app/assets/application.js.erb

<% if Rails.env.test? %>
 <%= require_asset 'capybara_turbolinks.js' %>
<% end %>

Otherwise, if you've installed the gem in all environments you can include the JavaScript normally:

// app/assets/application.js

//= require capybara_turbolinks

This gem actually check the environment anyway, so even if you include the JavaScript in all environments it will only exist in the test environment.

Usage

This gem extends Capybara by adding two additional methods:

Capybara::Node::Actions#click_turbolink

and

Capybara::Node::Element#turboclick

When you are clicking a link that triggers turbolinks, you will need to use one of the above methods. For example:

  visit root_path
  click_turbolink 'View all deals'

Or when you are finding an element to click on:

  visit root_path
  find('a.all-deals').turboclick

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Loft47/capybara_turbolinks.

License

The gem is available as open source under the terms of the MIT License.