celerity 0.0.3 → 0.0.4

data/lib/celerity/element_collections.rb

@@ -1,25 +1,28 @@
 module Celerity
-  # this class is the super class for the iterator classes (buttons, links, spans etc
-  # it would normally only be accessed by the iterator methods (spans, links etc) of IE
+  # This class is the superclass for the iterator classes (Buttons, Links, Spans etc.)
+  # It would normally only be accessed by the iterator methods (Browser#spans, Browser#links, ...).
   class ElementCollections
     include Enumerable
     
+    # @api internal
     def initialize(container, how = nil, what = nil)
       @container = container
       @object = (how == :object ? what : nil)
       @length = length
     end
-
+   
+    # @return [Fixnum] The number of elements in this collection.
     def length
       if @object
         @object.length
       else
-        @elements = ElementLocator.new(@container.object, element_class).elements_by_idents
+        @elements ||= ElementLocator.new(@container.object, element_class).elements_by_idents
         @elements.size
       end
     end
     alias_method :size, :length
     
+    # @yield [element] Iterate through the elements in this collection.
     def each
       if @elements
         @elements.each { |e| yield(element_class.new(@container, :object, e)) }
@@ -29,19 +32,22 @@ module Celerity
       end
     end
     
+    # Get the element at the given index.
+    # NB! This is 1-indexed to keep compatibility with Watir. Subject to change.
+    #
+    # @return [Celerity::Element]
     def [](n)
-      @elements ? element_class.new(@container, :object, @elements[n - 1]) : iterator_object(n - 1)
+      @elements ? element_class.new(@container, :object, @elements[n-1]) : iterator_object(n-1)
     end
     
     def to_s
-      return self.collect { |i| i.to_s }.join("\n")
+      map { |e| e.to_s }.join("\n")
     end
     
     private
 
-    # this method creates an object of the correct type that the iterators use
     def iterator_object(i)
-      element_class.new(@container, :index, i + 1)
+      element_class.new(@container, :index, i+1)
     end
   
   end # ElementCollections

data/lib/celerity/element_locator.rb

@@ -1,9 +1,6 @@
 module Celerity
   
-  # What we essentially want is the ability to perform a fast SQLish 'select' against the DOM. 
-  # Instead of iterating twice through a lot of elements, we could modify the Identifier objects to contain 
-  # everything in our 'query'. 
-  # Jari - 2008-05-11
+  # Used internally to locate elements on the page.
   class ElementLocator
     include Celerity::Exception
     attr_accessor :idents
@@ -23,55 +20,53 @@ module Celerity
       index = 0 # by default, return the first matching element
       text = nil 
       
-      begin 
-        conditions.each do |how, what|
-          case how
-          when :object
-            return what
-          when :id
-            return find_by_id(what)
-          when :xpath
-            return find_by_xpath(what)
-          when :class_name
-            how = :class
-          when :url
-            how = :href
-          when :caption
-            how = :text
-          end
-        
-          if @attributes.include?(how)
-            attributes[how] << what  
-          elsif how == :index
-            index = what.to_i - 1
-          elsif how == :text
-            text = what
-          else
-            raise MissingWayOfFindingObjectException, "No how #{how.inspect}"
-          end
-
+      conditions.each do |how, what|
+        case how
+        when :object
+          return what
+        when :id
+          return find_by_id(what)
+        when :xpath
+          return find_by_xpath(what)
+        when :class_name
+          how = :class
+        when :url
+          how = :href
+        when :caption
+          how = :text
         end
-
-        @idents.each do |ident|
-          merged = attributes.merge(ident.attributes) do |key, v1, v2|
-            attributes[key] = v1 | v2
-          end
-            
-          id = Identifier.new(ident.tag, merged)
-          # «original» identifier takes precedence for :text
-          id.text = ident.text || text
-          @condition_idents << id
-        end
-        
-        if index == 0
-          element_by_idents(@condition_idents)
+      
+        if @attributes.include?(how)
+          attributes[how] << what  
+        elsif how == :index
+          index = what.to_i - 1
+        elsif how == :text
+          text = what
         else
-          elements_by_idents(@condition_idents)[index]
+          raise MissingWayOfFindingObjectException, "No how #{how.inspect}"
         end
 
-      rescue HtmlUnit::ElementNotFoundException
-        nil # for rcov
       end
