watir-webdriver 0.6.1 → 0.6.2

data/lib/watir-webdriver/cell_container.rb

@@ -1,6 +1,12 @@
 module Watir
   module CellContainer
 
+    #
+    # Returns table cell.
+    #
+    # @return [TableCell]
+    #
+
     def cell(*args)
       cell = TableCell.new(self, extract_selector(args).merge(:tag_name => /^(th|td)$/))
       cell.locator_class = ChildCellLocator
@@ -8,6 +14,12 @@ module Watir
       cell
     end
 
+    #
+    # Returns table cells collection.
+    #
+    # @return [TableCell]
+    #
+
     def cells(*args)
       cells = TableCellCollection.new(self, extract_selector(args).merge(:tag_name => /^(th|td)$/))
       cells.locator_class = ChildCellLocator
@@ -15,5 +27,5 @@ module Watir
       cells
     end
 
-  end
-end
+  end # CellContainer
+end # Watir

data/lib/watir-webdriver/container.rb

@@ -4,14 +4,36 @@ module Watir
     include XpathSupport
     include Atoms
 
+    #
+    # Returns element.
+    #
+    # @example
+    #   browser.element(:data_bind => 'func')
+    #
+    # @return [HTMLElement]
+    #
+
     def element(*args)
       HTMLElement.new(self, extract_selector(args))
     end
 
+    #
+    # Returns element collection.
+    #
+    # @example
+    #   browser.elements(:data_bind => 'func')
+    #
+    # @return [HTMLElementCollection]
+    #
+
     def elements(*args)
       HTMLElementCollection.new(self, extract_selector(args))
     end
 
+    #
+    # @api private
+    #
+
     def extract_selector(selectors)
       case selectors.size
       when 2

data/lib/watir-webdriver/cookies.rb

@@ -4,12 +4,37 @@ module Watir
       @control = control
     end
 
+    #
+    # Returns array of cookies.
+    #
+    # @example
+    #   browser.cookies.to_a
+    #   #=> {:name=>"my_session", :value=>"BAh7B0kiD3Nlc3Npb25faWQGOgZFRkk", :domain=>"mysite.com"}
+    #
+    # @return [Array<Hash>]
+    #
+
     def to_a
       @control.all_cookies.each do |e|
         e[:expires] = to_time(e[:expires]) if e[:expires]
       end
     end
 
