tellurium_driver 1.1.23 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5229e6abc4f13c94886122de14c75fb4644f916f
-  data.tar.gz: f8bd2c1cf7f68fd314ac24046ca69ccb1fde27dd
+  metadata.gz: e22bbe5f3a58319caa758ee2e4cf66a66c9d4d7e
+  data.tar.gz: 583775721267ca37ac90b0663e6f75c97a001e0d
 SHA512:
-  metadata.gz: 44a8af562fc264e07ed7fefb4e43119daeae97448125f7fb9d8004f1e61fdbcf6d282976b9f622e18b49bd93842b5a708c0b11436c63ec5e3e097695e433c573
-  data.tar.gz: 2e9b3d0114b0ae440d37f218d5aadf7f3dd47b8918776c844ea11c0001d6147ad9c7a345d8f603646862e88906549cd2cc1b906d5fec96bc6c4d79f498425b42
+  metadata.gz: 38c2723d74b211441af599c740292032bf6bdb363876a0b282d62b33ee7d4078ac5404dc818fd4869224939f72a8ad75c9f4472d34b919fbfc508adf9e658d5c
+  data.tar.gz: 4d995672f18aeb2c351d69c07210fac90e2d4cedea9f8d31280f04caca14cb2cd77d05c608c662d57413c1304daf7c2d0594af2c2efed2fff6af62a82f9680a2

data/lib/tellurium_driver.rb

@@ -1,10 +1,12 @@
-#Provides added functionality to Selenium WebDriver
+# Provides added functionality to Selenium WebDriver
+#
+# Author:: Noah Prince (mailto:noahprince8@gmail.com)
 class TelluriumDriver
   class << self
     attr_accessor :wait_for_document_ready
   end
-  
-  #takes browser name, browser version, hub ip(optional) 
+
+  # :nodoc:
   def self.before(names)
     names.each do |name|
       m = instance_method(name)
@@ -14,47 +16,46 @@ class TelluriumDriver
       end
     end
   end
+  # :doc:
   
-  #@sets up this instance of TelluriumDriver
-  #@param [String] browser, "chrome","firefox", or "internet explorer"
-  #@param [Integer] version, the version of the browser. nil for firefox or chrome, or "local" to run locally
-  #@param hub_ip [String] the IP address of the Selenium Grid hub to test on
-  #@param [Integer] timeout, the timeout to use on test
-  def initialize(*args)
-    browser, version,hub_ip,timeout = args
-    timeout = 120 unless timeout
-    @wait = Selenium::WebDriver::Wait.new(:timeout=>timeout)
+  # Sets up this instance of TelluriumDriver
+  #
+  # ==== Options
+  #
+  # * +:browser+ - "chrome","firefox", "safari" or "internet explorer"
+  # * +:version+ - [String] the version of the browser. Not needed for safari, chrome, or firefox. 
+  # * +:hub_ip+ - the IP address of the Selenium Grid hub to test on. 
+  #   * Will use http://hub_ip:4444/wd/hub. If this is not correct, use :hub_url
+  # * +:hub_url+ - the full url address of the Selenium Grid hub to test on
+  #   * WARNING: DO NOT USE BOTH hub_ip and hub_url
+  #   * NOTE: If either hub_ip or hub_url is present, tests will not run locally
+  # * +:caps+ - see https://code.google.com/p/selenium/wiki/DesiredCapabilities
+  #   * Not necessary, but will give the browser any extra desired functionality
+  # * +:timeout+ - Number of seconds for all Tellurium wait commands. Default 120
+  #
+  # ==== Examples
+  #
+  # Run a local chrome instance 
+  #    TelluriumDriver.new(browser: "chrome") 
+  #
+  # Run an IE10 instance on the grid with ip 192.168.1.1
+  #    TelluriumDriver.new(browser: "internet explorer", version: "10", hub_ip: 192.168.1.1)
+  def initialize(opts = {})
+    opts[:timeout] = 120 unless opts[:timeout]
+    @wait = Selenium::WebDriver::Wait.new(:timeout=>opts[:timeout])
     TelluriumDriver.wait_for_document_ready=true;
