Feature Test with Headless Chrome and Capybara

Using ChromeDriver to use Headless Chrome with Capybara.

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. 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 (v59 and above) and ChromeDriver (v2.30 and above). For MacOs user, you can easily install/update your ChromeDriver via Homebrew by running one of these command in your Terminal:
# install the latest version
brew install chromedriver
# update existing chrome driver
brew upgrade chromedriver

You can validate your installation by running:
chromedriver -v
# It should display the latest/specify version like so
#=> ChromeDriver 2.33.506106 (8a06c39c4582fbfbab6966dbb1c38a9173bfb1a2)

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)

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

Capybara.configure do |config|
  config.default_max_wait_time = 30
  config.default_driver = IS_DEBUG_MODE.call
  config.javascript_driver = IS_DEBUG_MODE.call

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 which is slick!

Update 4/10/17
RSpec has just
released 3.7 version 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

  config.before(:each, type: :system, js: true) do
    driven_by :selenium_chrome_headless

Thanks Michael Kohl 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)

    # 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

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.
Like 162 likes
Tino Thamjarat

Join the conversation

This will be shown public
All comments are moderated

Get our stories delivered

From us to your inbox weekly.