+
+      @idents.each do |ident|
+        merged = attributes.merge(ident.attributes) do |key, v1, v2|
+          v1 | v2
+        end
+          
+        id = Identifier.new(ident.tag, merged)
+        # «original» identifier takes precedence for :text
+        id.text = ident.text || text
+        @condition_idents << id
+      end
+      
+      if index == 0
+        element_by_idents(@condition_idents)
+      else
+        elements_by_idents(@condition_idents)[index]
+      end
+
+    rescue HtmlUnit::ElementNotFoundException
+      nil # for rcov
     end
     
     def find_by_id(what)
@@ -79,7 +74,13 @@ module Celerity
       when Regexp
         elements_by_tag_names.find { |elem| elem.getIdAttribute =~ what }
       when String
-        @object.getHtmlElementById(what)
+        obj = @object.getHtmlElementById(what)
+        if @tags.include?(obj.getTagName)
+          obj
+        else
+          $stderr.puts "warning: multiple elements with identical id (#{what.inspect})? " if $VERBOSE
+          elements_by_tag_names.find { |elem| elem.getIdAttribute == what }
+        end
       else
         raise ArgumentError, "Argument #{what.inspect} should be a String or Regexp"
       end
@@ -105,6 +106,7 @@ module Celerity
         if @tags.include?(e.getTagName)
           idents.any? do |ident|
             next unless ident.tag == e.getTagName
+            
             attr_result = ident.attributes.all? do |key, value| 
               value.any? { |val| matches?(e.getAttributeValue(key.to_s), val) } 
             end 
@@ -114,7 +116,6 @@ module Celerity
             else
               attr_result
             end
-            
           end
         end
       end
@@ -125,10 +126,20 @@ module Celerity
     end
 
     def elements_by_tag_names
+      tries = 0
       # HtmlUnit's getHtmlElementsByTagNames won't get elements in the correct order, making :index fail
       @object.getAllHtmlChildElements.iterator.to_a.select do |elem|
         @tags.include?(elem.getTagName)
       end
+    # workaround for HtmlUnit bug?
+    rescue java.lang.NullPointerException => e
+      $stderr.puts "warning: celerity caught #{e}"
+      if tries < 2
+        tries += 1
+        retry
+      else
+        raise e
+      end
     end
 
 

data/lib/celerity/element_map.rb

@@ -0,0 +1,51 @@
+module Celerity
+  module ElementMap
+    # Some HtmlUnit classes are missing equivalents in Celerity. Shouldn't be too hard to fix.
+    # This is mostly used to implement Element#parent easily.
+    HtmlUnit2CelerityElement = {
+      HtmlUnit::Html::HtmlAnchor           => Celerity::Link,
+      HtmlUnit::Html::HtmlArea             => Celerity::Area,
+      HtmlUnit::Html::HtmlButton           => Celerity::Button,
+      HtmlUnit::Html::HtmlButtonInput      => Celerity::Button,
+      HtmlUnit::Html::HtmlCaption          => Celerity::Button, # ?
+      HtmlUnit::Html::HtmlCheckBoxInput    => Celerity::CheckBox,
+      HtmlUnit::Html::HtmlDivision         => Celerity::Div,
+      HtmlUnit::Html::HtmlFileInput        => Celerity::FileField,
+      HtmlUnit::Html::HtmlForm             => Celerity::Form,
+      HtmlUnit::Html::HtmlFrame            => Celerity::Frame,
+      HtmlUnit::Html::HtmlHeading1         => Celerity::H1,
+      HtmlUnit::Html::HtmlHeading2         => Celerity::H2,
+      HtmlUnit::Html::HtmlHeading3         => Celerity::H3,
+      HtmlUnit::Html::HtmlHeading4         => Celerity::H4,
+      HtmlUnit::Html::HtmlHeading5         => Celerity::H5,
+      HtmlUnit::Html::HtmlHeading6         => Celerity::H6,
+      HtmlUnit::Html::HtmlHiddenInput      => Celerity::Hidden,
+      HtmlUnit::Html::HtmlImage            => Celerity::Image,
+      HtmlUnit::Html::HtmlLabel            => Celerity::Label,
+      HtmlUnit::Html::HtmlLink             => Celerity::Link,
+      HtmlUnit::Html::HtmlListItem         => Celerity::Li,
+      HtmlUnit::Html::HtmlMap              => Celerity::Map,
+      HtmlUnit::Html::HtmlOption           => Celerity::Option,
+      HtmlUnit::Html::HtmlOrderedList      => Celerity::Ol,
+      HtmlUnit::Html::HtmlParagraph        => Celerity::P,
+      HtmlUnit::Html::HtmlPasswordInput    => Celerity::TextField,
+      HtmlUnit::Html::HtmlPreformattedText => Celerity::Pre,
+      HtmlUnit::Html::HtmlRadioButtonInput => Celerity::Radio,
+      HtmlUnit::Html::HtmlSelect           => Celerity::SelectList,
+      HtmlUnit::Html::HtmlSpan             => Celerity::Span,
+      HtmlUnit::Html::HtmlTable            => Celerity::Table,
+      HtmlUnit::Html::HtmlTableBody        => Celerity::TableBody,
+      HtmlUnit::Html::HtmlTableCell        => Celerity::TableCell,
+      HtmlUnit::Html::HtmlTableFooter      => Celerity::TableFooter,
+      HtmlUnit::Html::HtmlTableHeader      => Celerity::TableHeader,
+      HtmlUnit::Html::HtmlTableRow         => Celerity::TableRow,
+      HtmlUnit::Html::HtmlTextArea         => Celerity::Area,
+      HtmlUnit::Html::HtmlTextInput        => Celerity::TextField,
+      HtmlUnit::Html::HtmlUnorderedList    => Celerity::Ul
+    }
+  end
+end
+
+class Celerity::Element 
+  include Celerity::ElementMap
+end

