warnold-selenium-client 1.2.19

data/README.markdown

@@ -0,0 +1,338 @@
+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-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)
+
+

data/examples/rspec/google_spec.rb

@@ -0,0 +1,41 @@
+require 'rubygems'
+gem "rspec", ">=1.2.8"
+gem "selenium-client", ">=1.2.18"
+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

data/examples/script/google.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+#
+# Sample Ruby script using the Selenium client API
+#
+require "rubygems"
+gem "selenium-client", ">=1.2.18"
+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
+

data/examples/testunit/google_test.rb

@@ -0,0 +1,39 @@
+#!/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.18"
+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

data/lib/nautilus/shell.rb

@@ -0,0 +1,34 @@
+module Nautilus
+  
+  class Shell
+    
+    def run(command, options = {})
+      sh build_command(command, options)
+    end
+
+    def build_command(command, options = {})
+      actual_command = command.kind_of?(Array) ? command.join(" ") : command
+      if options[:background]
+        actual_command = if windows?
+          "start /wait /b #{actual_command}"
+        elsif options[:nohup]
+          "nohup #{actual_command} &"
+        else
+          "#{actual_command} &"
+        end
+      end 
+      actual_command
+    end
+            
+    def windows?
+      RUBY_PLATFORM =~ /mswin/
+    end
+    
+    def sh(command)
+      successful = system(command)
+      raise "Error while running >>#{command}<<" unless successful
+    end
+    
+  end
+
+end