+
+    opts[:caps] ||= {}
+    opts[:caps][:browserName] ||= opts[:browser]
+    opts[:caps][:version] ||= opts[:version]
+
+    is_local = !opts[:hub_ip] and !opts[:hub_url]
     
-    is_local = version.include?("local") if version and version.is_a? String
-    is_ie = browser.include?("internet") && version
-    is_chrome = browser.include?("chrome")
-    is_firefox = browser.include?("firefox") 
-
-    if is_chrome && is_local
-      caps = {
-        :browserName => "chrome",
-        :idleTimeout => timeout
-        # :screenshot => true
-      }
-      @driver = Selenium::WebDriver.for :chrome,:desired_capabilities=>caps
-    elsif is_firefox && is_local
-      caps = {
-        :browserName => "firefox",
-        :idleTimeout => timeout,
-        :screenshot => true
-      }
-      @driver = Selenium::WebDriver.for :firefox, :desired_capabilities=>caps
-    elsif is_ie
-      caps = Selenium::WebDriver::Remote::Capabilities.internet_explorer
-      caps.version = version.to_s
-      @driver = Selenium::WebDriver.for(:remote,:desired_capabilities=>caps,:url=> "http://#{hub_ip}:4444/wd/hub")
-    elsif is_chrome
-      @driver = Selenium::WebDriver.for(:remote,:desired_capabilities=>:chrome,:url=> "http://#{hub_ip}:4444/wd/hub")
-    elsif is_firefox
-      @driver = Selenium::WebDriver.for(:remote,:desired_capabilities=>:firefox,:url=> "http://#{hub_ip}:4444/wd/hub")
+    if is_local
+      @driver = Selenium::WebDriver.for(opts[:browser].to_sym,:desired_capabilities=>opts[:caps])
+    else
+      @driver = Selenium::WebDriver.for(:remote,:desired_capabilities=>opts[:caps],:url=> "http://#{opts[:hub_ip]}:4444/wd/hub")
     end
-
   end
 
 
@@ -78,62 +79,51 @@ class TelluriumDriver
     @driver.send sym,*args,&block
   end
 
-  #@param [String] url, the url to point the driver at
+  # Goes to a given url, does not wait for load
+  #
+  # ==== Attributes
+  #
+  # * +url+ - the url to visit
   def go_to(url)
     driver.get url
   end
 
-  #Waits for the title to change after going to a url
-  #@param [String] url, the url to go to
+  # Goes to a given url, waits for it to load
+  #   * NOTE: To see if loaded, waits for the title of the window to change
+  #
+  # ==== Attributes
+  #
+  # * +url+ - the url to visit
   def go_to_and_wait_to_load(url)
     current_name = driver.title
     driver.get url
 
-    #wait until the current title changes to see that you're at a new url
+    # wait until the current title changes to see that you're at a new url
     @wait.until { driver.title != current_name }
   end
-  
-  #takes a url, the symbol of what you wait to exist and the id/name/xpath, whatever of what you want to wait to exist
-  def load_website_and_wait_for_element(url,arg1,id)
+
+  # Goes to a given url, and waits for a given element to appear
+  #
+  # ==== Attributes
+  #
+  # * +url+ - the url to visit
+  # * +sym+ - :id, :name, :css, etc
+  # * +id+ - The text corresponding with the symbol.
+  #
+  # ==== Examples
+  #     driver.load_url_and_wait_for_element(:id,"password")
+  def load_url_and_wait_for_element(url,sym,id)
     current_name = driver.title
     driver.get url
 