+    #
+    # Adds new cookie.
+    #
+    # @example
+    #   browser.cookies.add 'my_session', 'BAh7B0kiD3Nlc3Npb25faWQGOgZFRkk', :secure => true
+    #
+    # @param [String] name
+    # @param [String] value
+    # @param [Hash] opts
+    # @option opts [Boolean] :secure
+    # @option opts [String] :path
+    # @option opts [] :expires  TODO what type
+    # @option opts [String] :domain
+    #
+
     def add(name, value, opts = {})
       cookie = {
         :name    => name,
@@ -26,10 +51,26 @@ module Watir
       @control.add_cookie cookie
     end
 
+    #
+    # Deletes cookie by given name.
+    #
+    # @example
+    #   browser.cookies.delete 'my_session'
+    #
+    # @param [String] name
+    #
+
     def delete(name)
       @control.delete_cookie(name)
     end
 
+    #
+    # Deletes all cookies.
+    #
+    # @example
+    #   browser.cookies.clear
+    #
+
     def clear
       @control.delete_all_cookies
     end

data/lib/watir-webdriver/element_collection.rb

@@ -13,6 +13,14 @@ module Watir
       @selector = selector
     end
 
+    #
+    # Yields each element in collection.
+    #
+    # @example
+    #   divs = browser.divs(:class => 'kls')
+    #   divs.each do |div|
+    #     puts div.text
+    #   end
     #
     # @yieldparam [Watir::Element] element Iterate through the elements in this collection.
     #
@@ -22,7 +30,9 @@ module Watir
     end
 
     #
-    # @return [Fixnum] The number of elements in this collection.
+    # Returns number of elements in collection.
+    #
+    # @return [Fixnum]
     #
 
     def length
@@ -37,7 +47,7 @@ module Watir
     # Also note that because of Watir's lazy loading, this will return an Element
     # instance even if the index is out of bounds.
     #
-    # @param [Fixnum] n Index of wanted element, 0-indexed
+    # @param [Fixnum] idx Index of wanted element, 0-indexed
     # @return [Watir::Element] Returns an instance of a Watir::Element subclass
     #
 
@@ -66,7 +76,7 @@ module Watir
     end
 
     #
-    # This collection as an Array
+    # This collection as an Array.
     #
     # @return [Array<Watir::Element>]
     #

data/lib/watir-webdriver/elements/button.rb

@@ -20,6 +20,8 @@ module Watir
     # For input elements, returns the "value" attribute.
     # For button elements, returns the inner text.
     #
+    # @return [String]
+    #
 
     def text
       assert_exists
@@ -37,7 +39,7 @@ module Watir
     end
 
     #
-    # Returns true if this element is enabled
+    # Returns true if this element is enabled.
     #
     # @return [Boolean]
     #

data/lib/watir-webdriver/elements/checkbox.rb

@@ -4,16 +4,17 @@ module Watir
   class CheckBox < Input
 
     #
-    # Set this checkbox to the given value
-    #
-    # Example:
+    # Sets checkbox to the given value.
     #
+    # @example
     #   checkbox.set?        #=> false
     #   checkbox.set
     #   checkbox.set?        #=> true
     #   checkbox.set(false)
     #   checkbox.set?        #=> false
     #
+    # @param [Boolean] bool
+    #
 
     def set(bool = true)
       assert_exists
@@ -27,7 +28,7 @@ module Watir
     end
 
     #
-    # returns true if the element is checked
+    # Returns true if the element is checked
     # @return [Boolean]
     #
 
@@ -37,7 +38,7 @@ module Watir
     end
 
     #
-    # Unset this checkbox.
+    # Unsets checkbox.
     #
     # Same as +set(false)+
     #
@@ -45,6 +46,7 @@ module Watir
     def clear
       set false
     end
+
   end # CheckBox
 
   module Container
@@ -62,4 +64,4 @@ module Watir
       CheckBox
     end
   end # CheckBoxCollection
-end
+end # Watir

data/lib/watir-webdriver/elements/dlist.rb

@@ -1,12 +1,12 @@
 module Watir
   class DList < HTMLElement
-    
+
     def to_hash
       keys = dts.map { |e| e.text }
       values = dds.map { |e| e.text }
 
       Hash[keys.zip(values)]
     end
-    
-  end
-end
+
+  end # DList
+end # Watir

data/lib/watir-webdriver/elements/element.rb

@@ -14,14 +14,14 @@ module Watir
     include EventuallyPresent
 
     #
-    # need to add :id manually since it's not specified in the HTML spec.
+    # temporarily add :id and :class_name manually since they're no longer specified in the HTML spec.
     #
     # @see http://html5.org/r/6605
-    # @see http://www.w3.org/Bugs/Public/show_bug.cgi?id=13610
+    # @see http://html5.org/r/7174
     #
-    # TODO: use IDL from DOM core?
+    # TODO: use IDL from DOM core - http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html
     #
-    attributes :string => [:id]
+    attributes :string => [:id, :class_name]
 
     def initialize(parent, selector)
       @parent   = parent
@@ -33,6 +33,12 @@ module Watir
       end
     end
 
+    #
+    # Returns true if element exists.
+    #
+    # @return [Boolean]
+    #
+
     def exists?
       assert_exists
       true
@@ -49,6 +55,14 @@ module Watir
       end
     end
 
+    #
+    # Returns true if two elements are equal.
+    #
+    # @example
+    #   browser.a(:id => "foo") == browser.a(:id => "foo")
+    #   #=> true
+    #
+
     def ==(other)
       return false unless other.kind_of? self.class
 
@@ -61,31 +75,40 @@ module Watir
       @element ? @element.hash : super
     end
 
+    #
+    # Returns the text of the element.
+    #
+    # @return [String]
+    #
+
     def text
       assert_exists
       @element.text
     end
 
+    #
+    # Returns tag name of the element.
+    #
+    # @return [String]
+    #
+
     def tag_name
       assert_exists
       @element.tag_name.downcase
     end
 
     #
-    # Clicks the element, optionally while pressing the given mofifier keys.
+    # Clicks the element, optionally while pressing the given modifier keys.
     # Note that support for holding a modifier key is currently experimental,
     # and may not work at all.
     #
     # @example Click an element
-    #
     #   element.click
     #
     # @example Click an element with shift key pressed
-    #
     #   element.click(:shift)
     #
     # @example Click an element with several modifier keys pressed
-    #
     #   element.click(:shift, :control)
     #
     # @param [:shift, :alt, :control, :command, :meta] Modifier key(s) to press while clicking.
@@ -113,10 +136,11 @@ module Watir
 
     #
     # Double clicks the element.
-    #
     # Note that browser support may vary.
     #
-
+    # @example
+    #   browser.a(:id => "foo").double_click
+    #
 
     def double_click
       assert_exists
@@ -128,9 +152,11 @@ module Watir
 
     #
     # Right clicks the element.
-    #
     # Note that browser support may vary.
     #
+    # @example
+    #   browser.a(:id => "foo").right_click
+    #
 
     def right_click
       assert_exists
@@ -142,8 +168,10 @@ module Watir
 
     #
     # Moves the mouse to the middle of this element.
+    # Note that browser support may vary.
     #
-    # Note that browser/platform support may vary.
+    # @example
+    #   browser.a(:id => "foo").hover
     #
 
     def hover
@@ -155,12 +183,11 @@ module Watir
 
     #
     # Drag and drop this element on to another element instance.
+    # Note that browser support may vary.
     #
-    # Example:
-    #
+    # @example
     #    a = browser.div(:id => "draggable")
     #    b = browser.div(:id => "droppable")
-    #
     #    a.drag_and_drop_on b
     #
 
@@ -176,12 +203,13 @@ module Watir
 
     #
     # Drag and drop this element by the given offsets.
+    # Note that browser support may vary.
     #
-    # Example:
-    #
-    #    a = browser.div(:id => "draggable")
+    # @example
+    #    browser.div(:id => "draggable").drag_and_drop_by 100, -200
     #
-    #    a.drag_and_drop_by 100, -200
+    # @param [Fixnum] right_by
+    # @param [Fixnum] down_by
     #
 
     def drag_and_drop_by(right_by, down_by)
@@ -193,15 +221,33 @@ module Watir
              perform
     end
 
+    #
+    # Flashes (change background color far a moment) element.
+    #
+    # @example
+    #    browser.div(:id => "draggable").flash
+    #
+
     def flash
-      original_color = style("backgroundColor")
+      background_color = style("backgroundColor")
+      element_color = driver.execute_script("arguments[0].style.backgroundColor", @element)
 
       10.times do |n|
-        color = (n % 2 == 0) ? "red" : original_color
+        color = (n % 2 == 0) ? "red" : background_color
         driver.execute_script("arguments[0].style.backgroundColor = '#{color}'", @element)
       end
+
+      driver.execute_script("arguments[0].style.backgroundColor = arguments[1]", @element, element_color)
+
+      self
     end
 
+    #
+    # Returns value of the element.
+    #
+    # @return [String]
+    #
+
     def value
       assert_exists
 
@@ -212,25 +258,56 @@ module Watir
       end
     end
 
+    #
+    # Returns given attribute value of element.
+    #
+    # @example
+    #   browser.a(:id => "foo").attribute_value "href"
+    #   #=> "http://watir.com"
+    #
+    # @param [String] attribute_name
+    # @return [String]
+    #
+
     def attribute_value(attribute_name)
       assert_exists
       @element.attribute attribute_name
     end
 
+    #
+    # Returns inner HTML code of element.
+    #
+    # @example
+    #   browser.div(:id => "foo").html
+    #   #=> "<a>Click</a>"
+    #
+    # @return [String]
+    #
+
     def html
       assert_exists
       execute_atom(:getOuterHtml, @element).strip
     end
 
+    #
+    # Sends sequence of keystrokes to element.
+    #
+    # @example
+    #   browser.div(:id => "foo").send_keys "Watir", :return
+    #
+    # @param [String, Symbol] *args
+    #
+
     def send_keys(*args)
       assert_exists
       @element.send_keys(*args)
     end
 
     #
-    # Note: Firefox queues focus events until the window actually has focus.
+    # Focuses element.
+    # Note that Firefox queues focus events until the window actually has focus.
     #
-    # See http://code.google.com/p/selenium/issues/detail?id=157
+    # @see http://code.google.com/p/selenium/issues/detail?id=157
     #
 
     def focus
@@ -238,11 +315,29 @@ module Watir
       driver.execute_script "return arguments[0].focus()", @element
     end
 
+    #
+    # Returns true if this element is focused.
+    #
+    # @return [Boolean]
+    #
+
     def focused?
       assert_exists
       @element == driver.switch_to.active_element
     end
 
+    #
+    # Simulates JavaScript events on element.
+    # Note that you may omit "on" from event name.
+    #
+    # @example
+    #   browser.a(:id => "foo").fire_event :click
+    #   browser.a(:id => "foo").fire_event "mousemove"
+    #   browser.a(:id => "foo").fire_event "onmouseover"
+    #
+    # @param [String, Symbol] event_name
+    #
+
     def fire_event(event_name)
       assert_exists
       event_name = event_name.to_s.sub(/^on/, '').downcase
@@ -250,6 +345,10 @@ module Watir
       execute_atom :fireEvent, @element, event_name
     end
 
+    #
+    # Returns parent element of current element.
+    #
+
     def parent
       assert_exists
 
@@ -278,7 +377,9 @@ module Watir
     end
 
     #
-    # Returns true if this element is visible on the page
+    # Returns true if this element is visible on the page.
+    #
+    # @return [Boolean]
     #
 
     def visible?
@@ -287,8 +388,9 @@ module Watir
     end
 
     #
-    # Returns true if the element exists and is visible on the page
+    # Returns true if the element exists and is visible on the page.
     #
+    # @return [Boolean]
     # @see Watir::Wait
     #
 
@@ -300,6 +402,19 @@ module Watir
       false
     end
 
+    #
+    # Returns given style property of this element.
+    #
+    # @example
+    #   browser.a(:id => "foo").style
+    #   #=> "display: block"
+    #   browser.a(:id => "foo").style "display"
+    #   #=> "block"
+    #
+    # @param [String] property
+    # @return [String]
+    #
+
     def style(property = nil)
       if property
         assert_exists
@@ -309,6 +424,10 @@ module Watir
       end
     end
 
+    #
+    # Runs checkers.
+    #
+
     def run_checkers
       @parent.run_checkers
     end
@@ -316,9 +435,9 @@ module Watir
     #
     # Cast this Element instance to a more specific subtype.
     #
-    # Example:
-    #
-    #   browser.element(:xpath => "//input[@type='submit']").to_subtype #=> #<Watir::Button>
+    # @example
+    #   browser.element(:xpath => "//input[@type='submit']").to_subtype
+    #   #=> #<Watir::Button>
     #
 
     def to_subtype
@@ -347,6 +466,12 @@ module Watir
       klass.new(@parent, :element => elem)
     end
 
+    #
+    # Returns browser.
+    #
+    # @return [Watir::Browser]
+    #
+
     def browser
       @parent.browser
     end