celerity 0.0.4 → 0.0.6

data/lib/celerity/default_viewer.rb

@@ -0,0 +1,10 @@
+module Celerity
+  class DefaultViewer
+    IMAGE = "#{Celerity::DIR}/resources/no_viewer.png"
+    
+    def self.save(path = nil)
+      return unless path
+      FileUtils.copy(IMAGE, path)
+    end
+  end
+end

data/lib/celerity/disabled_element.rb

@@ -1,23 +1,40 @@
 module Celerity
-  # Module mixed in to all elements that can have the 'disabled' attribute.
+  
+  #
+  # Mixed in to all elements that can have the 'disabled' attribute.
+  #
+
   module DisabledElement
     include Celerity::Exception
     
+    #
+    # Returns false if the element is disabled.
+    #
+
     def enabled?
       !disabled?
     end
 
+    #
+    # Returns true if the element is disabled.
+    # 
+    
     def disabled?
       assert_exists unless defined?(@object) && @object
       @object.isDisabled
     end
     alias_method :disabled, :disabled?
     
+    #
+    # Used internally.
+    # @api private
+    #
+
     def assert_enabled
       if disabled?
         raise ObjectDisabledException, "Object #{identifier_string} is disabled"
       end
     end
-    
+
   end
 end

data/lib/celerity/element.rb

@@ -1,105 +1,151 @@
 module Celerity
   
+  #
   # Superclass for all HTML elements.
+  # 
+  
   class Element
     include Exception
     include Container
-    
+
     attr_reader :container, :object
-    
+
     # number of spaces that separate the property from the value in the create_string method
     TO_S_SIZE = 14
-    
+
     # HTML 4.01 Transitional DTD
