Running capybara-webkit Specs with Jenkins CI

How to get WebKit-driven integration tests working in a headless Linux environment.

The capybara-webkit gem is a great way to test the JavaScript aspects of a Rails application. I wanted to take my tests to the next level by automating them with the Jenkins continuous integration server, but getting WebKit to run in a headless Linux environment was a bit tricky. Here’s how I did it.

My setup

I have Jenkins deployed with the following stack:

1 Install Qt libraries

As you may have already encountered on your development machine, the capybara-webkit gem won’t even install unless you have the necessary Qt libraries.

$ gem install capybara-webkit
Fetching: capybara-webkit-1.0.0.gem (100%)
Building native extensions.  This could take a while...
ERROR:  Error installing capybara-webkit:
  ERROR: Failed to build gem native extension.

    /home/deployer/.rbenv/versions/2.0.0-p247/bin/ruby extconf.rb
Command 'qmake -spec linux-g++' not available

Installing these libraries involves a different set of commands for each operating system, and is documented on the capybara-webkit GitHub wiki. For my Ubuntu 14.04 LTS setup, here’s what I had to do:

# as root
aptitude -y install libqt4-dev libqtwebkit-dev

2 Install xvfb and use it to invoke rspec

The tricker problem is that WebKit requires a display.

bundle exec rake spec
webkit_server: cannot connect to X server

This isn’t an issue when running tests on my Mac, but on a headless Linux continuous integration server, a workaround is needed.

This workaround is a utility called Xvfb (“X virtual frame buffer”).

# as root
aptitude -y install xvfb

To use it, I had to change how I invoke specs/tests by wrapping the rake command with xvfb-run. Here’s an example:

if type xvfb-run; then
  DISPLAY=localhost:1.0 xvfb-run bundle exec rake test
  bundle exec rake test

Now my capybara-webkit tests run great on my CI server.

More best practices for Rails and Jenkins

If you’re setting up Jenkins for the first time, or looking for ways to improve your existing Rails CI approach, check out these additional resources: