Let’s Talk About Drivers

Capybara drivers

To understand what Capybara is doing and what we need to do to make JavaScript integration testing work, we need to know about drivers. The driver is the part of Capybara that actually manages a web page as a series of DOM elements. The Capybara query language interacts with the driver, telling it to click a button or fill a form element or querying the driver to return DOM elements that match a selector and some other criteria.

The Rack::Test driver

Capybara’s default driver is called Rack::Test. It’s relatively simple and relatively fast. The Rack::Test is written in Ruby and maintains its own DOM element tree. It’s also dependent on Rack, the web stack that underlies nearly all Ruby web frameworks(not only Rails but also Sinatra). The Rack::Test has been great for our purposes so far, but it has some limitations. The most relevant of those for us is that Rack::Test doesn’t have a JavaScript interpreter and ignores any JavaScript in the output. Once our code depends on JavaScript to do anything, Rack::Test is no longer useful.

JavaScript drivers

If we’re web developers, there’s about a 100% chance that we have multiple powerful JavaScript runtime interpreters on the computer in the form of web browsers. Capybara allows the use of other drivers that interact with the JavaScript interpreters designed for web browsers. Capybara still manages the query language but hands over the drivers’ queries and actions, which automates the actions using the full web rendering engine, including JavaScript.

Until 2017, the three most commonly used JavaScript drivers for Capybara were:

1. Selenium

2. Capybara-Webkit

3. Poltergeist

Selenium

Selenium is the oldest Capybara drive. Capybara ships with support for it. It differs from the other two in that it is a toolkit designed to automate a browser that is already installed on the computer Capybara can be used to control. That is to say that by default when we run Selenium tests, we’ll see a browser window open, and the interactions actually play out in the window. While this has a certain comforting concreteness to it, it’s also kind of slow.

Poltergeist and Capybara-webkit

Poltergeist and capybara-webkit are tools that extract the WebKit rendering engine used in the Safari browser into a standalone tool designed to run “headless,” meaning without a window. While capybara-webkit and Poltergeist typically run faster than Selenium, they are both somewhat tricky to install and notoriously a little flaky to run.

Chrome driver

The Chrome browser team recently released tools that allow Chrome to be run headless. In fact, as we write this, the maintainer for PhantomJS, which is a key dependency of Poltergeist, is stepping down because of headless Chrome. As of Capybara 2.15, there are default drivers for :selenium-chrome and :selenium-headless-chrome.

To use these drivers, we need a gem and a background application.

Selenium-webdriver gem

The gem is selenium-webdriver, and as of Rails 5.1, it is part of the Rails default gem set. The background application is ChromeDriver, which is basically the transfer protocol between Selenium and Chrome. On Mac OS, we can install it with homebrew using brew install chromedriver. Installation instructions for other platforms can be found online.

We’ll use :selenium-headless-chrome. Here’s the configuration we can put into the existing Capybara configuration file: