watir-classic 3.3.0 → 3.4.0

data/lib/watir-classic/page-container.rb

@@ -4,36 +4,19 @@ module Watir
   module PageContainer
     include Watir::Exception
 
-    # This method checks the currently displayed page for http errors, 404, 500 etc
-    # It gets called internally by the wait method, so a user does not need to call it explicitly
-
-    def check_for_http_error
-      # check for IE7
-      n = self.document.invoke('parentWindow').navigator.appVersion
-      m=/MSIE\s(.*?);/.match( n )
-      if m and m[1] =='7.0'
-        if m = /HTTP (\d\d\d.*)/.match( self.title )
-          raise NavigationException, m[1]
-        end
-      else
-        # assume its IE6
-        url = self.document.location.href
-        if /shdoclc.dll/.match(url)
-          m = /id=IEText.*?>(.*?)</i.match(self.html)
-          raise NavigationException, m[1] if m
-        end
-      end
-      false
-    end
-
-    # The HTML Page
-    def page
-      document.documentelement
-    end
-
-    private :page
-
-    # Execute the given JavaScript string
+    # Execute the given JavaScript string in the context of the current page.
+    #
+    # @example
+    #   browser.execute_script "var a=1; var b=a+1; return b"
+    #
+    # @example
+    #   browser.execute_script("return {a: 1, b: 2}")["b"] # => 1
+    #
+    # @note It is needed to call return inside of the JavaScript if the value
+    #   is needed at Ruby side.
+    #
+    # @return [Object] appropriate type of the object, which is returned from the
+    #   JavaScript via "return" keyword or nil when "return" is omitted.
     def execute_script(source)
       result = nil
       begin
@@ -50,36 +33,24 @@ module Watir
       MultiJson.load(result)["value"] rescue nil
     end
 
-    # The HTML of the current page
+    # @return [String] html of the current page.
     def html
       page.outerhtml
     end
 
-    # The url of the page object.
+    # @return [String] url of the page.
     def url
       page.document.location.href
     end
 
-    # The text of the current page
+    # @return [String] text of the page.
     def text
       page.innertext.strip
     end
 
-    def set_container container
-      @container = container
-      @page_container = self
-    end
-
-    # Search the current page for specified text or regexp.
-    # Returns the index if the specified text was found.
-    # Returns matchdata object if the specified regexp was found.
-    #
-    # *Deprecated*
-    # Instead use
-    #   IE#text.include? target
-    # or
-    #   IE#text.match target
+    # @deprecated Use "browser.text.include?(target)" or "browser.text.match(target) instead."
     def contains_text(target)
+      Kernel.warn "Deprecated(Element#contains_text) - use \"browser.text.include?(target)\" or \"browser.text.match(target)\" instead."
       if target.kind_of? Regexp
         self.text.match(target)
       elsif target.kind_of? String
@@ -89,6 +60,14 @@ module Watir
       end
     end
 
+    # @private
+    def set_container container
+      @container = container
+      @page_container = self
+    end
+
+    private
+
     def with_json2_if_needed source
       %Q[
       (function() {
@@ -104,7 +83,10 @@ module Watir
       ]
     end
 
-    private :with_json2_if_needed
+    # The HTML Page
+    def page
+      document.documentelement
+    end
 
   end # module
 end

data/lib/watir-classic/process.rb

@@ -1,8 +1,9 @@
 module Watir
+  # @private
   module Process
     
     # Returns the number of windows processes running with the specified name.
-    def self.count name
+    def self.count(name)
       mgmt = WIN32OLE.connect('winmgmts:\\\\.')
       processes = mgmt.InstancesOf('win32_process')
       processes.extend Enumerable
@@ -13,8 +14,9 @@ module Watir
   
   class IE
     # Returns the number of IEXPLORE processes currently running.
+    # @return [Fixnum] number of ie processes.
     def self.process_count
       Watir::Process.count 'iexplore.exe'
     end    
   end
-end
+end

data/lib/watir-classic/screenshot.rb

@@ -3,15 +3,20 @@ require "base64"
 require "win32/screenshot"
 
 module Watir
+  # Returned by {IE#screenshot}.
   class Screenshot
     def initialize(browser_hwnd)
       @hwnd = browser_hwnd
     end
 
+    # Save screenshot to the file.
+    #
+    # @param [String] path path to the image.
     def save(path)
       screenshot.write(path)
     end
 
+    # @return [String] image in png format.
     def png
       path = File.expand_path "temporary-image-#{Time.now.to_i}.png", Dir.tmpdir
       save path
@@ -20,6 +25,7 @@ module Watir
       File.delete path rescue nil
     end
 
+    # @return [String] {#png} image formatted as base64.
     def base64
       Base64.encode64 png
     end

data/lib/watir-classic/supported_elements.rb

@@ -2,7 +2,30 @@ module Watir
   module Container
 
     class << self
-      def support_element method_name, args={}
+
+      private
+
+      # @!macro support_element
+      #   @!method $1
+      #   Create an $1 html element instance.
+      #
+      #   Elements can be searched by using different locators.
+      #   
+      #   @example Search by partial text:
+      #     browser.$1(:text => /partial text/)
+      #   
+      #   @example Search by id:
+      #     browser.$1(:id => "htmlid")
+      #
+      #   @example Search by any arbitrary html attribute:
+      #     browser.$1(:foo => "value-of-foo-attribute)
+      #
+      #   @example Search by multiple attributes, all provided locators should evaluate to true - only then element is considered to be found:
+      #     browser.$1(:text => "some text", :class => "css class")
+      #
+      #   @example It is also possible to search for multiple elements of the same type like this:
+      #     browser.divs(:class => "foo") # => instance of Watir::DivCollection
+      def support_element(method_name, args={})
         klass = args[:class] || method_name.to_s.capitalize
         super_class = args[:super_class] || "Element"
 
@@ -28,20 +51,8 @@ module Watir
         ]
       end
 
-      private :support_element
-    end
-
-    def format_specifiers(tag_name, how, what)
-      defaults = {:tag_name => [tag_name].flatten.map(&:to_s)}
-      formatted_specifiers = defaults.merge(what ? {how => what} : how)
-      if (formatted_specifiers[:css] || formatted_specifiers[:xpath]) && formatted_specifiers.size > 2
-        raise ArgumentError, ":xpath and :css specifiers should be the only one when used in #{formatted_specifiers.inspect}"
-      end
-      formatted_specifiers
     end
 
-    private :format_specifiers
-
     support_element :a, :class => :Link
     alias_method :link, :a
     alias_method :links, :as
@@ -103,7 +114,6 @@ module Watir
     support_element :hgroup
     support_element :hidden, :super_class => :TextField, :super_collection => :InputElement
     support_element :hr
-    # html and htmls?!
     support_element :i
     support_element :img, :class => :Image
     alias_method :image, :img
@@ -168,5 +178,17 @@ module Watir
     support_element :var
     support_element :video
     support_element :wbr
+
+    private
+
+    def format_specifiers(tag_name, how, what)
+      defaults = {:tag_name => [tag_name].flatten.map(&:to_s)}
+      formatted_specifiers = defaults.merge(what ? {how => what} : how)
+      if (formatted_specifiers[:css] || formatted_specifiers[:xpath]) && formatted_specifiers.size > 2
+        raise ArgumentError, ":xpath and :css specifiers should be the only one when used in #{formatted_specifiers.inspect}"
+      end
+      formatted_specifiers
+    end
+
   end
 end

data/lib/watir-classic/table.rb

@@ -1,13 +1,16 @@
 module Watir
 
   module TableContainer
-    # Returns a row in the table
-    #   * index         - the index of the row
+    # @return [TableRow] a row in the {Table}.
+    # @param [Fixnum] index row number to retrieve.
+    # @macro exists
     def [](index)
       assert_exists
       TableRow.new(self, :ole_object => @o.rows.item(index))
     end
     
+    # @return [Array<String>] array of table element texts.
+    # @macro exists
     def strings
       assert_exists
       rows_memo = []
@@ -23,22 +26,28 @@ module Watir
   end
 
   module TableElementsContainer
+
+    private
+
     def table_elements(klass, tags, how, what, ole_collection)
       specifiers = format_specifiers(tags, how, what)
       klass.new(self, specifiers, ole_collection)
     end
 
-    private :table_elements
   end
 
   module TableCellsContainer
     include TableElementsContainer
 
+    # @return [TableCellCollection] cells inside of the {Table}.
+    # @macro exists
     def cells(how={}, what=nil)
       assert_exists
       table_elements(TableCellCollection, [:th, :td], how, what, @o.cells)
     end
 
+    # @return [TableCell] cell inside of the {Table}.
+    # @macro exists
     def cell(how={}, what=nil)
       specifiers = format_specifiers([:th, :td], how, what)
       index = specifiers.delete(:index) || 0
@@ -49,11 +58,15 @@ module Watir
   module TableRowsContainer
     include TableElementsContainer
 
+    # @return [TableRowCollection] rows inside of the {Table}.
+    # @macro exists
     def rows(how={}, what=nil)
       assert_exists
       table_elements(TableRowCollection, [:tr], how, what, @o.rows)
     end
 
+    # @return [TableRow] row inside of the {Table}.
+    # @macro exists
     def row(how={}, what=nil)
       specifiers = format_specifiers([:tr], how, what)
       index = specifiers.delete(:index) || 0
@@ -61,11 +74,7 @@ module Watir
     end
   end
 
-  # This class is used for dealing with tables.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#table method
-  #
-  # many of the methods available to this object are inherited from the Element class
-  #
+  # Returned by {Container#table}
   class Table < Element
     include TableContainer
     include TableRowsContainer
@@ -73,81 +82,39 @@ module Watir
 
     attr_ole :rules
 
-    # override the highlight method, as if the tables rows are set to have a background color,
-    # this will override the table background color, and the normal flash method won't work
-    def highlight(set_or_clear)
-      if set_or_clear == :set
-        begin
-          @original_border = @o.border.to_i
-          if @o.border.to_i==1
-            @o.border = 2
-          else
-            @o.border = 1
-          end
-        rescue
-          @original_border = nil
-        end
-      else
-        begin
-          @o.border= @original_border unless @original_border == nil
-          @original_border = nil
-        rescue
-          # we could be here for a number of reasons...
-        ensure
-          @original_border = nil
-        end
-      end
-      super
-    end
-    
-    # this method is used to populate the properties in the to_s method
-    def table_string_creator
-      n = []
-      n << "rows:".ljust(TO_S_SIZE) + self.row_count.to_s
-      n << "cols:".ljust(TO_S_SIZE) + self.column_count.to_s
-      return n
-    end
-    private :table_string_creator
-    
-    # returns the properties of the object in a string
-    # raises an ObjectNotFound exception if the object cannot be found
-    def to_s
-      assert_exists
-      r = string_creator
-      r += table_string_creator
-      return r.join("\n")
-    end
-    
-    # Returns the number of rows inside the table, including rows in nested tables.
+    # @return [Fixnum] number of rows inside of the table, including rows from
+    #   nested tables.
+    # @macro exists
     def row_count
       assert_exists
       rows.length
     end
 
-    # This method returns the number of columns in a row of the table.
-    # Raises an UnknownObjectException if the table doesn't exist.
-    #   * index         - the index of the row
+    # @return [Fixnum] number of columns inside of the table, including columns from
+    #   nested tables.
+    # @param [Fixnum] index the number of row.
+    # @macro exists
     def column_count(index=0)
       assert_exists
       rows[index].cells.length
     end
     
-    # Returns an array containing all the text values in the specified column
-    # Raises an UnknownCellException if the specified column does not exist in every
-    # Raises an UnknownObjectException if the table doesn't exist.
-    # row of the table
-    #   * columnnumber  - column index to extract values from
+    # @return [Array<String>] array of each row's specified column text.
+    # @param [Fixnum] columnnumber the number of column to extract text from.
+    # @macro exists
     def column_values(columnnumber)
-      return (0..row_count - 1).collect {|i| self[i][columnnumber].text}
+      (0..row_count - 1).collect {|i| self[i][columnnumber].text}
     end
     
-    # Returns an array containing all the text values in the specified row
-    # Raises an UnknownObjectException if the table doesn't exist.
-    #   * rownumber  - row index to extract values from
+    # @return [Array<String>] array of each column's text on specified row.
+    # @param [Fixnum] rownumber the number of row to extract column texts from.
+    # @macro exists
     def row_values(rownumber)
-      return (0..column_count(rownumber) - 1).collect {|i| self[rownumber][i].text}
+      (0..column_count(rownumber) - 1).collect {|i| self[rownumber][i].text}
     end
     
+    # @return [Array<Hash>] array with hashes of table data.
+    # @macro exists
     def hashes
       assert_exists
 
@@ -176,6 +143,41 @@ module Watir
       end
       rows_memo
     end
+
+    def to_s
+      assert_exists
+      r = string_creator
+      r += table_string_creator
+      r.join("\n")
+    end
+
+    private
+
+    # this method is used to populate the properties in the to_s method
+    def table_string_creator
+      n = []
+      n << "rows:".ljust(TO_S_SIZE) + self.row_count.to_s
+      n << "cols:".ljust(TO_S_SIZE) + self.column_count.to_s
+      n
+    end
+
+    # override the highlight method, as if the tables rows are set to have a background color,
+    # this will override the table background color, and the normal flash method won't work
+    def set_highlight
+      perform_highlight do
+        @original_border = @o.border.to_i
+        @o.border = @original_border + 1
+        super
+      end
+    end
+
+    def clear_highlight
+      perform_highlight do
+        @o.border = @original_border if @original_border
+        super
+      end
+    end
+        
   end
 
   class TableSection < Element
@@ -184,24 +186,30 @@ module Watir
     include TableCellsContainer
   end
 
+  # Returned by {Container#tr}.
   class TableRow < Element
     include TableCellsContainer
 
-    # this method iterates through each of the cells in the row. Yields a TableCell object
+    # Iterate over each of the cell in the row.
+    # @yieldparam [TableCell] cell cell instance.
     def each
       locate
       cells.each {|cell| yield cell}
     end
     
-    # Returns an element from the row as a TableCell object
+    # @return [TableCell] cell from the row.
+    # @param [Fixnum] index cell index in the row.
+    # @macro exists
     def [](index)
       assert_exists
       if cells.length <= index
         raise UnknownCellException, "Unable to locate a cell at index #{index}" 
       end
-      return cells[index]
+      cells[index]
     end
     
+    # @return [Fixnum] cells count in the row.
+    # @macro exists
     def column_count
       assert_exists
       cells.length
@@ -209,12 +217,14 @@ module Watir
 
   end
   
-  # this class is a table cell - when called via the Table object
+  # Returned by {Container#td} and {Container#th}.
   class TableCell < Element
     attr_ole :headers
 
     alias_method :to_s, :text
     
+    # @return [Fixnum] colspan attribute value.
+    # @macro exists
     def colspan
       locate
       @o.colSpan