selenium-client 1.2.3 → 1.2.4

data/README.markdown

@@ -16,22 +16,35 @@ Install It
 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.
+* 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.
+* 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.
-   
- * Leveraging latest innovations in Selenium Remote Control (screenshots, log captures, ...)
+* 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.
  
- * Robust Rake task to start/stop the Selenium Remote Control server. More details in the next section.
+  * `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 => :no_text, :text => 'Disappearing Text'`
+  * `click 'the_button_id', :wait_for => :effects`
+  * `click 'the_button_id', :wait_for => :condition, :javascript => "some arbitrary javascript expression"`
 
- * State-of-the-art reporting for RSpec.
+  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
 =========
@@ -131,8 +144,9 @@ Writing Tests
        selenium_driver.start_new_browser_session
      end
 
-     after(:each) do
-       selenium_driver.close_current_browser_session
+     # The system capture need to happen BEFORE closing the Selenium session 
+     config.append_after(:each) do    
+       @selenium_driver.close_current_browser_session
      end
 
      it "can find Selenium" do    
@@ -202,6 +216,21 @@ Grid](http://selenium-grid.openqa.org))
 
  You can then get cool reports like [this one](http://ph7spot.com/examples/selenium_rspec_report.html)
 
+Contribute and Join the Fun!
+============================
+
+  We welcome new features, add-ons, bug fixes, example, documentation, etc. Make the gem work the way you
+  envision!
+  
+* I recommend cloning the selenium-client [reference repository](http://github.com/ph7/selenium-client/tree/master)
+  I you are more of a SVN guy, the same code also lives at [OpenQA](http://svn.openqa.org/svn/selenium-rc/trunk/clients/ruby)
+  
+* 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)
+
 
+  
+  
  
  

data/lib/selenium/client/base.rb

@@ -9,6 +9,8 @@ module Selenium
       include Selenium::Client::GeneratedDriver
       include Selenium::Client::Extensions
       include Selenium::Client::Idiomatic
+
+      attr_reader :browser_string
   
       def initialize(server_host, server_port, browser_string, browser_url, timeout_in_seconds=300)
         @server_host = server_host

data/lib/selenium/client/extensions.rb

@@ -4,52 +4,69 @@ module Selenium
     # Convenience methods not explicitely part of the protocol
     module Extensions
 	
-	    # These for all Ajax request to finish (Only works if you are using prototype)
+	    # These for all Ajax request to finish (Only works if you are using prototype, the wait in happenning browser side)
 	    #
 	    # See http://davidvollbracht.com/2008/6/4/30-days-of-tech-day-3-waitforajax for
 	    # more background.
-      def wait_for_ajax(timeout=nil)
-	      selenium.wait_for_condition "selenium.browserbot.getCurrentWindow().Ajax.activeRequestCount == 0", 
-	                                  timeout || default_timeout_in_seconds
+      def wait_for_ajax(timeout_in_seconds=nil)
+	      selenium.wait_for_condition "selenium.browserbot.getCurrentWindow().Ajax.activeRequestCount == 0", timeout_in_seconds
 	    end
 	
-	    # Wait for all Prototype effects to be processed 
+	    # Wait for all Prototype effects to be processed (the wait in happenning browser side).
 	    #
 	    # Credits to http://github.com/brynary/webrat/tree/master
-			def wait_for_effects(timeout=nil)
-			  selenium.wait_for_condition "window.Effect.Queue.size() == 0", timeout || default_timeout_in_seconds
+			def wait_for_effects(timeout_in_seconds=nil)
+			  selenium.wait_for_condition "window.Effect.Queue.size() == 0", timeout_in_seconds
 			end
 			
-		  def wait_for_element(field_name, time=60000)
+			# Wait for an element to be present (the wait in happenning browser side).
+		  def wait_for_element(locator, timeout_in_seconds=nil)
 		    script = <<-EOS
 		    var element;
 		    try {
-		      element = selenium.browserbot.findElement('#{field_name}');
+		      element = selenium.browserbot.findElement('#{locator}');
 		    } catch(e) {
 		      element = null;
 		    }
 		    element != null
 		    EOS
 
-		    wait_for_condition script, time
+		    wait_for_condition script, timeout_in_seconds
 		  end
 
-		  def wait_for_text(field_name, text, time=60000)
+			# Wait for an element to NOT be present (the wait in happenning browser side).
+		  def wait_for_no_element(locator, timeout_in_seconds=nil)
+		    script = <<-EOS
+		    var element;
+		    try {
+		      element = selenium.browserbot.findElement('#{locator}');
+		    } catch(e) {
+		      element = null;
+		    }
+		    element == null
+		    EOS
+
+		    wait_for_condition script, timeout_in_seconds
+		  end
+
+			# Wait for some text to be present (the wait in happenning browser side).
+		  def wait_for_text(locator, text, timeout_in_seconds=nil)
 		    script = "var element;
 		              try {
-		                element = selenium.browserbot.findElement('#{field_name}');
+		                element = selenium.browserbot.findElement('#{locator}');
 		              } catch(e) {
 		                element = null;
 		              }
 		              element != null && element.innerHTML == '#{text}'"
 
-		    wait_for_condition script, time
+		    wait_for_condition script, timeout_in_seconds
 		  end
 
-		  def wait_for_text_change(field_name, original_text, time=60000)
+			# Wait for some text to NOT be present (the wait in happenning browser side).
+		  def wait_for_no_text(locator, original_text, timeout_in_seconds=nil)
 		    script = "var element;
 		              try {
-		                element = selenium.browserbot.findElement('#{field_name}');
+		                element = selenium.browserbot.findElement('#{locator}');
 		              } catch(e) {
 		                element = null;
 		              }
@@ -58,16 +75,17 @@ module Selenium
 		    wait_for_condition script, time
 		  end
 
-		  def wait_for_field_value(field_name, value, time=60000)
+			# Wait for a field to get a specific value (the wait in happenning browser side).
+		  def wait_for_field_value(locator, expected_value, timeout_in_seconds=nil)
 		    script = "var element;
 		              try {
-		                element = selenium.browserbot.findElement('#{field_name}');
+		                element = selenium.browserbot.findElement('#{locator}');
 		              } catch(e) {
 		                element = null;
 		              }
-		              element != null && element.value == '#{value}'"
+		              element != null && element.value == '#{expected_value}'"
 
-		    wait_for_condition script, time
+		    wait_for_condition script, timeout_in_seconds
 		  end
 
     end

data/lib/selenium/client/idiomatic.rb

@@ -14,7 +14,7 @@ module Selenium
       # or the innerText (IE-like browsers) of the element, which is the
       # rendered text shown to the user.
       #
-      # 'locator' is an Selenium element locator
+      # * 'locator' is an Selenium element locator
       def text_content(locator)
         string_command"getText", [locator,]
       end
@@ -37,44 +37,84 @@ module Selenium
       # if you want to wait for a page to load, you must wait immediately 
       # after a Selenium command that caused a page-load.
       # 
-      # 'timeout_in_seconds' is a timeout in seconds, after which this 
-      # command will return with an error
+      # * 'timeout_in_seconds' is a timeout in seconds, after which this 
+      #   command will return with an error
       def wait_for_page(timeout_in_seconds=nil)
           actual_timeout = timeout_in_seconds || default_timeout_in_seconds
         remote_control_command "waitForPageToLoad", [actual_timeout * 1000,]
       end
 
+      # Flexible wait semantics. ait is happening browser side. Useful for testing AJAX application.
+      #
+      # * wait :wait_for => :page                                       # will wait for a new page to load
+      # * wait :wait_for => :ajax                                       # will wait for all ajax requests to be completed (Prototype only)
+      # * wait :wait_for => :effects                                    # will wait for all Prototype effects to be rendered
+      # * wait :wait_for => :element, :element => 'new_element_id'      # will wait for an element to be present/appear
+      # * wait :wait_for => :no_element, :element => 'new_element_id'   # will wait for an element to be not be present/disappear
+      # * wait :wait_for => :text, :text => 'some text'                 # will wait for some text to be present/appear
+      # * wait :wait_for => :no_text, :text => 'some text'              # will wait for the text to be not be present/disappear
+      # * wait :wait_for => :condition, :javascript => 'some expression' # will wait for the javascript expression to be true
+      #
+      # Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout
+      # is used.
+      def wait_for(options)
+        if options[:wait_for] == :page
+          wait_for_page options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :ajax
+	          wait_for_ajax options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :element
+	          wait_for_element options[:element], options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :no_element
+	          wait_for_no_element options[:element], options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :text
+	          wait_for_text options[:text], options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :no_text
+	          wait_for_no_text options[:text], options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :effects
+	          wait_for_effects options[:timeout_in_seconds]
+	      elsif options[:wait_for] == :condition
+	          wait_for_condition options[:javascript], options[:timeout_in_seconds]
+        end
+      end
+	
       # Gets the entire text of the page.
       def body_text
         string_command"getBodyText"
       end
 
-      # Clicks on a link, button, checkbox or radio button. If the click action
-      # causes a new page to load (like a link usually does), call
-      # waitForPageToLoad.
+      # Clicks on a link, button, checkbox or radio button.
       #
       # 'locator' is an element locator      
+      # 
+      # Using 'options' you can automatically wait for an event to happen after the 
+      # click. e.g.
+      #
+      # * click 'some_id', :wait_for => :page                                        # will wait for a new page to load
+      # * click 'some_id', :wait_for => :ajax                                        # will wait for all ajax requests to be completed (Prototype only)
+      # * click 'some_id', :wait_for => :effects                                     # will wait for all Prototype effects to be rendered
+      # * click 'some_id', :wait_for => :element, :element => 'new_element_id'       # will wait for an element to be present/appear
+      # * click 'some_id', :wait_for => :no_element, :element => 'new_element_id'    # will wait for an element to be not be present/disappear
+      # * click :wait_for => :text, :text => 'some text'                             # will wait for some text to be present/appear
+      # * click :wait_for => :no_text, :text => 'some text'                          # will wait for the text to be not be present/disappear
+      # * click 'some_id', :wait_for => :condition, :javascript => 'some expression' # will wait for the javascript expression to be true
+      #
+      # Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout
+      # is used.
       def click(locator, options={})
         remote_control_command("click", [locator,])        
-        if options[:wait_for] == :page
-          wait_for_page options[:timeout_in_seconds]
-	      elsif options[:wait_for] == :ajax
-	          wait_for_ajax options[:timeout_in_seconds]
-	      elsif options[:wait_for] == :effects
-	          wait_for_effects options[:timeout_in_seconds]
-        end
+        wait_for options
       end
 
       # Verifies that the specified text pattern appears somewhere on the rendered page shown to the user.
       #
-      # 'pattern' is a pattern to match with the text of the page
+      # * 'pattern' is a pattern to match with the text of the page
       def text?(pattern)
         boolean_command "isTextPresent", [pattern,]
       end
 
       # Verifies that the specified element is somewhere on the page.
       #
-      # 'locator' is an element locator
+      # * 'locator' is an element locator
       def element?(locator)
         boolean_command "isElementPresent", [locator,]
       end
@@ -84,7 +124,7 @@ module Selenium
       # For checkbox/radio elements, the value will be "on" or "off" 
       # depending on whether the element is checked or not.
       #
-      # 'locator' is an element locator
+      # * 'locator' is an element locator
       def field(locator)
         string_command "getValue", [locator,]
       end
@@ -97,7 +137,7 @@ module Selenium
       # Returns whether a toggle-button (checkbox/radio) is checked. 
       # Fails if the specified element doesn't exist or isn't a toggle-button.
       #
-      # 'locator' is an element locator pointing to a checkbox or radio button
+      # * 'locator' is an element locator pointing to a checkbox or radio button
       def checked?(locator)
         boolean_command "isChecked", [locator,]
       end
@@ -113,8 +153,10 @@ module Selenium
       # Getting an alert has the same effect as manually clicking OK. If an
       # alert is generated but you do not consume it with getAlert, the next Selenium action
       # will fail.
+      #
       # Under Selenium, JavaScript alerts will NOT pop up a visible alert
       # dialog.
+      #
       # Selenium does NOT support JavaScript alerts that are generated in a
       # page's onload() event handler. In this case a visible dialog WILL be
       # generated and Selenium will hang until someone manually clicks OK.
@@ -181,7 +223,7 @@ module Selenium
       # a locator to refer to a single element in your application page, you can
       # use <tt>this.browserbot.findElement("id=foo")</tt> where "id=foo" is your locator.
       # 
-      # 'script' is the JavaScript snippet to run
+      # * 'script' is the JavaScript snippet to run
       def js_eval(script)
         string_command"getEval", [script,]
       end
@@ -200,12 +242,47 @@ module Selenium
       # Returns the text from a cell of a table. The cellAddress syntax
       # tableLocator.row.column, where row and column start at 0.
       #
-      # 'tableCellAddress' is a cell address, e.g. "foo.1.4"
+      # * 'tableCellAddress' is a cell address, e.g. "foo.1.4"
       def table_cell_text(tableCellAddress)
         string_command "getTable", [tableCellAddress,]
       end
 
-      # set speed
+      # Runs the specified JavaScript snippet repeatedly until it evaluates to "true".
+      # The snippet may have multiple lines, but only the result of the last line
+      # will be considered.
+      # 
+      # Note that, by default, the snippet will be run in the runner's test window, not in the window
+      # of your application.  To get the window of your application, you can use
+      # the JavaScript snippet <tt>selenium.browserbot.getCurrentWindow()</tt>, and then
+      # run your JavaScript in there
+      # 
+      #
+      # * 'script' is the JavaScript snippet to run
+      # * 'timeout_in_seconds' is a timeout in seconds, after which this command will return with an error
+      def wait_for_condition(script, timeout_in_seconds = nil)
+        remote_control_command "waitForCondition", [script, (timeout_in_seconds || default_timeout_in_seconds) * 1000,]
+      end
+
+      # Simulates the user clicking the "back" button on their browser.
+      # Using 'options' you can automatically wait for an event to happen after the 
+      # click. e.g.
+      #
+      # * go_back :wait_for => :page                                        # will wait for a new page to load
+      # * go_back :wait_for => :ajax                                        # will wait for all ajax requests to be completed (Prototype only)
+      # * go_back :wait_for => :effects                                     # will wait for all Prototype effects to be rendered
+      # * go_back :wait_for => :element, :element => 'new_element_id'       # will wait for an element to be present/appear
+      # * go_back :wait_for => :no_element, :element => 'new_element_id'    # will wait for an element to be not be present/disappear
+      # * go_back :wait_for => :text, :text => 'some text'                  # will wait for some text to be present/appear
+      # * go_back :wait_for => :no_text, :text => 'some text'               # will wait for the text to be not be present/disappear
+      # * go_back :wait_for => :condition, :javascript => 'some expression' # will wait for the javascript expression to be true
+      #
+      # Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout
+      # is used.
+      def go_back(options={})
+        remote_control_command "goBack"
+        wait_for options
+      end
+
     end
   
   end

data/lib/selenium/rspec/spec_helper.rb

@@ -7,7 +7,7 @@ require File.expand_path(File.dirname(__FILE__) + "/reporting/selenium_test_repo
 
 Spec::Runner.configure do |config|
 
-  config.after(:each) do
+  config.prepend_after(:each) do
     begin 
       Selenium::RSpec::SeleniumTestReportFormatter.capture_system_state(selenium_driver, self) if execution_error
       if selenium_driver.session_started?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: selenium-client
 version: !ruby/object:Gem::Version 
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors: 
 - OpenQA
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-29 00:00:00 -07:00
+date: 2008-09-30 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -72,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: selenium-client
-rubygems_version: 1.3.0
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: Official Ruby Client for Selenium RC.