awetestlib 0.1.13-x86-mingw32 → 0.1.14-x86-mingw32

data/lib/awetestlib/regression/find.rb

@@ -1,17 +1,88 @@
 module Awetestlib
   module Regression
+    # Methods to fetch references to DOM elements for assigning to variables.  Includes collections of elements.
+    # Primary use is to limit the scope of other commands to the element passed in their *browser* parameter.
+    # (example here)
     module Find
 
-      def get_select_list(browser, how, what, desc = '')
-        list = browser.select_list(how, what)
-        if validate(browser, @myName, __LINE__)
-          passed_to_log("Select list #{how}='#{what}' found and returned.")
-          return list
+      # @!group Core
+
+      # Return a reference to a DOM element specified by its type *element*, attribute *how*, and the
+      # contents of that attribute *what*.  Some elements may require use of the *:value* attribute in addition
+      # to the designated one.  The target contents for *:value* are supplied in *value*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] element The kind of element to click. Must be one of the elements recognized by Watir.
+      #   Some common values are :link, :button, :image, :div, :span.
+      # @param [Symbol] how The element attribute used to identify the specific element.
+      #   Valid values depend on the kind of element.
+      #   Common values: :text, :id, :title, :name, :class, :href (:link only)
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
+      # @param [String, Regexp] value A string or a regular expression to be found in the *:value* attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      def get_element(browser, element, how, what, value = nil, desc = '')
+        msg    = build_message("Return #{element} with :#{how}=#{what}", value, desc)
+        target = nil
+        what = Regexp.new(Regexp.escape(what)) unless how == :index or what.is_a?(Regexp)
+        case element
+          when :link
+            target = browser.link(how, what)
+          when :button
+            target = browser.button(how, what)
+          when :div
+            target = browser.div(how, what)
+          when :checkbox
+            target = browser.checkbox(how, what, value)
+          when :text_field, :textfield
+            target = browser.text_field(how, what)
+          when :image
+            target = browser.image(how, what)
+          when :file_field, :filefield
+            target = browser.file_field(how, what)
+          when :form
+            target = browser.form(how, what)
+          when :frame
+            target = browser.frame(how, what)
+          when :radio
+            target = browser.radio(how, what, value)
+          when :span
+            target = browser.span(how, what)
+          when :table
+            target = browser.table(how, what)
+          when :li
+            target = browser.li(how, what)
+          when :select_list, :selectlist
+            target = browser.select_list(how, what)
+          when :hidden
+            target = browser.hidden(how, what)
+          when :area
+            target = browser.area(how, what)
+          else
+            target = browser.element(how, what)
+        end
+        if target.exists?
+          passed_to_log(msg)
+          target
+        else
+          failed_to_log(msg)
+          nil
+        end
+      rescue => e
+        if not rescue_me(e, __method__, "browser.#{element}(#{how}, '#{what}')", "#{browser.class}", target)
+          raise e
         end
-      rescue
-        failed_to_log("Unable to return select list #{how}='#{what}': '#{$!}' (#{__LINE__})")
       end
 
+      # Return an array containing the options available for selection in a select_list identifified by
+      # its attribute *how*, and the contents of that attribute *what*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] how The element attribute used to identify the specific element.
+      #   Valid values depend on the kind of element.
+      #   Common values: :text, :id, :title, :name, :class, :href (:link only)
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute
+      # that uniquely identifies the element.
+      # @param [Boolean] dump If set to true, a dump of the contents of the options will go to the log.
+      # See Utilities#dump_select_list_options
+      # @return [Array]
       def get_select_options(browser, how, what, dump = false)
         list = browser.select_list(how, what)
         dump_select_list_options(list) if dump
@@ -20,14 +91,15 @@ module Awetestlib
         failed_to_log("Unable to get select options for #{how}=>#{what}.  '#{$!}'")
       end
 
