Welcome to the official Ruby driver for Selenium Remote Control

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 to get an extensive reference.

• Idiomatic interface to the Selenium API. See the Idiomatic module for more details.

• Convenience methods for AJAX. See the Extensions 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'
  • click 'the_button_id', :wait_for => :visible, :element => 'a_locator'
  • click 'the_button_id', :wait_for => :not_visible, :element => 'a_locator'
  • 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

• 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.16"
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.16"
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.8"
gem "selenium-client", ">=1.2.16"
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 and RemoteControlStopTask 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)

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

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 http://github.com/ph7/selenium-client/issues
• Browse API at http://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 http://github.com/ph7/selenium-client/issues

• I recommend cloning the selenium-client reference repository

• You can also check out the RubyForge page and the RDoc

• We also have a continuous integration server

• Stories live in Pivotal Tracker

• 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)
  • Auto-highlighting support

• Rick Lee-Morlang (rleemorlang):

  • Fix for incremental calls to wait_for_text
  • Regex support in wait_for_text

• Paul Boone (paulboone)

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

• Adam Greene (skippy)

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

• Eliot Sykes (eliotsykes)

  • wait_for_visibility patch

• Frederik Fix(derfred)

  • Fix escaping bug when dealing with embedded regexes such as "webratlink=evalregex:/Pastry Lovers \(Organizer\)/" patch
  • Alex Chaffe
  • Better error reporting and fixed bug where if the response doesn't start with "OK" it swallows the first three chars (leading to annoying "ed out after 5000 msec" messages)