Webrat - Ruby Acceptance Testing for Web applications

• gitrdoc.com/brynary/webrat
• groups.google.com/group/webrat
• webrat.lighthouseapp.com/
• github.com/brynary/webrat
• #webrat on Freenode

Information about this branch (github.com/johnnyt/webrat)

• This branch adds initial support for Ruhu
• Ruhu is a wrapper for HtmlUnit specifically built for the Webrat API (just like Celerity is built for the Watir API)
• This is just the initial spike, so please let me know what problems you find
• I have only tried this on a Mac (OS 10.5.6) - I have no idea what the support is like for other systems (e.g. Windows)
• I have only tried this on Rails - I have no idea what the support is like for other frameworks (Merb, Sinatra, etc)
• I also included a basic rails app (/rails_testing_app) witch runs through all of the basic Webrat API methods

Getting your Rails site and Cucumber features working with Ruhu

There are a few things that you will need to do in order to get your Rails app working with Ruhu. First - get JRuby installed and working on your system (wiki.jruby.org/wiki/Getting_Started)

Create the file config/environments/ruhu.rb, and put the following in there:

  config.cache_classes = false

  # Log error messages when you accidentally call methods on nil.
  config.whiny_nils = true

  # Show full error reports and disable caching
  config.action_controller.consider_all_requests_local = true
  config.action_controller.perform_caching             = false

  # Disable request forgery protection in test environment
  config.action_controller.allow_forgery_protection    = false

  # Tell Action Mailer not to deliver emails to the real world.
  # The :test delivery method accumulates sent emails in the
  # ActionMailer::Base.deliveries array.
  config.action_mailer.delivery_method = :test

  # Fix application address for HtmlUnit
  Webrat::Ruhu.normalize_application_address

  # This sends all emails to the Webrat::Ruhu::Emails DRB server
  require 'webrat/ruhu/action_mailer'
  Webrat::Ruhu::ActionMailer::Client.start

I’ll get around to expailing the Ruhu::ActionMailer stuff later …

In your database.yml file:

  ruhu:
    adapter: ....

  (Copy your test environment)

In your env.rb file (for Cucumber):

  if ENV["WEBRAT"] =~ /ruhu/i
    Webrat.configure do |config|
      config.application_environment = :ruhu
      config.mode = :ruhu
    end

    Webrat::Ruhu.configure do |config|
      config.log_level = Logger::ERROR
      config.use_viewer = true
      config.page_view_seconds = 0.5
    end

    Webrat::Ruhu::ProcessManager.start_processes
    # Before { Webrat::Ruhu::Base.truncate_database }

  else
    Cucumber::Rails.use_transactional_fixtures

    Webrat.configure do |config|
      config.mode = :rails
      # config.open_error_files = false
    end
  end

A couple of notes about the above configuration:

• Right now, Ruhu has its own configure block - this would probably be nice to move into the global Webrat config
• The config.application_environment should be set to :ruhu which will cause the application being tested to be fired up using the ‘ruhu’ environment (See notes below about the Ruhu environment)
• If the config.use_viewer is set to false (which is the default) - it will run in "headless" mode (you won’t be able to see your tests running)
• If the config.use_viewer is set to true, a RubyCoca app (RuhuViewer) will be fired up and you will be able to see all of your tests running
• If you are going to use the RuhuViewer, the page_view_seconds variable determines how long each page/action will be displayed before moving onto the next step/action

When using Ruhu, before running it will check to see if the application is already running. If not it will fire it up for the tests, and then kill the process when the tests are done. If the application is already running (on the specified port - which defaults to 3001), then it will just test that process. This is useful for watching requests come through, or running a debugger.

Once all of this is setup, you should be able to run the following commands:

Run all of your features using Webrat::Core

  cucumber -r features/support/env.rb features

Run all of your features using Webrat::Ruhu

  WEBRAT=ruhu cucumber -r features/support/env.rb features

Basic Webrat API Testing App

I included this basic app (rails_testing_app) to test the Webrat API. This app has one feature - features/webrat_api.feature

To run this feature using Webrat::Core

  cd rails_testing_app
  cucumber -r features/support/env.rb features/webrat_api.rb

To run this feature using Webrat::Ruhu

  cd rails_testing_app
  WEBRAT=ruhu cucumber -r features/support/env.rb features/webrat_api.rb

Again - please let me know what bugs you find, problems you have, or features you would like to see.

Thanks!!

JohnnyT

P.S. - I would like to give a shout out to langalex - I based some of the code for remote object proxies on what he did for Culerity (github.com/langalex/culerity)

Description

Webrat lets you quickly write expressive and robust acceptance tests for a Ruby web application.

Features

• Browser Simulator for expressive, high level acceptance testing without the performance hit and browser dependency of Selenium or Watir (See Webrat::Session)
• Use the same API for Browser Simulator and real Selenium tests using Webrat::Selenium when necessary (eg. for testing AJAX interactions)
• Supports multiple Ruby web frameworks: Rails, Merb and Sinatra
• Supports popular test frameworks: RSpec, Cucumber, Test::Unit and Shoulda
• Webrat::Matchers API for verifying rendered HTML using CSS, XPath, etc.

Example

  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"
    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.

Installing Nokogiri

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.

Install for Rails

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

Install with Merb

Merb 1.0 has built-in, seamless Webrat support. Just start using methods from Webrat::Session in your specs.

Authors

• Maintained by Bryan Helmkamp
• Original code written by Seth Fitzsimmons
• Initial development was sponsored by EastMedia
• Many other contributors. See attributions in History.txt

License

Copyright © 2007-2008 Bryan Helmkamp, Seth Fitzsimmons. See MIT-LICENSE.txt in this directory.