-      def get_select_options_by_id(browser, strg, dump = false)
-        get_select_options(browser, :id, strg, dump)
-      end
-
-      def get_select_options_by_name(browser, strg, dump = false)
-        get_select_options(browser, :name, strg, dump)
-      end
-
+      # Return an array containing the _selected_ options in a select_list identified by
+      # its attribute *how*, and the contents of that attribute *what*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] how The element attribute used to identify the specific element.
+      #   Valid values depend on the kind of element.
+      #   Common values: :text, :id, :title, :name, :class, :href (:link only)
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute
+      # that uniquely identifies the element.
+      # @return [Array]
       def get_selected_options(browser, how, what)
         begin
           list = browser.select_list(how, what)
@@ -36,318 +108,120 @@ module Awetestlib
             raise e
           end
         end
-        list.selected_options
-      end
-
-      def get_selected_options_by_id(browser, strg)
-        get_selected_options(browser, :id, strg)
+        list.selected_options if list
       end
 
-      alias get_selected_option_by_id get_selected_options_by_id
-
-      def get_selected_options_by_name(browser, strg)
-        get_selected_options(browser, :name, strg)
-      end
-
-      alias get_selected_option_by_name get_selected_options_by_name
-
-=begin rdoc
-  :category: A_rdoc_test
-Returns a reference to a division element.  Used to assign a div element to a variable
-which can then be passed to methods that require a *browser* parameter.
-
-_Parameters_::
-
-*browser* - a reference to the browser window or container element to be tested
-
-*how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
-Common values: :text, :id, :title, :name, :class, :href (:link only)
-
-*what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
-
-*desc* - a string containing a message or description intended to appear in the log and/or report output
-
-_Example_
-
-  mainwindow = open_browser('www.myapp.com')  # open a browser to www.google.com
-  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
-  popup = attach_browser(mainwindow, :url, '[url of new window]') *or*
-  popup = attach_browser(mainwindow, :title, '[title of new window]')
-
-=end
-
+      # Return a reference to a div element identified by the contents *what* of its attribute *how*.
+      # This differs from get_element in that it waits for the element to exist before trying to return it.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] how The element attribute used to identify the specific element.
+      #   Valid values depend on the kind of element.
+      #   Common values: :text, :id, :title, :name, :class, :href (:link only)
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute
+      # that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @param [Boolean] dbg If set to true additional debug logging is performed.
+      # @return [Watir::Div]
       def get_div(browser, how, what, desc = '', dbg = false)
-        msg = "Get division #{how}=>#{what}."
-        msg << " #{desc}" if desc.length > 0
+        msg = build_message("Get :div #{how}=>#{what}.", desc)
         Watir::Wait.until { browser.div(how, what).exists? }
         div = browser.div(how, what)
         debug_to_log(div.inspect) if dbg
-        if validate(browser, @myName, __LINE__)
-          if div
-            passed_to_log(msg)
-            return div
-          else
-            failed_to_log(msg)
-          end
+        if div
+          passed_to_log(msg)
+          return div
+        else
+          failed_to_log(msg)
         end
       rescue
         failed_to_log("Unable to '#{msg}' '#{$!}'")
       end
 
-      def get_div_by_id(browser, strg, desc = '', dbg = false)
-        get_div(browser, :id, strg, desc, dbg)
-      end
-
-=begin rdoc
-  :category: A_rdoc_test
-Returns a reference to a division element identified by the value in its class attribute. Calls get_div()
-
-_Parameters_::
-
-*browser* - a reference to the browser window or container element to be tested
-
-*strg* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
-
-*desc* - a string containing a message or description intended to appear in the log and/or report output
-
-_Example_
-
-  mainwindow = open_browser('www.myapp.com')  # open a browser to www.google.com
-  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
-  popup = attach_browser(mainwindow, :url, '[url of new window]') *or*
-  popup = attach_browser(mainwindow, :title, '[title of new window]')
-
-=end
-
-      def get_div_by_class(browser, strg, desc = '', dbg = false)
-        get_div(browser, :class, strg, desc, dbg)
-      end
-
-      def get_div_by_text(browser, strg, desc = '', dbg = false)
-        get_div(browser, :text, strg, desc, dbg)
-      end
-
-      def get_form(browser, how, strg)
+      # Return a reference to a _span_ element identified by the contents *what* of its attribute *how*.
+      # This differs from get_element in that it waits for the element to exist before trying to return it.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] how The element attribute used to identify the specific element.
+      #   Valid values depend on the kind of element.
+      #   Common values: :text, :id, :title, :name, :class, :href (:link only)
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute
+      # that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::Span]
+      def get_span(browser, how, what, desc = '')
         begin
-          #       Watir::Wait.until( browser.form(how, strg).exists? )  # fails in wait_until
+          Watir::Wait.until { browser.span(how, what).exists? }
         rescue => e
-          if not rescue_me(e, __method__, "browser.form(#{how}, '#{strg}').exists?", "#{browser.class}")
+          if not rescue_me(e, __method__, "browser.span(#{how}, '#{what}').exists?", "#{browser.class}")
             raise e
           end
         end
-        myForm = browser.form(how, strg)
-        if validate(browser, @myName, __LINE__)
-          passed_to_log("Form #{how}='#{strg}' found and returned.")
-          return myForm
-        end
-      rescue
-        failed_to_log("Unable to return form #{how}='#{strg}': '#{$!}' (#{__LINE__})")
-      end
-
-      def get_form_by_id(browser, strg)
-        get_form(browser, :id, strg)
-      end
-
-      def get_frame(browser, how, strg, desc = '')
-        #    begin
-        #      Watir::Wait.until(browser.frame(how, strg).exists?) # fails in wait_until
-        #    rescue => e
-        #      if not rescue_me(e, __method__, "browser.frame(#{how}, '#{strg}').exists?", "#{browser.class}")
-        #        raise e
-        #      end
-        #    end
         begin
-          frame = browser.frame(how, strg)
+          span = browser.span(how, what)
         rescue => e
-          if not rescue_me(e, __method__, "browser.frame(#{how}, '#{strg}').exists?", "#{browser.class}")
+          if not rescue_me(e, __method__, "browser.span(#{how}, '#{what}').exists?", "#{browser.class}")
             raise e
           end
         end
-        if validate(browser, @myName, __LINE__)
-          passed_to_log("Frame #{how}='#{strg}' found and returned. #{desc}")
-          return frame
-        end
+        passed_to_log("Span #{how}='#{what}' found and returned. #{desc}")
+        return span
       rescue
-        failed_to_log("Unable to return frame #{how}='#{strg}'. #{desc}: '#{$!}' (#{__LINE__})")
-      end
-
-      def get_frame_by_id(browser, strg, desc = '')
-        get_frame(browser, :id, strg, desc)
-      end
-
-      def get_frame_by_index(browser, index, desc = '')
-        get_frame(browser, :index, index, desc)
-      end
-
-      def get_frame_by_name(browser, strg, desc = '')
-        get_frame(browser, :name, strg, desc)
+        failed_to_log("Unable to return span #{how}='#{what}'. #{desc}: '#{$!}' (#{__LINE__})")
       end
 
-      def get_span(browser, how, strg, desc = '')
-        begin
-          #TODO: use LegacyExtensions#wait_until
-          Watir::Wait.until { browser.span(how, strg).exists? }
-        rescue => e
-          if not rescue_me(e, __method__, "browser.span(#{how}, '#{strg}').exists?", "#{browser.class}")
-            raise e
-          end
-        end
-        begin
-          span = browser.span(how, strg)
-        rescue => e
-          if not rescue_me(e, __method__, "browser.span(#{how}, '#{strg}').exists?", "#{browser.class}")
-            raise e
-          end
-        end
-        if validate(browser, @myName, __LINE__)
-          passed_to_log("Span #{how}='#{strg}' found and returned. #{desc}")
-          return span
-        end
-      rescue
-        failed_to_log("Unable to return span #{how}='#{strg}'. #{desc}: '#{$!}' (#{__LINE__})")
+      # Return a reference to a _form_ element identified by the contents *what* of its attribute *how*.
+      # @param (see #get_span)
+      # @return [Watir::Form]
+      def get_form(browser, how, what, desc = '')
+        get_element(browser, :form, how, what, desc)
       end
 
-      def get_span_by_id(browser, strg, desc = '')
-        get_span(browser, :id, strg, desc)
+      # Return a reference to a _frame_ element identified by the contents *what* of its attribute *how*.
+      # @param (see #get_span)
+      # @return [Watir::Frame]
+      def get_frame(browser, how, what, desc = '')
+        get_element(browser, :frame, how, what, desc)
       end
 
