| 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
See [the generated driver](http://selenium-client.rubyforge.org/classes/Selenium/Client/GeneratedDriver.html) to get an extensive reference.
See the [Extensions](http://selenium-client.rubyforge.org/classes/Selenium/Client/Extensions.html) for more details.
Check out the `click`, `go_back` and `wait_for` methods of the [Idiomatic Module](selenium-client.rubyforge.org/classes/Selenium/Client/Idiomatic.html)
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
Contribute and Join the Fun!
We welcome new features, add-ons, bug fixes, example, documentation, etc. Make the gem work the way you envision!
generated gem with `sudo gem install pkg/*.gem`
Core Team
Contributors
- 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)
- Fix for incremental calls to `wait_for_text` - Regex support in `wait_for_text`
- Fixed method_missing in selenium_helper to only delegate to methods that @selenium responds to
- Added the ability to redirect output to a log file, when launching Selenium Remote Control with the Rake task