celerity 0.0.3 → 0.0.4

data/lib/celerity/clickable_element.rb

@@ -1,6 +1,7 @@
 module Celerity
   module ClickableElement
     
+    # clicks the element
     def click
       assert_exists
       assert_enabled

data/lib/celerity/collections.rb

@@ -1,5 +1,9 @@
 module Celerity
 
+ class Frames < ElementCollections
+    def element_class; Frame; end
+  end
+  
  class Buttons < ElementCollections
     def element_class; Button; end
   end

data/lib/celerity/container.rb

@@ -1,15 +1,42 @@
 module Celerity
+  
+  # This class contains methods for accessing elements inside a container.
+  # (usually the Browser object, meaning the current page).
+  #
+  # The most common syntax is 
+  #   browser.elem(:attribute, 'value')
+  #
+  # Note that the element is located lazily, so no exceptions will be thrown 
+  # if the element doesn't exist until you call a method on the resulting object. 
+  # To do this you would normally use +Element#exists?+ or an action method, 
+  # like +ClickableElement#click+. 
+  # 
+  # You can also pass in a hash:
+  #
+  #   browser.link(:index => 1).click
+  #
+  # All elements support multiple attributes identification using the 
+  # hash syntax (though might not always be compatible with Watir):
+  #
+  # browser.span(:class_name => 'product', :index => 5).text
+  #
+  # You can also get all the elements of a certain type by using the plural form:
+  #
+  # browser.links => #<Celerity::Links:0x7a1c2da2 ...>
+  # 
+  # See +Celerity::ElementCollections+ for details.
   module Container
     include Celerity::Exception
     attr_accessor :page_container
 
-    def set_container(container)
+    def container=(container)
       @container = container
       @page_container = container.page_container
+      container
     end
 
     def update_page(page)
-      @page_container.set_page(page)
+      @page_container.page = page 
     end
 
     def frame(*args)
@@ -17,10 +44,16 @@ module Celerity
       Frame.new(self, *args)
     end
 
+    def frames
+      assert_exists
+      Frames.new(self)
+    end
+
     def table(*args)
       assert_exists
       Table.new(self, *args)
     end
+    
     def tables
       assert_exists
       Tables.new(self)
@@ -30,6 +63,7 @@ module Celerity
       assert_exists
       TableHeader.new(self, *args)
     end
+    
     def theads
       assert_exists
       TableHeaders.new(self)
@@ -39,6 +73,7 @@ module Celerity
       assert_exists
       TableBody.new(self, *args)
     end
+    
     def tbodies
       assert_exists
       TableBodies.new(self)
@@ -48,6 +83,7 @@ module Celerity
       assert_exists
       TableFooter.new(self, *args)
     end
+    
     def tfoots
       assert_exists
       TableFooters.new(self)
@@ -58,6 +94,7 @@ module Celerity
       assert_exists
       TableCell.new(self, *args)
     end
+    
     def cells
       assert_exists
       TableCells.new(self)
@@ -67,6 +104,7 @@ module Celerity
       assert_exists
       TableRow.new(self, *args)
     end
+    
     def rows
       assert_exists
       TableRows.new(self)
@@ -76,6 +114,7 @@ module Celerity
       assert_exists
       Button.new(self, *args)
     end
+    
     def buttons
       assert_exists
       Buttons.new(self)
@@ -85,6 +124,7 @@ module Celerity
       assert_exists
       FileField.new(self, *args)
     end
+    
     def file_fields
       assert_exists
       FileFields.new(self)
@@ -94,6 +134,7 @@ module Celerity
       assert_exists
       TextField.new(self, *args)
     end
+    
     def text_fields
       assert_exists
       TextFields.new(self)
@@ -103,6 +144,7 @@ module Celerity
       assert_exists
       Hidden.new(self, *args)
     end
+    
     def hiddens
       assert_exists
       Hiddens.new(self)
@@ -112,6 +154,7 @@ module Celerity
       assert_exists
       SelectList.new(self, *args)
     end
+    
     def select_lists
       assert_exists
       SelectLists.new(self)
@@ -136,6 +179,7 @@ module Celerity
       assert_exists
       Radio.new(self, *args)
     end
+    
     def radios
       assert_exists
       Radios.new(self)
@@ -155,6 +199,7 @@ module Celerity
       assert_exists
       Ul.new(self, *args)
     end
+    
     def uls
       assert_exists
       Uls.new(self)
@@ -164,6 +209,7 @@ module Celerity
       assert_exists
       Ol.new(self, *args)
     end
+    
     def ols
       assert_exists
       Ols.new(self)
@@ -173,6 +219,7 @@ module Celerity
       assert_exists
       Li.new(self, *args)
     end
+    
     def lis
       assert_exists
       Lis.new(self)
@@ -182,6 +229,7 @@ module Celerity
       assert_exists
       Map.new(self, *args)
     end
+    
     def maps
       assert_exists
       Maps.new(self)
