English
资源说明：Official Ruby client API for Selenium Remote Control (bare bone client driver)
Welcome to the official Ruby driver for [Selenium Remote Control](http://selenium-rc.openqa.org)
DEPRECATED
==========
The selenium-client gem has been unmaintained for several years. Please
use http://rubygems.org/gems/selenium-webdriver instead.
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](http://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'`
* `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](http://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.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](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](http://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 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](http://github.com/ph7/selenium-client/tree/master)
* You can also check out the [RubyForge page](http://rubyforge.org/projects/selenium-client)
and the [RDoc](http://selenium-client.rubyforge.org)
* We also have a [continuous integration server](http://xserve.openqa.org:8080/view/Ruby%20Client)
* Stories live in [Pivotal Tracker](https://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)
- Auto-highlighting support
* Rick Lee-Morlang (`rleemorlang`):
- Fix for incremental calls to `wait_for_text`
- Regex support in `wait_for_text`
* [Paul Boone](http://www.mindbucket.com) (`paulboone`)
- Fixed method_missing in selenium_helper to only delegate to methods
that @selenium responds to
* [Adam Greene](http://blog.sweetspot.dm) (`skippy`)
- Added the ability to redirect output to a log file, when
launching Selenium Remote Control with the Rake task
* [Eliot Sykes](http://blog.eliotsykes.com) (`eliotsykes`)
- wait_for_visibility [patch](http://github.com/eliotsykes/selenium-client/commit/4c7f3d01aa75a6b1917fbf71335b0069392ed546)
* [Frederik Fix](http://github.com/derfred)(`derfred`)
- Fix escaping bug when dealing with embedded regexes such as
"webratlink=evalregex:/Pastry Lovers \\(Organizer\\)/"
[patch](http://github.com/derfred/selenium-client/commit/4342cbb39d1a92b8db8f26ee0dc6c1a8f3287737)
* [Alex Chaffe](http://alexch.github.com)
- 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)
* [Jeffrey ODell](http://github.com/jodell)
- [nohup support path](http://github.com/jodell/selenium-client/commit/66fdcb296f73b2f85d7e4bc38aa14cf0e2a27706)
License
=======
Apache License, Version 2.0
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