data/lib/celerity/elements/button.rb

@@ -13,6 +13,7 @@ module Celerity
 
     def locate
       # ugly..
+      # this is done to make <button> and <input>-buttons look similar
       if (val = @conditions[:value])
         locator = ElementLocator.new(@container.object, self.class)
         button_ident = Identifier.new('button')

data/lib/celerity/elements/file_field.rb

@@ -4,9 +4,10 @@ module Celerity
     TAGS = [ Identifier.new('input', :type => %w(file)) ]
     DEFAULT_HOW = :name
   
-    def set(value)
+    # Set the file field to the given path
+    def set(path)
       assert_exists
-      @object.setValueAttribute(value.to_s)
+      @object.setValueAttribute(path.to_s)
     end
   end
 end

data/lib/celerity/elements/form.rb

@@ -6,6 +6,7 @@ module Celerity
     ATTRIBUTES = BASE_ATTRIBUTES | [:action, :method, :enctype, :accept, :name, :onsubmit, :onreset, :target, :'accept-charset']
     DEFAULT_HOW = :name
   
+    # Submits the form.
     def submit
       assert_exists
       @container.update_page @object.submit(nil)

data/lib/celerity/elements/frame.rb

@@ -7,6 +7,8 @@ module Celerity
     ATTRIBUTES = BASE_ATTRIBUTES | [:longdesc, :name, :src, :frameborder, :marginwidth, :marginheight, :noresize, :scrolling]
     DEFAULT_HOW = :name
     
+    # Override the default locate to handle frame and inline frames.
+    # @api internal
     def locate
       super
       if @object
@@ -17,6 +19,8 @@ module Celerity
       end
     end
     
+    # Override assert_exists to raise UnknownFrameException (for Watir compatibility)
+    # @api internal
     def assert_exists
       locate unless @object
       unless @object
@@ -25,7 +29,7 @@ module Celerity
     end
     
     def update_page(value)
-      @page_container.set_page(value.getEnclosingWindow.getTopWindow.getEnclosedPage)
+      @page_container.page = value.getEnclosingWindow.getTopWindow.getEnclosedPage
     end
 
     def to_s
@@ -33,6 +37,17 @@ module Celerity
       create_string(@inline_frame_object)
     end
     
+    def method_missing(meth, *args, &blk)
+      meth = selector_to_attribute(meth)
+      if self.class::ATTRIBUTES.include?(meth)
+        assert_exists
+        @inline_frame_object.getAttributeValue(meth.to_s)
+      else
+        Log.warn "Element\#method_missing calling super with #{meth.inspect}"
+        super
+      end
+    end
+    
   end
 
 end

data/lib/celerity/elements/image.rb

@@ -1,10 +1,5 @@
 module Celerity
   
