---
title: "Feature Test with Headless Chrome and Capybara"
description: "Using ChromeDriver to use Headless Chrome with Capybara."
canonical: https://oozou.com/blog/feature-test-with-headless-chrome-and-capybara-24
locale: en
date: 2017-07-17
author: "OOZOU Team"
---

# Feature Test with Headless Chrome and Capybara

> Using ChromeDriver to use Headless Chrome with Capybara.

Published: 2017-07-17 · Author: OOZOU Team (Engineering) · 3 min read

[Capybara](https://github.com/teamcapybara/capybara) is one of the most popular feature testing framework in the Ruby on Rails community. I’ve been pretty happy using it with headless browser like PhantomJS.

However, Google recently released Headless Chrome with their 59 version of it’s Chrome browser and it’s performance is really [impressive](https://hackernoon.com/benchmark-headless-chrome-vs-phantomjs-e7f44c6956c). I decided switch to it on my current project and updated my Capybara configuration to supports it and have been really satisfied with the performance improvement.

**ChromeDriver installation**

Running your feature specs requires you to [install Chrome](https://support.google.com/chrome/answer/95346?co=GENIE.Platform%3DDesktop&hl=en-GB) (v59 and above) and [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/downloads) (v2.30 and above). For MacOs user, you can easily install/update your ChromeDriver via [Homebrew](https://brew.sh/) by running one of these command in your Terminal:

```
# install the latest version
brew install chromedriver
# update existing chrome driver
brew upgrade chromedriver
lang-bash
```

You can validate your installation by running:

```
chromedriver -v
# It should display the latest/specify version like so
#=> ChromeDriver 2.33.506106 (8a06c39c4582fbfbab6966dbb1c38a9173bfb1a2)
lang-bash
```
Capybara Configuration
I normally put my spec configuration in spec/supports/ and import them in spec_helper so that the configuration file could be named properly and my Capybara configuration is not an exception.

```
# frozen_string_literal: true

require 'capybara/rspec'

IS_DEBUG_MODE = -> { ENV['DEBUG'].present? ? :chrome : :headless_chrome }

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

Capybara.register_driver :headless_chrome do |app|
  options = ::Selenium::WebDriver::Chrome::Options.new
  options.add_argument 'headless'
  Capybara::Selenium::Driver.new app, browser: :chrome, options: options
end

Capybara.configure do |config|
  config.default_max_wait_time = 30
  config.default_driver = IS_DEBUG_MODE.call
  config.javascript_driver = IS_DEBUG_MODE.call
end
lang-ruby
```

This configuration sets Capybara to use headless_chrome as the default JavaScript driver and opens Chrome browser when the DEBUG is export to your ENV. This also enables you to write feature test for pages that is rendered by [React.js](https://reactjs.org/) which is slick!

> **_Update 4/10/17_**_RSpec has just_ [_released 3.7 version_](http://rspec.info/blog/2017/10/rspec-3-7-has-been-released/) _last month and the configuration for integration test is a lot cleaner. Here’s the snippet:_

```
# System tests use Rack::Test for non JS test and headless Chrome for JS specs
  config.before(:each, type: :system) do
    driven_by :rack_test
  end

  config.before(:each, type: :system, js: true) do
    driven_by :selenium_chrome_headless
  end
lang-ruby
```

_Thanks_ [_Michael Kohl_](https://medium.com/u/b3d5a4fbc3f?source=post_page-----6310b86ef34c----------------------) _who updated me with this. ❤_

**CI configuration**

If you have the right version of Chrome and ChromeDriver installed on your CI, you should be able to run your tests normally.

For CircleCI users, like me, the current CircleCI machine uses older version of Chrome and ChromeDriver which does not support Headless Chrome.

**Has ChromeDriver been updated on the Ubuntu 14.04 (Trusty) image?**Hi, We started observing build failures 2 hours ago due to a mismatch between the Chrome and ChromeDriver versions. We…discuss.circleci.com

To fix this, you need to add a script to remove and reinstall newer Chrome and ChromeDriver. (At least until they update the version)

```
dependencies:
  pre:
    # install chrome
    - wget -N https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb -P ~/
    - sudo dpkg -i --force-depends ~/google-chrome-stable_current_amd64.deb
    - sudo apt-get -f install -y
    - sudo dpkg -i --force-depends ~/google-chrome-stable_current_amd64.deb
    - sudo rm /usr/local/bin/chromedriver
    # install chromedriver
    - wget -N http://chromedriver.storage.googleapis.com/$CHROME_DRIVER_VERSION/chromedriver_linux64.zip -P ~/
    - unzip ~/chromedriver_linux64.zip -d ~/
    - rm ~/chromedriver_linux64.zip
    - sudo mv -f ~/chromedriver /usr/local/bin/chromedriver
    - sudo chown root:root /usr/local/bin/chromedriver
    - sudo chmod 0755 /usr/local/bin/chromedriver
lang-yaml
```

**Wrapping Up**

As I told you before, Headless Chrome performance is really satisfying and debugging it with this configuration is a breeze. I really recommend you to try it with your feature spec.

---

Contact OOZOU: hello@oozou.com · +66 2544 0000 · https://oozou.com/contact

More for AI agents: https://oozou.com/llms.txt · every page has a markdown twin at its URL plus ".md"