-    HTML_401_TRANSITIONAL = { 
+    HTML_401_TRANSITIONAL = {
       :core        => [:class, :id, :style, :title],
       :cell_halign => [:align, :char, :charoff],
       :cell_valign => [:valign],
       :i18n        => [:dir, :lang],
-      :event       => [:onclick, :ondblclick, :onmousedown, :onmouseup, :onmouseover, 
+      :event       => [:onclick, :ondblclick, :onmousedown, :onmouseup, :onmouseover,
                        :onmousemove, :onmouseout, :onkeypress, :onkeydown, :onkeyup],
       :sloppy      => [:name, :value]
     }
-    
+
     CELLHALIGN_ATTRIBUTES = HTML_401_TRANSITIONAL[:cell_halign]
     CELLVALIGN_ATTRIBUTES = HTML_401_TRANSITIONAL[:cell_valign]
     BASE_ATTRIBUTES       = HTML_401_TRANSITIONAL.values_at(:core, :i18n, :event, :sloppy).flatten
     ATTRIBUTES            = BASE_ATTRIBUTES
+    TAGS                  = []
 
     DEFAULT_HOW = nil
-    
-    # @api internal
+
+    # @api private
     def initialize(container, *args)
       self.container = container
-      
+
       case args.size
       when 2
         @conditions = { args[0] => args[1] }
       when 1
         if args.first.is_a? Hash
           @conditions = args.first
-        elsif self.class::DEFAULT_HOW
-          @conditions = { self.class::DEFAULT_HOW => args.first }
+        elsif (how = self.class::DEFAULT_HOW)
+          @conditions = { how => args.first }
         else
           raise ArgumentError, "wrong number of arguments (1 for 2)"
         end
       else
         raise ArgumentError, "wrong number of arguments (#{args.size} for 2)"
       end
+
+      @conditions.freeze
     end
-    
-    # Get the parent element (experimental, avoid if possible)
-    # @return [Celerity::Element] subclass
+
+    #
+    # Get the parent element
+    # @return [Celerity::Element, nil] subclass of Celerity::Element, or nil if no parent was found
+    # 
+
     def parent
       assert_exists
-      
-      obj = @object.getParentNode
-      until element_class = HtmlUnit2CelerityElement[obj.class]
+
+      obj = @object.parentNode
+      until element_class = Celerity::Util.htmlunit2celerity(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
+
+    #
+    # Used internally. Find the element on the page.
+    # @api private
+    # 
+
     def locate
-      @object = ElementLocator.new(@container.object, self.class).find_by_conditions(@conditions)
+      @object = ElementLocator.new(@container, 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.to_s)
     end
 
-    # Locates the element.
+    #
+    # Check if the element is visible to the user or not.
+    # Note that this only takes the _style attribute_ of the element (and
+    # its parents) into account - styles from applied CSS is not considered.
+    #
+    # @return [boolean]
+    # 
+
+    def visible?
+      obj = self
+      while obj
+        return false if obj.respond_to?(:type) && obj.type == 'hidden'
+        return false if obj.style =~ /display\s*:\s*none|visibility\s*:\s*hidden/
+        obj = obj.parent
+      end
+
+      return true
+    end
+
+    #
+    # Used internally to ensure the element actually exists.
+    #
+    # @raise [Celerity::Exception::UnknownObjectException] if the element can't be found.
+    # @api private
     # 
-    # @raise UnknownObjectException
-    # @api internal
+
     def assert_exists
       locate
       unless @object
-        raise UnknownObjectException, "Unable to locate object, using #{identifier_string}"
+        raise UnknownObjectException, "Unable to locate #{self.class.name[/::(.*)$/, 1]}, using #{identifier_string}"
       end
     end
-
+    
+    #
     # Checks if the element exists.
     # @return [true, false]
+    # 
+
     def exists?
       assert_exists
       true
@@ -107,39 +153,37 @@ module Celerity
       false
     end
     alias_method :exist?, :exists?
-    alias_method :exists, :exists?
-
-    # Return a text representation of the element.
+    
+    #
+    # Return a text representation of the element as it would appear in a browser.
+    #
+    # @see inner_text
     # @return [String]
+    # 
+
     def text
       assert_exists
-
-      # this could work, but breaks some tests atm
-      # @object.getTextContent.strip
-
-      @object.asText.strip
+      @object.asText.strip # this must behave like ElementLocator
     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)
+    # Return the text content of this DOM node, disregarding its visibility.
+    #
+    # (Celerity-specific?)
+    #
+    # @see text
+    # @return [String]
+    # 
+
+    def inner_text
       assert_exists
-      
-      case expected_text
-      when Regexp
-        text() =~ expected_text
-      when String
-        text().index(expected_text)
-      else
-        raise ArgumentError, "Argument #{expected_text.inspect} should be a String or Regexp."
-      end
+      Celerity::Util.normalize_text @object.getTextContent
     end
 
+    #
     # @return [String] The normative XML representation of the element (including children).
+    # 
+
     def to_xml
       assert_exists
       @object.asXml
@@ -147,35 +191,57 @@ module Celerity
     alias_method :asXml,  :to_xml
     alias_method :as_xml, :to_xml
     alias_method :html,   :to_xml
-    
+
+    #
     # @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}\" "
+      @object.getAttributes.each do |attribute|
+        result << %Q{#{attribute.getName}="#{attribute.getHtmlValue}"}
       end
-      
+
       result
     end
 
+    #
+    # return the canonical xpath for this element (Celerity-specific)
+    # 
+
+    def xpath
+      assert_exists
+      @object.getCanonicalXPath
+    end
+
+    #
     # Dynamically get element attributes.
+    #
+    # @see ATTRIBUTES constant for a list of valid methods for a given element.
+    #
     # @return [String] The resulting attribute.
-    # @raise NoMethodError If the element doesn't have this attribute.
+    # @raise  [NoMethodError] if the element doesn't support this attribute.
+    # 
+
     def method_missing(meth, *args, &blk)
+      assert_exists
+
       meth = selector_to_attribute(meth)
-      
+
       if self.class::ATTRIBUTES.include?(meth)
-        assert_exists
-        @object.getAttributeValue(meth.to_s)
-      else
-        Log.warn "Element\#method_missing calling super with #{meth.inspect}"
-        super
+        return @object.getAttributeValue(meth.to_s)
       end
+
+      Log.warn "Element\#method_missing calling super with #{meth.inspect}"
+      super
+    end
+    
+    def methods(*args)
+      ms = super 
+      ms += self.class::ATTRIBUTES.map { |e| e.to_s }
+      ms.sort
     end
 
     def respond_to?(meth, include_private = false)
@@ -185,39 +251,42 @@ module Celerity
     end
 
     private
-    
+
     def create_string(element)
       ret = []
-      ret << "tag:".ljust(TO_S_SIZE) + element.getTagName unless element.getTagName.empty?
-      
-      iterator = element.getAttributeEntriesIterator
-      while iterator.hasNext
-        attribute = iterator.next
+
+      unless (tag = element.getTagName).empty?
+        ret << "tag:".ljust(TO_S_SIZE) + tag
+      end
+
+      element.getAttributes.each do |attribute|
         ret << "  #{attribute.getName}:".ljust(TO_S_SIZE+2) + attribute.getHtmlValue.to_s
       end
-      
-      ret << "  text:".ljust(TO_S_SIZE+2) + element.asText unless element.asText.empty?
-      
+
+      unless (text = element.asText).empty?
+        ret << "  text:".ljust(TO_S_SIZE+2) + element.asText
+      end
+
       ret.join("\n")
     end
-    
+
     def identifier_string
       if @conditions.size == 1
-        how, what = @conditions.shift
+        how, what = @conditions.to_a.first
         "#{how.inspect} and #{what.inspect}"
       else
         @conditions.inspect
       end
     end
-    
+
     def selector_to_attribute(meth)
       case meth
       when :class_name then :class
-      when :caption then :value
-      when :url then :href
+      when :caption    then :value
+      when :url        then :href
       else meth
       end
     end
-    
+
   end # Element
 end # Celerity

data/lib/celerity/element_collection.rb

@@ -0,0 +1,106 @@
+module Celerity
+  
+  #
+  # 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 ElementCollection
+    include Enumerable
+    
+    #
+    # @api private
+    #
+
+    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, element_class).elements_by_idents
+        @elements.size
+      end
+    end
+    alias_method :size, :length
+
+    #
+    # @yieldparam [Celerity::Element] element Iterate through the elements in this collection.
+    #
+
+    def each
+      if @elements
+        @elements.each { |e| yield(element_class.new(@container, :object, e)) }
+      else
+        0.upto(@length - 1) { |i| yield iterator_object(i) }
+      end
+
+      @length
+    end
+    
+    #
+    # Get the element at the given index.
+    # This is 1-indexed to keep compatibility with Watir - subject to change.
+    # 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, 1-indexed.
+    # @return [Celerity::Element] Returns a subclass of Celerity::Element
+    # 
+
+    def [](n)
+      if @elements && @elements[n - INDEX_OFFSET]
+        element_class.new(@container, :object, @elements[n - INDEX_OFFSET])
+      else
+        iterator_object(n - INDEX_OFFSET)
+      end
+    end
+
+    #
+    # Get the first element in this collection. (Celerity-specific)
+    #
+    # @return [Celerity::Element] Returns a subclass of Celerity::Element
+    # 
+    
+    def first
+      self[INDEX_OFFSET]
+    end
+
+    #
+    # Get the last element in this collection. (Celerity-specific)
+    #
+    # @return [Celerity::Element] Returns a subclass of Celerity::Element
+    # 
+    
+    def last
+      self[INDEX_OFFSET - 1]
+    end
+
+    #
+    # Note: This can be quite useful in irb:
+    #
+    #   puts browser.text_fields
+    #
+    # @return [String] A string representation of all elements in this collection.
+    # 
+    
+    def to_s
+      map { |e| e.to_s }.join("\n")
+    end
+
+    private
+
+    def iterator_object(i)
+      element_class.new(@container, :index, i+1)
+    end
+
+  end # ElementCollection
+end # Celerity