-  # This class is the means of accessing an image on a page.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#image method
-  #
-  # many of the methods available to this object are inherited from the Element class
-  #
   class Image < Element
     include ClickableElement
     include DisabledElement
@@ -13,18 +8,18 @@ module Celerity
     ATTRIBUTES = BASE_ATTRIBUTES | [:src, :alt, :longdesc, :name, :height, :width, :usemap, :ismap, :align, :border, :hspace, :vspace]
     DEFAULT_HOW = :src
     
-    # this method returns the file created date of the image
+    # returns the file created date of the image
     def file_created_date
       assert_exists
       web_response = @object.getWebResponse(true)      
-      return Time.parse(web_response.getResponseHeaderValue("Last-Modified").to_s)    
+      Time.parse(web_response.getResponseHeaderValue("Last-Modified").to_s)    
     end
     
-    # this method returns the filesize of the image
+    # returns the filesize of the image
     def file_size
       assert_exists
       web_response = @object.getWebResponse(true)      
-      return web_response.getResponseBody().length  
+      web_response.getResponseBody.length  
     end
     
     # returns the width in pixels of the image, as a string
@@ -38,23 +33,30 @@ module Celerity
       assert_exists
       @object.getHeight
     end
-        
+     
+    # returns true if the image is loaded   
     def loaded?
       assert_exists
       begin 
         @object.getImageReader
-        return true
+        true
       rescue
-        return false
+        false
       end
     end
     
+    def click
+      assert_exists
+      @container.update_page(@object.click)
+    end 
+    
+    # Saves the image to the given file
     def save(filename)
       assert_exists
       image_reader = @object.getImageReader
       file = java.io.File.new(filename)
       buffered_image = image_reader.read(0);
-      return javax.imageio.ImageIO.write(buffered_image, image_reader.getFormatName(), file);
+      javax.imageio.ImageIO.write(buffered_image, image_reader.getFormatName(), file);
     end
   end
 

data/lib/celerity/elements/link.rb

@@ -2,9 +2,12 @@ module Celerity
   class Link < Element
     
     TAGS = [ Identifier.new('a') ]
-    ATTRIBUTES = BASE_ATTRIBUTES | [:charset, :type, :name, :href, :hreflang, :target, :rel, :rev, :accesskey, :shape, :coords, :tabindex, :onfocus, :onblur]
+    ATTRIBUTES = BASE_ATTRIBUTES | [:charset, :type, :name, :href, :hreflang, 
+                                    :target, :rel, :rev, :accesskey, :shape, 
+                                    :coords, :tabindex, :onfocus, :onblur]
     DEFAULT_HOW = :href
     
+    # clicks the link
     def click
       assert_exists
       @container.update_page @object.click

data/lib/celerity/elements/option.rb

@@ -1,4 +1,5 @@
 module Celerity
+  # Represents a select list option.
   class Option < Element
     include ClickableElement
     include DisabledElement

data/lib/celerity/elements/radio_check.rb

@@ -1,13 +1,10 @@
 module Celerity
-  # This class is the class for radio buttons and check boxes.
-  # It contains methods common to both.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#checkbox or Watir::Container#radio methods
-  #
-  # most of the methods available to this element are inherited from the Element class
-  #
+  # Common superclass for radios and check boxes.
   class RadioCheckCommon < InputElement
     DEFAULT_HOW = :name
-    
+
+    # these can optionally take a value parameter as a third arg, so needs
+    # to be special-handled.
     def initialize(container, type, *args)
       @type = type
       case args.size
@@ -20,6 +17,7 @@ module Celerity
       end
     end
     
+    # returns true if the element is checked
     def set?
       assert_exists
       @object.isChecked
@@ -39,6 +37,13 @@ module Celerity
       super(container, ['radio'], *args)
     end
 
+    # Sets the radio button. 
+    #
+    #   radio.set? # => false
+    #   radio.set  
+    #   radio.set? # => true
+    #   radio.set(false)
+    #   radio.set? # => false
     def set(value = true)
       assert_exists
       assert_enabled
@@ -55,6 +60,13 @@ module Celerity
       super(container, ['checkbox'], *args)
     end
 
+    # Sets the checkbox button. 
+    #
+    #   checkbox.set? # => false
+    #   checkbox.set  
+    #   checkbox.set? # => true
+    #   checkbox.set(false)
+    #   checkbox.set? # => false
     def set(value = true)
       assert_exists
       assert_enabled