Today we bring you the first in a series of guest posts on our TFG blog. This post is written by Peter Cooper, editor of Ruby Inside and Ruby Weekly.


You’re using Capybara, right?

It’s an acceptance / integration test framework for Ruby that superseded Webrat and makes it easy to automatically interact with Web applications but at the user level. It’s now the de facto way to do request / integration / acceptance testing (seriously, it gets called any or all of these) in Rails 3.

Capybara supports using different ‘drivers’ to run the scenarios you specify and by default it’ll use Rack::Test or Selenium (which uses Firefox’s Gecko engine). capybara-webkit is a library by the guys at Thoughtbot that gives Capybara a WebKit-powered driver using the WebKit implementation in Qt, a popular cross-platform development toolkit.

Why?

Why get WebKit involved with your integration tests at all? Perhaps your userbase is primarily made up of Safari and Chrome users (both WebKit-powered browsers) and you want to focus on them. Or perhaps you’re thorough and want to ensure the JavaScript on your pages works fine with your tests in a WebKit scenario too.

Installation

Here’s the bad news. You need Qt installed in order to install capybara-webkit. If you’re on OS X, grab it from here (pick the Cocoa: Mac binary package – the 206MB version). You can install via homebrew too (using brew install qt), but Thoughtbot says it takes forever (well, almost).

For other platforms, check out Qt’s Downloads page.
If you’re on CentOS, in particular, check this article.

Once you’ve installed the Qt toolkit, add this to your app’s Gemfile:

gem 'capybara-webkit'

Then run bundle and you’re off to the races.

Usage

Once everything’s installed, you can set Capybara’s JavaScript driver to use Webkit by default, by adding this to your normal Capybara config options (or if you have none, in spec/spec_helper.rb in most Rails 3 cases):

Capybara.javascript_driver = :webkit

Then, if you’re using Cucumber you can add the following tag to the header of your scenario to trigger JavaScript usage specifically (it’s not done by default):

@javascript

In regular RSpec code, you can do something like this:

feature "The signup page" do
scenario "should load", :js => true do
visit new_user_registration_path
page.should have_selector("form.user_new")
end
end

You could also use the :driver option to specify :webkit if you want to choose the driver on a per scenario / describe basis. The same applies to @webkit in Cucumber.

If you’re on OS X, when you first run tests using capybara-webkit the OS X firewall might go a little crazy since it works by connecting over a socket. Just approve it and you’re on your way.

You may also have issues if you’re using transaction fixtures. If so, read the “Transactional Fixtures” section of the Capybara README.