-=begin rdoc
-  :category: A_rdoc_test
-Returns a reference to a table element.  Used to assign a table element to a variable
-which can then be used directly or passed to methods that require a *browser* or *table* parameter.
-
-_Parameters_::
-
-*browser* - a reference to the browser window or container element to be tested
-
-*how* - the element attribute used to identify the specific element. Valid values depend on the kind of element.
-Common values: :text, :id, :title, :name, :class, :href (:link only)
-
-*what* - a string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
-
-*desc* - a string containing a message or description intended to appear in the log and/or report output
-
-_Example_
-
-  a_table = get_table(browser, :id, 'table1')
-  a_table_cell = a_table[2][1]   # The cell in the first column of the second row of the table
-
-=end
-
-      def get_table(browser, how, what, desc = '')
-        msg = "Return table :#{how}='#{what}'. #{desc}"
-        tbl = browser.table(how, what)
-        if validate(browser, @myName, __LINE__)
-          passed_to_log(msg)
-          tbl
-        end
-      rescue
-        failed_to_log("#{msg}': '#{$!}'")
-      end
-
-      def get_table_by_id(browser, strg, desc = '')
-        get_table(browser, :id, strg, desc)
-      end
-
-      def get_table_by_index(browser, idx)
-        get_table(browser, :index, idx, desc)
-      end
-
-      def get_table_by_text(browser, strg)
-        get_table(browser, :text, strg, desc)
-      end
-
-      def get_table_headers(table, header_index = 1)
-        headers          = Hash.new
-        headers['index'] = Hash.new
-        headers['name']  = Hash.new
-        count            = 1
-        table[header_index].each do |cell|
-          if cell.text.length > 0
-            name                    = cell.text.gsub(/\s+/, ' ')
-            headers['index'][count] = name
-            headers['name'][name]   = count
-          end
-          count += 1
-        end
-        #debug_to_log("#{__method__}:****** headers:\n#{headers.to_yaml}")
-        headers
-      rescue
-        failed_to_log("Unable to get content headers. '#{$!}'")
-      end
-
-      def get_element(browser, element, how, what, value = nil)
-        target = nil
-        what = Regexp.new(Regexp.escape(what)) unless how == :index or what.is_a?(Regexp)
-        case element
-          when :link
-            target = browser.link(how, what)
-          when :button
-            target = browser.button(how, what)
-          when :div
-            target = browser.div(how, what)
-          when :checkbox
-            target = browser.checkbox(how, what, value)
-          when :text_field, :textfield
-            target = browser.text_field(how, what)
-          when :image
-            target = browser.image(how, what)
-          when :file_field, :filefield
-            target = browser.file_field(how, what)
-          when :form
-            target = browser.form(how, what)
-          when :frame
-            target = browser.frame(how, what)
-          when :radio
-            target = browser.radio(how, what, value)
-          when :span
-            target = browser.span(how, what)
-          when :table
-            target = browser.table(how, what)
-          when :li
-            target = browser.li(how, what)
-          when :select_list, :selectlist
-            target = browser.select_list(how, what)
-          when :hidden
-            target = browser.hidden(how, what)
-          when :area
-            target = browser.area(how, what)
-        end
-        if target.exists?
-          target
-        else
-          nil
-        end
-      rescue => e
-        if not rescue_me(e, __method__, "browser.#{element}(#{how}, '#{what}')", "#{browser.class}", target)
-          raise e
-        end
+      # Return a reference to a _select_list_ element identified by the contents *what* of its attribute *how*.
+      # @param (see #get_span)
+      # @return [Watir::SelectList]
+      def get_select_list(browser, how, what, desc = '')
+        get_element(browser, :select_list, how, what, desc)
       end
 
-      def get_objects(browser, which, dbg=false)
+      # Return an array (collection) of all the elements of the type *which* contained in the browser or container
+      # supplied in *browser*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] element The kind of element to click. Must be one of the elements recognized by Watir.
+      #   Some common values are :link, :button, :image, :div, :span.
+      # @param [Boolean] dbg If set to true additional debug logging is performed.
+      # @return [Array]
+      def get_element_collection(browser, element, dbg = false)
         cnt = 0