-    @wait.until { driver.title != current_name and driver.find_elements(arg1, id).size > 0 }
-  end
-  
-  #clicks one element and waits for another one to change it's value. 
-  #@param [String] id_to_click, the id you want to click
-  #@param [String] id_to_change you
-  def click_and_wait_to_change(id_to_click,id_to_change,value) 
-    element_to_click = driver.find_element(:id, id_to_click)
-    element_to_change = driver.find_element(:id, id_to_change)
-    current_value = element_to_change.attribute(value.to_sym)
-
-    element_to_click.click
-    @wait.until { element_to_change.attribute(value.to_sym) != current_value }
-  end
-
-  #Fills in a value for form selectors
-  #@param [Symbol] sym, usually :id, :css, or :name
-  #@param [String] selector_value, the value to set the selector to
-  def click_selector(sym,id,selector_value)
-    option = Selenium::WebDriver::Support::Select.new(driver.find_element(sym.to_sym,id))
-    option.select_by(:text, selector_value)
-  end
-
-  #Fills out a selector and waits for another id to change
-  def click_selector_and_wait(id_to_click,selector_value,id_to_change,value)
-    element_to_change = driver.find_element(:id => id_to_change)
-    current_value = element_to_change.attribute(value.to_sym)
-
-    option = Selenium::WebDriver::Support::Select.new(driver.find_element(:id => id_to_click))
-    option.select_by(:text, selector_value)
-      
-    @wait.until { element_to_change.attribute(value.to_sym) != current_value }
+    @wait.until { driver.title != current_name and driver.find_elements(sym, id).size > 0 }
   end
 
-  #Waits for an element to be displayed
-  #@param [SeleniumWebdriver::Element]
+  # Waits for an element to be displayed on the page
+  #
+  # ==== Attributes
+  #
+  # * +element+ - Selenium::WebDriver::Element to appear
   def wait_for_element(element)
       @wait.until {
           bool = false
@@ -148,9 +138,16 @@ class TelluriumDriver
       }
   end
 
-  #Waits for the element with specified identifiers to disappear
-  #@param [Symbol] sym
-  #@param [String] id
+  # Waits for the element with specified identifiers to disappear 
+  #
+  # ==== Attributes
+  #
+  # * +sym+ - :id, :name, :css, etc
+  # * +id+ - The text corresponding with the symbol.
+  #
+  # ==== Examples
+  #
+  #   driver.wait_to_disappear(:id,"hover-box")
   def wait_to_disappear(sym,id)
    @wait.until {
     element_arr = driver.find_elements(sym,id)
@@ -158,8 +155,18 @@ class TelluriumDriver
   }
   end
 
-  #waits for an element to disappear
-  #@param [SeleniumWebdriver::Element] element
+  # Similar to wait_to_disappear, but takes an element instead of identifiers
+  #   * WARNING: If the element disappears from the DOM, and isn't just hidden
+  #              this will raise a stale reference error
+  #
+  # ==== Attributes
+  #
+  # * +element+ - Selenium::WebDriver::Element to appear
+  #
+  # ==== Examples
+  #
+  #    element = driver.find_element(id: "foo")
+  #    driver.wait_for_element_to_disappear(element)
   def wait_for_element_to_disappear(element)
     @wait.until {
       begin
@@ -170,8 +177,16 @@ class TelluriumDriver
     }
   end
 
-  #@param [Symbol] sym
-  #@param [String] id, the string associated with the symbol to identify the elementw
+  # Waits for the element with specified identifiers to appear 
+  #
+  # ==== Attributes
+  #
+  # * +sym+ - :id, :name, :css, etc
+  # * +id+ - The text corresponding with the symbol.
+  #
+  # ==== Examples
+  #
+  #    driver.wait_to_appear(:id,"hover-box")
   def wait_to_appear(sym,id)
    @wait.until {
     element_arr = driver.find_elements(sym,id)
@@ -179,8 +194,16 @@ class TelluriumDriver
    }
   end
 
-  # to change. (Example, I click start-application and wait for the next dialogue
-  # box to not be hidden)
+  # Waits for the element with specified identifiers to appear, then clicks it 
+  #
+  # ==== Attributes
+  #
+  # * +sym+ - :id, :name, :css, etc
+  # * +id+ - The text corresponding with the symbol.
+  #
+  # ==== Examples
+  #
+  #    driver.wait_and_click(:name,"hello")
   def wait_and_click(sym, id)
    found_element = false
 
