# README.markdown

Path: | README.markdown
Last Update: | Fri Jun 12 14:11:17 -0500 2009

Welcome to the official Ruby driver for [Selenium Remote Control](selenium-rc.openqa.org)

Mission

###### =

     Provide a **lightweight, simple and idiomatic API to write
     Selenium tests in Ruby**. Focus is also on improving test
     feedback -- especially on failures -- by providing
     out-of-the-box **state-of-the-art reporting capabilities**.
     With screenshots, HTML snapshopts and log captures,
     investigating test failures becomes a breeze.

Install It

###### ====

     The easiest way to install the install selenium-client using RubyGems:

        sudo gem install selenium-client

Features

###### ==

- Backward compatible with the old-fashioned, XSL generated Selenium Ruby API.

     See [the generated driver](http://selenium-client.rubyforge.org/classes/Selenium/Client/GeneratedDriver.html) to get an extensive reference.

- Idiomatic interface to the Selenium API. See [the Idiomatic module](selenium-client.rubyforge.org/classes/Selenium/Client/Idiomatic.html) for more details.
- Convenience methods for AJAX.

     See the [Extensions](http://selenium-client.rubyforge.org/classes/Selenium/Client/Extensions.html)
      for more details.

- Flexible wait semantics inline with the trigerring action. e.g.
  - `click ‘the_button_id’, :wait_for => :page`
  - `click ‘the_button_id’, :wait_for => :ajax`
  - `click ‘the_button_id’, :wait_for => :element, :element => ‘new_element_id’`
  - `click ‘the_button_id’, :wait_for => :no_element, :element => ‘disappearing_element_id’`
  - `click ‘the_button_id’, :wait_for => :text, :text => ‘New Text’`
  - `click ‘the_button_id’, :wait_for => :text, :text => /A Regexp/`
  - `click ‘the_button_id’, :wait_for => :text, :element => ‘notification_box’, :text => ‘New Text’`
  - `click ‘the_button_id’, :wait_for => :no_text, :text => ‘Disappearing Text’`
  - `click ‘the_button_id’, :wait_for => :no_text, :text => /A Regexp/`
  - `click ‘the_button_id’, :wait_for => :no_text, :element => ‘notification_box’, :text => ‘Disappearing Text’`
  - `click ‘the_button_id’, :wait_for => :effects`
  - `click ‘the_button_id’, :wait_for => :value, :element => ‘a_locator’, :value => ‘some value’`
  - `click ‘the_button_id’, :wait_for => :no_value, :element => ‘a_locator’, :value => ‘some value’ # will wait for the field value of ‘a_locator’ to not be ‘some value’`
  - `click ‘the_button_id’, :wait_for => :condition, :javascript => "some arbitrary javascript expression"`

  Check out the `click`, `go_back` and `wait_for` methods of the [Idiomatic Module](selenium-client.rubyforge.org/classes/Selenium/Client/Idiomatic.html)

- Leveraging latest innovations in Selenium Remote Control (screenshots, log captures, …)
- Robust Rake task to start/stop the Selenium Remote Control server. More details in the next section.
- State-of-the-art reporting for RSpec.

Plain API

###### ===

     Selenium client is just a plain Ruby API, so you can use it wherever you can use Ruby.

     To used the new API just require the client driver:

        require "rubygems"
        require "selenium/client"

     For a fully backward compatible API you can start with:

        require "rubygems"
        gem "selenium-client"
        require "selenium"

     For instance
     to write a little Ruby script using selenium-client you could write something like:

        #!/usr/bin/env ruby
        #
        # Sample Ruby script using the Selenium client API
        #
        require "rubygems"
        gem "selenium-client", ">=1.2.15"
        require "selenium/client"

        begin
          @browser = Selenium::Client::Driver.new \
              :host => "localhost",
              :port => 4444,
              :browser => "*firefox",
              :url => "http://www.google.com",
              :timeout_in_second => 60

          @browser.start_new_browser_session
            @browser.open "/"
            @browser.type "q", "Selenium seleniumhq.org"
            @browser.click "btnG", :wait_for => :page
            puts @browser.text?("seleniumhq.org")
        ensure
          @browser.close_current_browser_session
        end

Writing Tests

###### =======

     Most likely you will be writing functional and acceptance tests using selenium-client. If you are a
     `Test::Unit` fan your tests will look like:

        #!/usr/bin/env ruby
        #
        # Sample Test:Unit based test case using the selenium-client API
        #
        require "test/unit"
        require "rubygems"
        gem "selenium-client", ">=1.2.15"
        require "selenium/client"

        class ExampleTest < Test::Unit::TestCase
            attr_reader :browser

          def setup
            @browser = Selenium::Client::Driver.new \
                :host => "localhost",
                :port => 4444,
                :browser => "*firefox",
                :url => "http://www.google.com",
                :timeout_in_second => 60

            browser.start_new_browser_session
          end

          def teardown
            browser.close_current_browser_session
          end

          def test_page_search
                    browser.open "/"
                    assert_equal "Google", browser.title
                    browser.type "q", "Selenium seleniumhq"
                    browser.click "btnG", :wait_for => :page
                    assert_equal "Selenium seleniumhq - Google Search", browser.title
                    assert_equal "Selenium seleniumhq", browser.field("q")
                    assert browser.text?("seleniumhq.org")
                    assert browser.element?("link=Cached")
          end

        end

     If BDD is more your style, here is how you can achieve the same thing  using RSpec:

        require 'rubygems'
        gem "rspec", "=1.2.6"
        gem "selenium-client", ">=1.2.15"
        require "selenium/client"
        require "selenium/rspec/spec_helper"

        describe "Google Search" do
            attr_reader :selenium_driver
            alias :page :selenium_driver

          before(:all) do
              @selenium_driver = Selenium::Client::Driver.new \
                  :host => "localhost",
                  :port => 4444,
                  :browser => "*firefox",
                  :url => "http://www.google.com",
                  :timeout_in_second => 60
          end

          before(:each) do
            selenium_driver.start_new_browser_session
          end

          # The system capture need to happen BEFORE closing the Selenium session
          append_after(:each) do
            @selenium_driver.close_current_browser_session
          end

          it "can find Selenium" do
            page.open "/"
            page.title.should eql("Google")
            page.type "q", "Selenium seleniumhq"
            page.click "btnG", :wait_for => :page
            page.value("q").should eql("Selenium seleniumhq")
            page.text?("seleniumhq.org").should be_true
            page.title.should eql("Selenium seleniumhq - Google Search")
            page.text?("seleniumhq.org").should be_true
                    page.element?("link=Cached").should be_true
          end

        end

Start/Stop a Selenium Remote Control Server

###### =====================================

      Selenium client comes with some convenient Rake tasks to start/stop a Remote Control server.
      To leverage the latest selenium-client capabilities, you may need to download
      a recent nightly build of a standalone packaging of Selenium Remote
      Control. You will find the nightly build at
      http://nexus.openqa.org/content/repositories/snapshots/org/seleniumhq/selenium/server/selenium-server/

     You typically "freeze" the Selenium Remote Control jar in your `vendor`
     directory.

        require 'selenium/rake/tasks'

        Selenium::Rake::RemoteControlStartTask.new do |rc|
          rc.port = 4444
          rc.timeout_in_seconds = 3 * 60
          rc.background = true
          rc.wait_until_up_and_running = true
          rc.jar_file = "/path/to/where/selenium-rc-standalone-jar-is-installed"
          rc.additional_args << "-singleWindow"
        end

        Selenium::Rake::RemoteControlStopTask.new do |rc|
          rc.host = "localhost"
          rc.port = 4444
          rc.timeout_in_seconds = 3 * 60
        end

      If you do not explicitly specify the path to selenium remote control jar
      it will be "auto-discovered" in `vendor` directory using the following
      path : `vendor/selenium-remote-control/selenium-server*-standalone.jar`

      Check out [RemoteControlStartTask](http://selenium-client.rubyforge.org/classes/Selenium/Rake/RemoteControlStartTask.html) and [RemoteControlStopTask](http://selenium-client.rubyforge.org/classes/Selenium/Rake/RemoteControlStopTask.html) for more

details.

State-of-the-Art RSpec Reporting

###### ==========================

     Selenium Client comes with out-of-the-box RSpec reporting that include HTML snapshots, O.S. screenshots, in-browser page

screenshots (not limited to current viewport), and a capture of the latest remote controls for all failing tests. And all course all this works even if your infrastructure is distributed (In particular in makes wonders with [Selenium Grid](selenium-grid.openqa.org))

     Using selenium-client RSpec reporting is as simple as using `SeleniumTestReportFormatter` as one of you RSpec formatters. For instance:

        require 'spec/rake/spectask'
        desc 'Run acceptance tests for web application'
        Spec::Rake::SpecTask.new(:'test:acceptance:web') do |t|
         t.libs << "test"
         t.pattern = "test/*_spec.rb"
         t.spec_opts << '--color'
         t.spec_opts << "--require 'rubygems,selenium/rspec/reporting/selenium_test_report_formatter'"
         t.spec_opts << "--format=Selenium::RSpec::SeleniumTestReportFormatter:./tmp/acceptance_tests_report.html"
         t.spec_opts << "--format=progress"
         t.verbose = true
        end

     You can then get cool reports like [this one](http://ph7spot.com/examples/selenium_rspec_report.html)

     To capture screenshots and logs on failures, also make sure you
     require the following files in your `spec_helper`:

        require "rubygems"
        require "spec"
        require "selenium/client"
        require "selenium/rspec/spec_helper"

Other Resources

###### =========

- Report bugs at github.com/ph7/selenium-client/issues
- Browse API at selenium-client.rubyforge.org

Contribute and Join the Fun!

###### ======================

      We welcome new features, add-ons, bug fixes, example, documentation,
      etc. Make the gem work the way you envision!

- Report bugs at github.com/ph7/selenium-client/issues
- I recommend cloning the selenium-client [reference repository](github.com/ph7/selenium-client/tree/master)
- You can also check out the [RubyForge page](rubyforge.org/projects/selenium-client) and the [RDoc](selenium-client.rubyforge.org)
- We also have a [continuous integration server](xserve.openqa.org:8080/view/Ruby%20Client)
- Stories live in [Pivotal Tracker](www.pivotaltracker.com/projects/6280)
- To build, run `rake clean default package`. You can then install the

generated gem with `sudo gem install pkg/*.gem`

- You can also run all integration tests with `rake ci:integration`

Core Team

###### ===

- Philippe Hanrigou (`ph7`): Current Maintainer and main contributor
- Aslak Hellesoy and Darren Hobbs : Original version of the Selenium Ruby driver

Contributors

###### ======

- Aaron Tinio (`aptinio`):

       - More robust Selenium RC shutdown
       - Support for locator including single quotes in `wait_for_...` methods
       - Do not capture system state on execution errors for pending examples
         (ExamplePendingError, NotYetImplementedError)

- Rick Lee-Morlang (`rleemorlang`):

       - Fix for incremental calls to `wait_for_text`
       - Regex support in `wait_for_text`

- [Paul Boone](www.mindbucket.com) (`paulboone`)

       - Fixed method_missing in selenium_helper to only delegate to methods
         that @selenium responds to

- [Adam Greene](blog.sweetspot.dm) (`skippy`)

       - Added the ability to redirect output to a log file, when
         launching Selenium Remote Control with the Rake task

[Validate]