Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

147 lines (108 sloc) 4.783 kb


Click here to
lend your support to: WatirSplash and make a donation at !

WatirSplash makes browser-based web page testing in Ruby splashin' easy. It combines Watir, FireWatir or Watir-WebDriver for controlling the browser, RSpec for testing framework and Spork for faster environment loading. This powerful combination gives you the ability to write easily well-maintained and easy-to-read specs (specifications in RSpec) so you don't need to have any extra documentation for your applications.

WatirSplash makes it easier to use best features of all of these tools together so you won't have to spend time on thinking how to do that yourself - you can start testing right away!


1) Install Ruby (version 1.8.7 is recommended)

2) Install WatirSplash

C:\my_project>gem install watirsplash

3) Create a new project

C:\my_project>watirsplash new
      create  ui-test

C:\my_project>cd ui-test

4) Install all possible runtime dependencies

C:\my_project\ui-test>bundle install
Fetching source index for
Using watirsplash

5) Create a “search” page class and a spec skeleton for it

C:\my_project\ui-test>bundle exec watirsplash page search --url
      create  lib
      create  lib/app/page/search.rb
      create  spec
      create  spec/app/page/search_spec.rb

6) Create a “results” page class without spec

C:\my_project\ui-test>bundle exec watirsplash page results --no-spec
       exist  lib
      create  lib/app/page/results.rb

7) Modify the created files

# lib\app\page\search.rb
module App
  module Page
    class Search < WatirSplash::Page::Base
      url ""

      def search_field
        text_field(:name => "q")

      def search_button
        modify button(:name => "go"),
          # clicking the search button results a page transition to "results" page
          :click => lambda {redirect_to Results}

# lib\app\page\results.rb
module App
  module Page
    class Results < WatirSplash::Page::Base

      def result index
        div(:id => "results").
          ul(:class => "sb_results").
          li(:class => /sa_wr/, :index => index).


# spec\app\page\search_spec.rb
describe App::Page::Search do
  it "has something on the search page" do
    search_page =
    search_page.search_field.set "watirsplash"
    results_page =
    results_page.result(1).should =~ /watirsplash/i

7) Start Spork for faster environment loading:

 C:\my_project\ui-test>bundle exec spork 
--> DRb magazine_slave_service: 1 provided...
--> DRb magazine_slave_service: 2 provided...

9) Execute all specs

C:\my_project\ui-test>bundle exec rspec spec
Results will be saved into to results/index.html

App::Page::Search @ app/page/search_spec.rb:1 (30.06.2011)
  has something on the search page:2 (09:34:30)

Finished in 4.48 seconds
1 example, 0 failures

10) Check out the html report at results/index.html

11) Repeat & profit!


WatirSplash supports different frameworks/browsers on different operating systems:

  • Linux & OS X - watir-webdriver/firefox, watir-webdriver/chrome and firewatir

  • Windows - watir, watir-webdriver/firefox, watir-webdriver/chrome, watir-webdriver/ie and firewatir

Each framework drives a specific browser:

  • Watir - IE

  • Watir-WebDriver - Chrome, IE and Firefox

  • FireWatir - Firefox

It is possible to specify what framework to use in spec_helper.rb file:

WatirSplash::Util.framework = "watir-webdriver/firefox"

It is also possible to specify used framework by using environment variable WATIRSPLASH_FRAMEWORK.

If framework is not specified manually then the default framework will be used for the current platform.

PS! Please note that all frameworks are not 100% compatible with each other. If you find any concrete incompatibilities then it would be great if you'd contribute fixes or information to the authors of the frameworks.


You can read more information about the usage and features from the wiki at


Copyright © 2010-2011 Jarmo Pertman. See LICENSE for details.

Jump to Line
Something went wrong with that request. Please try again.