-        case which
-          when :links
+        case element
+          when :links, :link
             list = browser.links
             sleep(1)
-          when :tables
+          when :tables, :table
             list = browser.tables
-          when :divs
+          when :divs, :div
             list = browser.divs
-          when :buttons
+          when :buttons, :button
             list = browser.buttons
-          when :checkboxes
+          when :checkboxes, :checkbox
             list = browser.checkboxes
-          when :radios
+          when :radios, :radio
             list = browser.radios
-          when :selectlists
+          when :selectlists, :select_lists, :selectlist, :select_list
             list = browser.selectlists
-          when :textfields
+          when :textfields, :text_fields, :textareas, :text_fields, :textfield, :text_field, :textarea, :text_area
             list = browser.textfields
-          when :lis
+          when :lis, :li
             list = browser.lis
+          when :uls, :ul
+            list = browser.uls
           else
-            debug_to_log("Unrecognized dom object '#{which}'")
+            debug_to_log("Unsupported DOM object '#{which}'")
         end
         if dbg
           list.each do |obj|
@@ -358,6 +232,12 @@ _Example_
         list
       end
 
+      alias get_objects get_element_collection
+
+      # Return the ole object for the specified element.
+      # @note Usable only with classic Watir.
+      # @todo Detect $watir_script variable and disable if not set to true
+      # @param [Symbol] element A reference to the already identified element.
       def get_ole(element)
         ole = element.ole_object
         if ole
@@ -370,6 +250,10 @@ _Example_
         failed_to_log("Unable to find ole_object for #{element}.  #{$!}")
       end
 
+      # Return a hash of all links in *browser* with *:href* attribute containing the exact url in *href*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] href The exact url to be located.
+      # @return [Hash] The hash is indexed by the order in which the links were located in *browser*.
       def find_all_links_with_exact_href(browser, href)
         links = browser.links
         hash  = Hash.new
@@ -386,6 +270,10 @@ _Example_
         hash
       end
 
+      # Return a reference to the first link in *browser* with *:href* attribute containing the exact url in *href*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] href The exact url to be located.
+      # @return [Watir::Link]
       def find_link_with_exact_href(browser, href)
         links = browser.links
         link  = nil
@@ -396,18 +284,159 @@ _Example_
           my_href = l.href
           if my_href == an_href
             link = l
-    #        debug_to_log("#{__method__}:#{__LINE__}\n********\n#{l.to_s}\n\n#{l.to_yaml}")
+            #        debug_to_log("#{__method__}:#{__LINE__}\n********\n#{l.to_s}\n\n#{l.to_yaml}")
             break
           end
         end
         link
       end
 