@@ -191,6 +239,7 @@ module Celerity
       assert_exists
       Area.new(self, *args)
     end
+    
     def areas
       assert_exists
       Areas.new(self)
@@ -200,6 +249,7 @@ module Celerity
       assert_exists
       Image.new(self, *args)
     end
+    
     def images
       assert_exists
       Images.new(self)
@@ -209,6 +259,7 @@ module Celerity
       assert_exists
       Div.new(self, *args)
     end
+    
     def divs
       assert_exists
       Divs.new(self)
@@ -218,6 +269,7 @@ module Celerity
       assert_exists
       Form.new(self, *args)
     end
+    
     def forms
       assert_exists
       Forms.new(self)
@@ -227,6 +279,7 @@ module Celerity
       assert_exists
       Span.new(self, *args)
     end
+    
     def spans
       assert_exists
       Spans.new(self)
@@ -236,6 +289,7 @@ module Celerity
       assert_exists
       P.new(self, *args)
     end
+    
     def ps
       assert_exists
       Ps.new(self)
@@ -245,6 +299,7 @@ module Celerity
       assert_exists
       Pre.new(self, *args)
     end
+    
     def pres
       assert_exists
       Pres.new(self)
@@ -254,6 +309,7 @@ module Celerity
       assert_exists
       Label.new(self, *args)
     end
+    
     def labels
       assert_exists
       Labels.new(self)
@@ -263,46 +319,57 @@ module Celerity
       assert_exists
       H1.new(self, *args)
     end
+    
     def h2(*args)
       assert_exists
       H2.new(self, *args)
     end
+    
     def h3(*args)
       assert_exists
       H3.new(self, *args)
     end
+    
     def h4(*args)
       assert_exists
       H4.new(self, *args)
     end
+    
     def h5(*args)
       assert_exists
       H5.new(self, *args)
     end
+    
     def h6(*args)
       assert_exists
       H6.new(self, *args)
     end
+    
     def h1s
       assert_exists
       H1s.new(self)
     end
+    
     def h2s
       assert_exists
       H2s.new(self)
     end
+    
     def h3s
       assert_exists
       H3s.new(self)
     end
+    
     def h4s
       assert_exists
       H4s.new(self)
     end
+    
     def h5s
       assert_exists
       H5s.new(self)
     end
+    
     def h6s
       assert_exists
       H6s.new(self)

data/lib/celerity/disabled_element.rb

@@ -1,4 +1,5 @@
 module Celerity
+  # Module mixed in to all elements that can have the 'disabled' attribute.
   module DisabledElement
     include Celerity::Exception
     

data/lib/celerity/element.rb

@@ -1,8 +1,11 @@
 module Celerity
+  
+  # Superclass for all HTML elements.
   class Element
     include Exception
     include Container
-    attr_accessor :container, :object
+    
+    attr_reader :container, :object
     
     # number of spaces that separate the property from the value in the create_string method
     TO_S_SIZE = 14
@@ -13,7 +16,8 @@ module Celerity
       :cell_halign => [:align, :char, :charoff],
       :cell_valign => [:valign],
       :i18n        => [:dir, :lang],
-      :event       => [:onclick, :ondblclick, :onmousedown, :onmouseup, :onmouseover, :onmousemove, :onmouseout, :onkeypress, :onkeydown, :onkeyup],
+      :event       => [:onclick, :ondblclick, :onmousedown, :onmouseup, :onmouseover, 
+                       :onmousemove, :onmouseout, :onkeypress, :onkeydown, :onkeyup],
       :sloppy      => [:name, :value]
     }
     
@@ -21,15 +25,18 @@ module Celerity
     CELLVALIGN_ATTRIBUTES = HTML_401_TRANSITIONAL[:cell_valign]
     BASE_ATTRIBUTES       = HTML_401_TRANSITIONAL.values_at(:core, :i18n, :event, :sloppy).flatten
     ATTRIBUTES            = BASE_ATTRIBUTES
+
+    DEFAULT_HOW = nil
     
+    # @api internal
     def initialize(container, *args)
-      set_container container
+      self.container = container
       
       case args.size
       when 2
         @conditions = { args[0] => args[1] }
       when 1
-        if Hash === args.first
+        if args.first.is_a? Hash
           @conditions = args.first
         elsif self.class::DEFAULT_HOW
           @conditions = { self.class::DEFAULT_HOW => args.first }
@@ -41,20 +48,49 @@ module Celerity
       end
     end
     
+    # Get the parent element (experimental, avoid if possible)
+    # @return [Celerity::Element] subclass
+    def parent
+      assert_exists
+      
+      obj = @object.getParentNode
+      until element_class = HtmlUnit2CelerityElement[obj.class]
+        return nil if obj.nil?
+        obj = obj.parentNode
+      end
+      
+      element_class.new(@container, :object, obj)
+    end
+    
+    # Sets the focus to this element.
+    def focus
+      assert_exists
+      @object.focus
+    end
+    
+    # Locates the element
+    # @api internal
     def locate
       @object = ElementLocator.new(@container.object, self.class).find_by_conditions(@conditions)
     end
     