@@ -210,8 +233,11 @@ class TelluriumDriver
     
   end
 
-  # Waits for an element to be displayed and click it
-  #@param [SeleniumWebdriver::Element] 
+  # Waits for the given element to appear and clicks it
+  #
+  # ==== Attributes
+  #
+  # * +element+ - Selenium::WebDriver::Element to appear
   def wait_for_element_and_click(element)
     wait_for_element(element)
     
@@ -227,8 +253,79 @@ class TelluriumDriver
     
   end
 
-  #hovers where the element is and clicks. Workaround for timeout on click that happened with the new update to the showings app
-  #@param [SeleniumWebdriver::Element] element OR can take sym,id
+  # Clicks one element, and waits for the attribute of another element to change
+  #   * NOTE: This method only takes ids
+  #
+  # ==== Attributes
+  #
+  # * +id_to_click+
+  # * +id_to_change+
+  # * +value+ - the attribute to change on the second element
+  #
+  # ==== Examples
+  #
+  #    driver.click_and_wait_to_change("checkbox","score","text")
+  def click_and_wait_to_change(id_to_click,id_to_change,value) 
+    element_to_click = driver.find_element(:id, id_to_click)
+    element_to_change = driver.find_element(:id, id_to_change)
+    current_value = element_to_change.attribute(value.to_sym)
+
+    element_to_click.click
+    @wait.until { element_to_change.attribute(value.to_sym) != current_value }
+  end
+
+  # Fills in a value for form selectors
+  #
+  # ==== Attributes
+  #
+  # * +sym+ - :id, :css, or :name, etc
+  # * +id+ - The text corresponding with the symbol.
+  # * +selector_value+ - The value to change the selector to
+  #
+  # ==== Examples
+  #
+  #    driver.click_selector(:id,"age","21")
+  def click_selector(sym,id,selector_value)
+    option = Selenium::WebDriver::Support::Select.new(driver.find_element(sym.to_sym,id))
+    option.select_by(:text, selector_value)
+  end
+
+  # Fills in a value for form selectors and waits for another element to change
+  #   * NOTE: This method only uses ids
+  #
+  # ==== Attributes
+  #
+  # * +id_to_click+
+  # * +selector_value+ - The value to change the selector to
+  # * +id_to_change+
+  # * +value+ - the attribute to change on the second element
+  #
+  # ==== Examples
+  #
+  # Waits for the attribute "available" on the element with id: "drinks" to change
+  # after filling an age selector to 21
+  # 
+  #    driver.click_selector_and_wait("age","21","drinks","available")
+  def click_selector_and_wait(id_to_click,selector_value,id_to_change,value)
+    element_to_change = driver.find_element(:id => id_to_change)
+    current_value = element_to_change.attribute(value.to_sym)
+
+    option = Selenium::WebDriver::Support::Select.new(driver.find_element(:id => id_to_click))
+    option.select_by(:text, selector_value)
+      
+    @wait.until { element_to_change.attribute(value.to_sym) != current_value }
+  end
+
+  # Hovers over where an element should be and clicks. Useful for hitting hidden elements
+  #
+  # ==== Attributes
+  #
+  # * +element+ - Selenium::WebDriver::Element
+  #
+  # ===== OR
+  #
+  # * +sym+ - :id, :css, or :name, etc
+  # * +id+ - The text corresponding with the symbol.
   def hover_click(*args)
     if args.size == 1
     driver.action.click(element).perform
@@ -239,10 +336,13 @@ class TelluriumDriver
 
   end
 
