Webrat

Integration tests are probably more important then anything else, and using a library like Webrat makes them very easy to do. […] Webrat rocks for integration tests.

—Gregg Pollack, Rails Envy

Webrat is a Ruby integration test library. It has two main purposes:

• Implement a browser simulator to allow fast, reliable integration testing (sans JavaScript) without requiring Selenium or Watir and their associated issues.
• Define a ubiquitous DSL for describing interacting with a web application from the perspective of an end user.

It's maintained by Bryan Helmkamp.

class SignupTest < ActionController::IntegrationTest
 
  def test_trial_account_sign_up
    visit home_path
    click_link "Sign up"
    fill_in "Email", :with => "good@example.com"
    select "Free account"
    click_button "Register"
    assert_contain "Thanks for joining"
  end
 
end

Behind the scenes, Webrat will ensure:

• If a link, form field or button is missing, the test will fail.
• If a URL is invalid, the test will fail.
• If a page load or form submission is unsuccessful, the test will fail.
• The page the user is sent to after registering says “Thanks for joining”

Webrat's long term goal is to become a unified API for driving interactions with Web applications from Ruby. To this end, it supports most popular Ruby testing frameworks:

• Test::Unit
• RSpec
• Shoulda
• Cucumber

It also works with multiple Ruby web application frameworks:

• Rails
• Merb
• Sinatra
• Coming Soon – Anything that uses Rack

Finally, Webrat supports swappable adapters. An adapter in this context is the tool Webrat uses to interact with the application under test. Currently supported are:

• Webrat's browser simulator – This is the oldest, and most widely used mode (also the default). It leverages Nokogiri to parse the XHTML responses of the application without needing a desktop browser. It's invisible and fast.
• Webrat::Selenium – This is useful when you need to exercise JavaScript interactions, so you can't avoid the browser dependency. The Webrat API works, and Webrat tries to minimize the pain points of raw selenium like concurrency issues and process dependencies.
• Mechanize – Webrat's adapter for the Mechanize library opens the Webrat API up to be used with any application, regardless of where it's running, without opening up a desktop browser. You could even build a scraper with it.

Additional adapters, like Celerity are in the works.

• Webrat's RDoc is available on Git RDoc.

• The start of a Webrat wiki is taking form on GitHub.

Users of Debian Linux (e.g. Ubuntu) need to run:

$ sudo apt-get install libxslt1-dev libxml2-dev.

Otherwise the Nokogiri gem, which Webrat depends on, won't install properly.

To install the latest release as a gem:

$ sudo gem install webrat

To install the latest code as a plugin: (_Note:_ This may be less stable than using a released version)

script/plugin install git://github.com/brynary/webrat.git

In your test_helper.rb or env.rb (for Cucumber) add:

require "webrat"
 
Webrat.configure do |config|
  config.mode = :rails
end

In spec_helper.rb (for RSpec), you need the above, plus an addition in the Spec::Runner configuration, like so:

Spec::Runner.configure do |config|
  include Webrat::Methods
...

• Mailing List on Google Groups
• Bugs/Tickets on Lighthouse
• IRC channel on Freenode
• Twitter