-      def find_index_for_object(browser, obj, how, ord, strg)
-        obj_sym = (obj.to_s.pluralize).to_sym
+      # @!endgroup Core
+
+      # @!group Legacy (Backward compatible usages)
+
+      # Return the list of options in a select list identified by its *:id* attribute.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String, Regexp] what A string or a regular expression to be found in the designated attribute that uniquely identifies the element.
+      # @param [Boolean] dbg Triggers additional debug logging when set to true.
+      # @return [Array]
+      def get_select_options_by_id(browser, what, dbg = false)
+        get_select_options(browser, :id, what, dbg)
+      end
+
+      # Return the list of options in a select list identified by its *:name* attribute.
+      # @param (see #get_select_options_by_id)
+      # @return [Array]
+      def get_select_options_by_name(browser, what, dbg = false)
+        get_select_options(browser, :name, what, dbg)
+      end
+
+      # Return the list of _selected_ options in a select list identified by its *:id* attribute.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String, Regexp] what A string or a regular expression to be found in the designated attribute that uniquely identifies the element.
+      # @return [Array]
+      def get_selected_options_by_id(browser, what)
+        get_selected_options(browser, :id, what)
+      end
+
+      alias get_selected_option_by_id get_selected_options_by_id
+
+      # Return the list of _selected_ options in a select list identified by its *:name* attribute.
+      # @param (see #get_select_options_by_id)
+      # @return [Array]
+      def get_selected_options_by_name(browser, what)
+        get_selected_options(browser, :name, what)
+      end
+
+      alias get_selected_option_by_name get_selected_options_by_name
+
+      # Return a reference to a div element identified by its *:id* attribute.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String, Regexp] what A string or a regular expression to be found in the designated attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @param [Boolean] dbg Triggers additional debug logging when set to true.
+      # @return [Water::Div]
+      def get_div_by_id(browser, what, desc = '', dbg = false)
+        get_div(browser, :id, what, desc, dbg)
+      end
+
+      # Return a reference to a div element identified by its *:class* attribute.
+      # @param (see #get_div_by_id)
+      # @return [Water::Div]
+      def get_div_by_class(browser, what, desc = '', dbg = false)
+        get_div(browser, :class, what, desc, dbg)
+      end
+
+      # Return a reference to a div element identified by its *:text* attribute.
+      # @param (see #get_div_by_id)
+      # @return [Water::Div]
+      def get_div_by_text(browser, what, desc = '', dbg = false)
+        get_div(browser, :text, what, desc, dbg)
+      end
+
+      # Return a reference to a form element identified by its *:id* attribute.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String, Regexp] what A string or a regular expression to be found in the designated attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Water::Form]
+      def get_form_by_id(browser, what, desc = '')
+        get_form(browser, :id, what, desc)
+      end
+
+      # Return a reference to a frame element identified by its *:id* attribute.
+      # @param (see #get_form_by_id)
+      # @return [Water::Frame]
+      def get_frame_by_id(browser, what, desc = '')
+        get_frame(browser, :id, what, desc)
+      end
+
+      # Return a reference to a frame element identified by its *:index* within *browser*.
+      # @param (see #get_form_by_id)
+      # @return [Water::Frame]
+      def get_frame_by_index(browser, what, desc = '')
+        get_frame(browser, :index, what, desc)
+      end
+
+      # Return a reference to a frame element identified by its *:name* attribute.
+      # @param (see #get_form_by_id)
+      # @return [Water::Frame]
+      def get_frame_by_name(browser, what, desc = '')
+        get_frame(browser, :name, what, desc)
+      end
+
+      # Return a reference to a span element identified by its *:id* attribute.
+      # @param (see #get_form_by_id)
+      # @return [Water::Span]
+      def get_span_by_id(browser, what, desc = '')
+        get_span(browser, :id, what, desc)
+      end
+
+      # Return a reference to a table element identified by its attribute *how* containing *what*.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] how The element attribute used to identify the specific element.
+      #   Valid values depend on the kind of element.
+      #   Common values: :text, :id, :title, :name, :class, :href (:link only)
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::Table]
+      def get_table(browser, how, what, desc = '')
+        get_element(browser, :table, how, what, nil, desc)
+      end
+
+      # Return a reference to a table element identified by its *:id* attribute.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::Table]
+      def get_table_by_id(browser, what, desc = '')
+        get_element(browser, :table, :id, what, nil, desc)
+      end
+
+      # Return a reference to a table element identified by its *:index* within *browser*.
+      # @param (see #get_table)
+      # @return [Watir::Table]
+      def get_table_by_index(browser, what, desc = '')
+        get_element(browser, :table, :index, what, nil, desc)
+      end
+
+      # Return a reference to a table element identified by its *:text* attribute.
+      # @param (see #get_table)
+      # @return [Watir::Table]
+      def get_table_by_text(browser, what)
+        get_element(browser, :table, :text, what, nil, desc)
+      end
+
+      # @!endgroup Legacy
+
+      # @!group Deprecated
+
+      # Find the index of an element within *browser* which has attribute *how* containing *what*
+      # @deprecated
+      def find_index_for_element(browser, element, how, ord, what)
+        element_sym = (element.to_s.pluralize).to_sym
         how_str = how.to_s
-        ptrn    = /#{how}:\s+#{strg}/i
-        list    = get_objects(browser, obj_sym, true)
+        ptrn    = /#{how}:\s+#{what}/i
+        list    = get_element_collection(browser, element_sym, true)
         cnt     = 0
         idx     = 0
         list.each do |nty|
@@ -424,6 +453,9 @@ _Example_
         idx
       end
 
+      alias find_index_for_object find_index_for_element
+
+      # @!endgroup Deprecated
 
     end
   end