-  #fills an input of the given sym,id with a value
-  #@param [Symbol] sym
-  #@param [String] id
-  #@param [String] value
+  # Fills a text input of the given sym,id with a value
+  # 
+  # ==== Attributes
+  #
+  # * +sym+ - :id, :css, or :name, etc
+  # * +id+ - The text corresponding with the symbol.
+  # * +value+ - the string to send to the text input
   def send_keys(sym,id,value)
     #self.wait_and_click(sym, id)
     #driver.action.send_keys(driver.find_element(sym => id),value).perform
@@ -252,12 +352,26 @@ class TelluriumDriver
     element.send_keys(value)
   end
 
+  # :nodoc:
   def send_keys_leasing(sym,id,value)
     self.wait_to_appear(sym,id)
     self.driver.find_element(sym,id).send_keys(value) 
   end
-
-  #takes the id you want to click, the id you want to exist.(Example, I click start-application and wait for the next dialogue box to exist
+  # :doc:
+
+  # Clicks one element and waits for another to exist
+  #
+  # ==== Attributes
+  #
+  # * +id1+ - Id of element to click
+  # * +id2+ - Id of element to exist
+  #
+  # ===== OR
+  #
+  # * +sym1+ - :id, :css, or :name, etc for the element to click
+  # * +id1+ - The text corresponding with the symbol. 
+  # * +sym2+ - :id, :css, or :name, etc for the element to wait to exist
+  # * +id2+ - The text corresponding with the symbol. 
   def click_and_wait_to_exist(*args) 
      case args.size
      when 2 #takes just two id's
@@ -280,22 +394,46 @@ class TelluriumDriver
         error
      end
   end
-  
-  def form_fillout(hash) #takes a hash of ID's with values to fillout
+
+  # Fills out large forms via a supplied hash in the form id,value_to_send
+  #
+  # ==== Attributes
+  #
+  # * +hash+ - A hash of input IDs associated with the value to send to the input
+  #
+  # ==== Examples
+  #
+  # Fill out a login form
+  #    driver.form_fillout({"first_name"=>"Noah",
+  #                         "last_name"=>"Prince",
+  #                         "email"=>"noahprince8@gmail.com"})
+  def form_fillout(hash)
     hash.each do |id,value|
       self.wait_to_appear(:id,id)
        self.send_keys(:id,id,value)
     end
 
   end
-  
+
+  # :nodoc:
   def form_fillout_editable(selector,hash)
     hash.each do |id,value|
       name = "#{selector}\[#{id}\]"
       driver.execute_script("$('[data-field=\"#{name}\"]').editable('setValue', '#{value}');")
     end
   end
-  
+  # :doc:
+
+  # Fills out large numbers of selectors via a supplied hash in the form id,value_to_send
+  #
+  # ==== Attributes
+  #
+  # * +hash+ - A hash of input IDs associated with the value to send to the input
+  #
+  # ==== Examples
+  #
+  # Fill out a login form
+  #    driver.form_fillout({"age"=>"21","num_of_pets"=>"2","num_of_stars"=>"5"})
   def form_fillout_selector(hash)
     hash.each do |id,value|
       option = Selenium::WebDriver::Support::Select.new(driver.find_element(:id => id))
@@ -303,7 +441,13 @@ class TelluriumDriver
     end
 
   end
-  
+
+  # Waits for the element specified by the identifiers then clicks where it should be
+  #
+  # ==== Attributes
+  # 
+  # * +sym+ - :id, :css, or :name, etc
+  # * +id+ - The text corresponding with the symbol.
   def wait_and_hover_click(sym,id)
     found = false
   #wait until an element with sym,id is displayed. When it is, hover click it
@@ -321,6 +465,7 @@ class TelluriumDriver
     self.hover_click(@element)
   end
 
+  # Closes the webdriver
   def close
     driver.quit
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tellurium_driver
 version: !ruby/object:Gem::Version
-  version: 1.1.23
+  version: 1.2.3
 platform: ruby
 authors:
 - Noah Prince
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-29 00:00:00.000000000 Z
+date: 2014-06-07 00:00:00.000000000 Z
 dependencies: []
 description: Provides useful extra methods for Selenium WebDriver, especially helpful
   in javascript webapps