= WatirSplash

* Web: http://github.com/jarmo/WatirSplash
* Author: Jarmo Pertman (mailto:jarmo.p[at]gmail.com)

{<img alt="Click here to lend your support to: WatirSplash and make a donation at www.pledgie.com !" src="https://www.pledgie.com/campaigns/16193.png?skin_name=chrome" />}[https://www.pledgie.com/campaigns/16193]

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!

== GETTING STARTED

1) Install Ruby (version 1.9.3 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 http://rubygems.org/
    ...
    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 http://bing.com
          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 "http://bing.com"

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

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


    # 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).
              text
          end

        end
      end
    end


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

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! 

== SUPPORTED PLATFORMS & BROWSERS

WatirSplash supports different frameworks/browsers on different operating systems:
* Linux & OS X - watir-webdriver/firefox and watir-webdriver/chrome
* Windows - watir, watir-webdriver/firefox, watir-webdriver/chrome and watir-webdriver/ie

Each framework drives a specific browser:
* Watir - IE
* Watir-WebDriver - Chrome, IE and 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.

== MORE INFORMATION?

You can read more information about the usage and features from the wiki at http://github.com/jarmo/WatirSplash/wiki

== COPYRIGHT

Copyright © Jarmo Pertman. See LICENSE for details.