Welcome to the official Ruby driver for [Selenium Remote Control](http://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-selenese using RubyGems:

    sudo gem install selenium-selenese

Features
========

* Backward compatible with the old-fashioned, XSL generated Selenium Ruby API.
   
* Idiomatic interface to the Selenium API.
 
* Convenience methods for AJAX.

* Flexible wait semantics inline with the trigerring action. e.g.
 
  Check out the `click`, `go_back` and `wait_for` methods of the [Idiomatic Module]
           
* 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-selenese 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/selenese"
 
 For instance
 to write a little Ruby script using selenium-selenese you could write something like:

    #!/usr/bin/env ruby
    #
    # Sample Ruby script
    #
    require "rubygems"
    require "selenium/selenese"
    
    begin
      @browser = Selenium::Client::Driver.new \
          :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. 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-to-selenese API
    #
    require "test/unit"
    require "rubygems"
    require "selenium/selenese"
    
    class ExampleTest < Test::Unit::TestCase
    	attr_reader :browser
    
      def setup
        @browser = Selenium::Client::Driver.new \
            :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.8"
    gem "selenium-client", ">=1.2.16"
    require "selenium/selenese"
    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 \
              :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.

  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`

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](http://selenium-grid.openqa.org))

 Using selenium-selenese 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/selenese"
    require "selenium/rspec/spec_helper"