+    # @return [String] A string representation of the element.
     def to_s
       assert_exists
       create_string(@object)
     end
     
+    # @param [String, #to_s] The attribute.
+    # @return [String] The value of the given attribute.
     def attribute_value(attribute)
       assert_exists
-      @object.getAttribute(attribute)
+      @object.getAttribute(attribute.to_s)
     end
 
+    # Locates the element.
+    # 
+    # @raise UnknownObjectException
+    # @api internal
     def assert_exists
       locate
       unless @object
@@ -62,29 +98,40 @@ module Celerity
       end
     end
 
+    # Checks if the element exists.
+    # @return [true, false]
     def exists?
-      begin
-        assert_exists
-        true
-      rescue UnknownObjectException, UnknownFrameException
-        false
-      end
+      assert_exists
+      true
+    rescue UnknownObjectException, UnknownFrameException
+      false
     end
     alias_method :exist?, :exists?
     alias_method :exists, :exists?
 
+    # Return a text representation of the element.
+    # @return [String]
     def text
       assert_exists
+
+      # this could work, but breaks some tests atm
+      # @object.getTextContent.strip
+
       @object.asText.strip
     end
     alias_method :innerText, :text
     alias_method :inner_text, :text
 
+    # Check if the element contains the given text.
+    #
+    # @param  [String, Regexp] expected_text The text to look for.
+    # @return [Fixnum, nil]  The index of the matched text, or nil if it doesn't match.
     def contains_text(expected_text)
       assert_exists
+      
       case expected_text
       when Regexp
-        text().match(expected_text)
+        text() =~ expected_text
       when String
         text().index(expected_text)
       else
@@ -92,25 +139,36 @@ module Celerity
       end
     end
 
+    # @return [String] The normative XML representation of the element (including children).
     def to_xml
       assert_exists
       @object.asXml
     end
-    alias_method :asXml, :to_xml
+    alias_method :asXml,  :to_xml
     alias_method :as_xml, :to_xml
-    alias_method :html, :to_xml
+    alias_method :html,   :to_xml
     
-    # used to get attributes
-    def method_missing(meth, *args, &blk)
-      case meth
-      when :class_name
-        meth = :class
-      when :caption
-        meth = :value
-      when :url
-        meth = :href
+    # @return [String] A string representation of the element's attributes.
+    def attribute_string
+      assert_exists
+      
+      result = ''
+      iterator = @object.getAttributeEntriesIterator
+      
+      while iterator.hasNext
+        attribute = iterator.next
+        result << "#{attribute.getName}=\"#{attribute.getHtmlValue.to_s}\" "
       end
+      
+      result
+    end
 
+    # Dynamically get element attributes.
+    # @return [String] The resulting attribute.
+    # @raise NoMethodError If the element doesn't have this attribute.
+    def method_missing(meth, *args, &blk)
+      meth = selector_to_attribute(meth)
+      
       if self.class::ATTRIBUTES.include?(meth)
         assert_exists
         @object.getAttributeValue(meth.to_s)
@@ -119,30 +177,28 @@ module Celerity
         super
       end
     end
-    
-    def attribute_string
-      assert_exists
-      n = ''
-      iterator = @object.getAttributeEntriesIterator
-      while iterator.hasNext
-        attribute = iterator.next
-        n += "#{attribute.getName}=\"#{attribute.getHtmlValue.to_s}\" "
-      end
-      return n
+
+    def respond_to?(meth, include_private = false)
+      meth = selector_to_attribute(meth)
+      return true if self.class::ATTRIBUTES.include?(meth)
+      super
     end
 
     private
     
     def create_string(element)
-      n = []
-      n << "tag:".ljust(TO_S_SIZE) + element.getTagName unless element.getTagName.empty?
+      ret = []
+      ret << "tag:".ljust(TO_S_SIZE) + element.getTagName unless element.getTagName.empty?
+      
       iterator = element.getAttributeEntriesIterator
       while iterator.hasNext
         attribute = iterator.next
-        n << "  #{attribute.getName}:".ljust(TO_S_SIZE+2) + attribute.getHtmlValue.to_s
+        ret << "  #{attribute.getName}:".ljust(TO_S_SIZE+2) + attribute.getHtmlValue.to_s
       end
-      n << "  text:".ljust(TO_S_SIZE+2) + element.asText unless element.asText.empty?
-      return n.join("\n")
+      
+      ret << "  text:".ljust(TO_S_SIZE+2) + element.asText unless element.asText.empty?
+      
+      ret.join("\n")
     end
     
     def identifier_string
@@ -154,5 +210,14 @@ module Celerity
       end
     end
     
+    def selector_to_attribute(meth)
+      case meth
+      when :class_name then :class
+      when :caption then :value
+      when :url then :href
+      else meth
+      end
+    end
+    
   end # Element
 end # Celerity