vapir-common 1.8.1 → 1.9.0

data/lib/vapir-common.rb

@@ -4,6 +4,8 @@ require 'vapir-common/browser'
 require 'vapir-common/exceptions'
 require 'vapir-common/config'
 module Vapir
+  # requires the winwindow library, raising a more informative error message than the default
+  # on failure. 
   def self.require_winwindow
     begin
       require 'winwindow'

data/lib/vapir-common/config.rb

@@ -5,6 +5,7 @@ module Vapir
     class Error < StandardError; end
     class BadKeyError < Error; end
     class NoValueError < Error; end
+    class InvalidValueError < Error; end
     
     # represents a valid option on a Configuration. consists of a key and criteria
     # for which a value is valid for that key. 
@@ -34,7 +35,7 @@ module Vapir
           when 'false', false
             false
           else
-            raise ArgumentError, "value should look like a boolean for key #{key}; instead got #{value.inspect}"
+            raise InvalidValueError, "value should look like a boolean for key #{key}; instead got #{value.inspect}"
           end
         when :numeric
           case value
@@ -44,13 +45,21 @@ module Vapir
             begin
               Float(value)
             rescue ArgumentError
-              raise ArgumentError, "value should look like a number for key #{key}; instead got #{value.inspect}"
+              raise InvalidValueError, "value should look like a number for key #{key}; instead got #{value.inspect}"
             end
           else
-            raise ArgumentError, "value should look like a number for key #{key}; instead got #{value.inspect}"
+            raise InvalidValueError, "value should look like a number for key #{key}; instead got #{value.inspect}"
+          end
+        when :positive_integer
+          if value.is_a?(Integer) && value > 0
+            value
+          elsif value.is_a?(String) && value.strip =~ /\A\d+\z/ && value.to_i > 0
+            value.to_i
+          else
+            raise InvalidValueError, "value should be a positive integer; got #{value.inspect}"
           end
         else
-          raise ArgumentError, "invalid validator given: #{@validotor.inspect}\nvalidator should be nil for unspecified, a Proc, or a symbol indicating a known validator type"
+          raise ArgumentError, "invalid validator given: #{@validator.inspect}\nvalidator should be nil for unspecified, a Proc, or a symbol indicating a known validator type"
         end
       end
     end
@@ -129,6 +138,14 @@ module Vapir
     def defined_key?(key)
       locally_defined_key?(key) || (parent && parent.defined_key?(key))
     end
+    # returns an array of keys defined on the current configuration 
+    def defined_keys
+      recognized_keys.select{|key| defined_key?(key) }
+    end
+    # returns a hash of currently defined configuration keys and values 
+    def defined_hash
+      (@parent ? @parent.defined_hash : {}).merge(@config_hash).freeze
+    end
     # raises an error if the given key is not in an acceptable format. the key should be a string
     # or symbol consisting of alphanumerics and underscorse, beginning with an alpha or underscore. 
     def validate_key_format!(key)
@@ -212,7 +229,7 @@ module Vapir
     end
     # see Configuration#with_config
     def with_config(hash, &block)
-      @configuration.with_config(hash, &block)
+      config.with_config(hash, &block)
     end
     private
     # takes a hash of given options, a map of config keys, and a list of other allowed keys. 
@@ -287,8 +304,9 @@ module Vapir
     end
   end
 
+  # :stopdoc:
   @configurations = []
-  def (@configurations).update_from_source
+  def (@configurations).update_from_source # :nodoc:
     self.each do |c|
       if c.respond_to?(:update_from_source)
         c.update_from_source 
@@ -298,15 +316,18 @@ module Vapir
 
   @configurations.push(@base_configuration=Configuration.new(nil) do |config|
     config.create_update(:attach_timeout, 30, :validator => :numeric)
+    config.create_update(:close_timeout, 16, :validator => :numeric)
+    config.create_update(:quit_timeout, 8, :validator => :numeric)
     config.create(:default_browser, :validator => proc do |val|
       require 'vapir-common/browsers'
       unless (val.is_a?(String) || val.is_a?(Symbol)) && (real_key = Vapir::SupportedBrowsers.keys.detect{|key| key.to_s==val.to_s })
-        raise ArgumentError, "default_browser should be a string or symbol matching a supported browser - one of: #{Vapir::SupportedBrowsers.keys.join(', ')}. instead got #{value.inspect}"
+        raise Vapir::Configuration::InvalidValueError, "default_browser should be a string or symbol matching a supported browser - one of: #{Vapir::SupportedBrowsers.keys.join(', ')}. instead got #{val.inspect}"
       end
       real_key
     end)
     config.create_update(:highlight_color, 'yellow')
     config.create_update(:wait, true, :validator => :boolean)
+    config.create_update(:wait_timeout, 120, :validator => :numeric)
     config.create_update(:type_keys, false, :validator => :boolean)
     config.create_update(:typing_interval, 0, :validator => :numeric)
     config.create_update(:warn_deprecated, true, :validator => :boolean)
@@ -337,5 +358,6 @@ module Vapir
   @env_configuration.update_from_source
   
   @configuration_parent = @configurations.last
+  # :startdoc:
   extend Configurable # makes Vapir.config which is the in-process user-configurable one, overriding base, yaml, and env 
 end

data/lib/vapir-common/container.rb

@@ -180,63 +180,8 @@ module Vapir
     # returns an array of text nodes below this element in the DOM heirarchy which are visible - 
     # that is, their parent element is visible. 
     def visible_text_nodes
-      # TODO: needs tests 
       assert_exists do
-        recurse_text_nodes=ycomb do |recurse|
-          proc do |node, parent_visibility|
-            case node.nodeType
-            when 1, 9 # TODO: name a constant ELEMENT_NODE, rather than magic number 
-              style= node.nodeType==1 ? base_element_class.element_object_style(node, document_object) : nil
-              our_visibility = style && (visibility=style.invoke('visibility'))
-              unless our_visibility && ['hidden', 'collapse', 'visible'].include?(our_visibility=our_visibility.strip.downcase)
-                our_visibility = parent_visibility
-              end
-              display = style && style.invoke('display')
-              if display && display.strip.downcase=='none'
-                []
-              else
-                Vapir::Element.object_collection_to_enumerable(node.childNodes).inject([]) do |result, child_node|
-                  result + recurse.call(child_node, our_visibility)
-                end
-              end
-            when 3 # TODO: name a constant TEXT_NODE, rather than magic number 
-              if parent_visibility && ['hidden','collapse'].include?(parent_visibility.downcase)
-                []
-              else
-                [node.data]
-              end
-            else
-              #Kernel.warn("ignoring node of type #{node.nodeType}")
-              []
-            end
-          end
-        end
-  
-        # determine the current visibility and display. TODO: this is copied/adapted from #visible?; should DRY 
-        element_to_check=containing_object
-        real_visibility=nil
-        while element_to_check #&& !element_to_check.instanceof(nsIDOMDocument)
-          if (style=base_element_class.element_object_style(element_to_check, document_object))
-            # only pay attention to the innermost definition that really defines visibility - one of 'hidden', 'collapse' (only for table elements), 
-            # or 'visible'. ignore 'inherit'; keep looking upward. 
-            # this makes it so that if we encounter an explicit 'visible', we don't pay attention to any 'hidden' further up. 
-            # this style is inherited - may be pointless for firefox, but IE uses the 'inherited' value. not sure if/when ff does.
-            if real_visibility==nil && (visibility=style.invoke('visibility'))
-              visibility=visibility.strip.downcase
-              if ['hidden', 'collapse', 'visible'].include?(visibility)
-                real_visibility=visibility
-              end
-            end
-            # check for display property. this is not inherited, and a parent with display of 'none' overrides an immediate visibility='visible' 
-            display=style.invoke('display')
-            if display && (display=display.strip.downcase)=='none'
-              # if display is none, then this element is not visible, and thus has no visible text nodes underneath. 
-              return []
-            end
-          end
-          element_to_check=element_to_check.parentNode
-        end
-        recurse_text_nodes.call(containing_object, real_visibility)
+        visible_text_nodes_method.call(containing_object, document_object)
       end
     end
     # returns an visible text inside this element by concatenating text nodes below this element in the DOM heirarchy which are visible.
@@ -286,6 +231,128 @@ module Vapir
       element_class
     end
     
+    # takes one argument, a proc. 
+    # this will be yielded successive dom nodes, and should return true if the node matches whatever
+    # criteria you care to match; false otherwise. 
+    #
+    # returns an ElementCollection consisting of the deepest elements within the dom heirarchy
+    # which match the given match_proc_or_function. 
+    def base_innermost_by_node(match_proc)
+      ElementCollection.new(self, base_element_class, extra_for_contained.merge(:candidates => proc do |container|
+        ycomb do |innermost_matching_nodes|
+          proc do |container_node|
+            child_nodes = Vapir::Element.object_collection_to_enumerable(container_node.childNodes)
+            matched_child_elements=child_nodes.select do |node|
+              node.nodeType==1 && match_proc.call(node)
+            end
+            if matched_child_elements.empty?
+              [container_node]
+            else
+              matched_child_elements.map do |matched_child_element|
+                innermost_matching_nodes.call(matched_child_element)
+              end.inject([], &:+)
+            end
+          end
+        end.call(container.containing_object)
+      end))
+    end
+    alias innermost_by_node base_innermost_by_node
+    # takes text or regexp, and returns an ElementCollection consisting of deepest (innermost) elements in the dom heirarchy whose visible text
+    # matches what's given (by substring for text; by regexp match for regexp) 
+    def base_innermost_matching_visible_text(text_or_regexp)
+      innermost_by_node(proc do |node|
+        visible_text_nodes_method.call(node, document_object).join('')[text_or_regexp] # String#[] works with either text or regexp - returns the matched substring or nil 
+      end)
+    end
+    alias innermost_matching_visible_text base_innermost_matching_visible_text
+    
+    private
+    # returns a proc that takes a node and a document object, and returns 
+    # true if the element's display property will allow it to be displayed; false if not. 
+    def element_displayed_method
+      @element_displayed_method ||= proc do |node, document_object|
+        style= node.nodeType==1 ? base_element_class.element_object_style(node, document_object) : nil
+        display = style && style.invoke('display')
+        displayed = display ? display.strip.downcase!='none' : true
+        displayed
+      end
+    end
+    
+    # returns a proc that takes a node and a document object, and returns 
+    # the visibility of that node, obtained by ascending the dom until an explicit 
+    # definition for visibility is found. 
+    def element_real_visibility_method
+      @element_real_visibility_method ||= proc do |element_to_check, document_object|
+        real_visibility=nil
+        while element_to_check && real_visibility==nil
+          style = base_element_class.element_object_style(element_to_check, document_object)
+          if style
+            # only pay attention to the innermost definition that really defines visibility - one of 'hidden', 'collapse' (only for table elements), 
+            # or 'visible'. ignore 'inherit'; keep looking upward. 
+            # this makes it so that if we encounter an explicit 'visible', we don't pay attention to any 'hidden' further up. 
+            # this style is inherited - may be pointless for firefox, but IE uses the 'inherited' value. not sure if/when ff does.
+            if style.invoke('visibility')
+              visibility=style.invoke('visibility').strip.downcase
+              if ['hidden', 'collapse', 'visible'].include?(visibility)
+                real_visibility=visibility
+              end
+            end
+          end
+          element_to_check=element_to_check.parentNode
+        end
+        real_visibility
+      end
+    end
+
+    # returns a proc that takes a node and a document object, and returns 
+    # an Array of strings, each of which is the data of a text node beneath the given node which 
+    # is visible. 
+    def visible_text_nodes_method
+      @visible_text_nodes_method ||= proc do |element_object, document_object|
+        recurse_text_nodes=ycomb do |recurse|
+          proc do |node, parent_visibility|
+            case node.nodeType
+            when 1, 9 # TODO: name a constant ELEMENT_NODE, rather than magic number 
+              style= node.nodeType==1 ? base_element_class.element_object_style(node, document_object) : nil
+              our_visibility = style && (visibility=style.invoke('visibility'))
+              unless our_visibility && ['hidden', 'collapse', 'visible'].include?(our_visibility=our_visibility.strip.downcase)
+                our_visibility = parent_visibility
+              end
+              if !element_displayed_method.call(node, document_object)
+                []
+              else
+                Vapir::Element.object_collection_to_enumerable(node.childNodes).inject([]) do |result, child_node|
+                  result + recurse.call(child_node, our_visibility)
+                end
+              end
+            when 3 # TODO: name a constant TEXT_NODE, rather than magic number 
+              if parent_visibility && ['hidden','collapse'].include?(parent_visibility.downcase)
+                []
+              else
+                [node.data]
+              end
+            else
+              #Kernel.warn("ignoring node of type #{node.nodeType}")
+              []
+            end
+          end
+        end
+  
+        # determine the current visibility and display. 
+        element_to_check=element_object
+        while element_to_check
+          if !element_displayed_method.call(element_to_check, document_object)
+            # check for display property. this is not inherited, and a parent with display of 'none' overrides an immediate visibility='visible' 
+            # if display is none, then this element is not visible, and thus has no visible text nodes underneath. 
+            return []
+          end
+          element_to_check=element_to_check.parentNode
+        end
+        recurse_text_nodes.call(element_object, element_real_visibility_method.call(element_object, document_object))
+      end
+    end
+    
+    public
     # shows the available objects on the current container.
     # This is usually only used for debugging or writing new test scripts.
     # This is a nice feature to help find out what HTML objects are on a page
@@ -333,3 +400,4 @@ module Vapir
     end
   end
 end
+

data/lib/vapir-common/element.rb

@@ -449,7 +449,7 @@ module Vapir
     def visible? 
       assert_exists do
         element_to_check=element_object
-        #nsIDOMDocument=jssh_socket.Components.interfaces.nsIDOMDocument
+        #nsIDOMDocument=firefox_socket.Components.interfaces.nsIDOMDocument
         really_visible=nil
         while element_to_check #&& !element_to_check.instanceof(nsIDOMDocument)
           if (style=element_object_style(element_to_check, document_object))
@@ -579,22 +579,28 @@ module Vapir
       @container
     end
     
+    # the Vapir::Browser this element is on
     attr_reader :browser
+    # the Vapir::PageContainer containing this element (a Browser, Frame, or ModalDialogDocument) 
     attr_reader :page_container
 
     def document_object
       assert_container
       @container.document_object
     end
+    # returns the content window object of the current page on the browser (this is the 'window'
+    # object in javascript). 
     def content_window_object
       assert_container
       @container.content_window_object
     end
+    # returns the underlying object representing the browser. 
     def browser_window_object
       assert_container
       @container.browser_window_object
     end
     
+    # used by inspect, to_s, and pretty_print to determine what to show 
     def attributes_for_stringifying
       attributes_to_inspect=self.class.attributes_to_inspect
       unless exists?
@@ -621,6 +627,9 @@ module Vapir
         " "+attr.first+'='+attr.last.inspect
       end.join('') + ">"
     end
+    # returns a string representation of this element with each attribute on its own line. this 
+    # returns the same information as #inspect, but formatted somewhat more readably. you might 
+    # also be interested in pretty-printing the element; see the pp library. 
     def to_s
       attrs=attributes_for_stringifying
       longest_label=attrs.inject(0) {|max, attr| [max, attr.first.size].max }
@@ -647,7 +656,7 @@ module Vapir
     def object_collection_to_enumerable(object)
       if object.is_a?(Enumerable)
         object
-      elsif Object.const_defined?('JsshObject') && object.is_a?(JsshObject)
+      elsif Object.const_defined?('JavascriptObject') && object.is_a?(JavascriptObject)
         object.to_array
       elsif Object.const_defined?('WIN32OLE') && object.is_a?(WIN32OLE)
         array=[]

data/lib/vapir-common/element_class_and_module.rb

@@ -4,7 +4,7 @@ module Vapir
   # this module is for methods that should go on both common element modules (ie, TextField) as well
   # as browser-specific element classes (ie, Firefox::TextField). 
   module ElementClassAndModuleMethods
-    # takes an element_object (JsshObject or WIN32OLE), and finds the most specific class 
+    # takes an element_object (JavascriptObject or WIN32OLE), and finds the most specific class 
     # that is < self whose specifiers match it. Returns an instance of that class using the given
     # element_object. 
     #

data/lib/vapir-common/elements/elements.rb

@@ -178,6 +178,7 @@ module Vapir
     # Raises ObjectDisabledException if the object is disabled
     # Raises ObjectReadOnlyException if the object is read only
     def append(value, options={})
+      raise ArgumentError, "Text field value must be a string! Got #{value.inspect}" unless value.is_a?(String)
       options={:blur => true, :change => true, :select => true, :focus => true}.merge(options)
       assert_enabled
       assert_not_readonly

data/lib/vapir-common/external/core_extensions.rb

@@ -34,13 +34,23 @@ unless :to_proc.respond_to?(:to_proc)
   end
 end
 
+class Hash
+  # returns a hash whose keys are the intersection of the keys of this hash and the keys given 
+  # as arguments to this function. values are the same as in this hash. 
+  def select_keys(*keys)
+    keys.inject(self.class.new) do |hash,key|
+      self.key?(key) ? hash.merge(key => self[key]) : hash
+    end
+  end
+end
+
 module Kernel
   # this is the Y-combinator, which allows anonymous recursive functions. for a simple example, 
   # to define a recursive function to return the length of an array:
   #
-  # length = ycomb do |len|
-  #   proc{|list| list == [] ? 0 : len.call(list[1..-1]) }
-  # end
+  #  length = ycomb do |len|
+  #    proc{|list| list == [] ? 0 : len.call(list[1..-1]) }
+  #  end
   #
   # see https://secure.wikimedia.org/wikipedia/en/wiki/Fixed_point_combinator#Y_combinator
   # and chapter 9 of the little schemer, available as the sample chapter at http://www.ccs.neu.edu/home/matthias/BTLS/
@@ -50,7 +60,7 @@ module Kernel
   module_function :ycomb
 
   def warn_with_caller(message)
-    Kernel.warn "#{message}\ncalled from: #{caller[1..-1].map{|c|"\n\t"+c}}"
+    Kernel.warn "#{message}\ncalled from: #{caller[1..-1].map{|c|"\n\t"+c}.join('')}"
   end
   module_function :warn_with_caller
 end

data/lib/vapir-common/specifier.rb

@@ -109,6 +109,16 @@ module Vapir
                                   names.first.is_a?(String) && 
                                   container.containing_object.object_respond_to?(:getElementsByName) &&
                                   specifiers.all?{|specifier| specifier[:tagName].is_a?(String) && %w(BUTTON TEXTAREA APPLET SELECT FORM FRAME IFRAME IMG A INPUT OBJECT MAP PARAM META).include?(specifier[:tagName].upcase) }
+      # thing to determine if object_respond_to?(:getElementsByClassName) is lying. returns 
+      # true if the thing is full of lies. 
+      getElementsByClassName_lies = proc do
+        Object.const_defined?('WIN32OLERuntimeError') && begin
+          container.containing_object.getElementsByClassName('dummy')
+          false
+        rescue WIN32OLERuntimeError, NoMethodError
+          true
+        end
+      end
       if can_use_getElementById
         candidates= if by_id=container.containing_object.getElementById(ids.first)
           [by_id]
@@ -117,7 +127,7 @@ module Vapir
         end
       elsif can_use_getElementsByName
         candidates=container.containing_object.getElementsByName(names.first)#.to_array
-      elsif classNames.size==1 && classNames.first.is_a?(String) && container.containing_object.object_respond_to?(:getElementsByClassName)
+      elsif classNames.size==1 && classNames.first.is_a?(String) && container.containing_object.object_respond_to?(:getElementsByClassName) && !getElementsByClassName_lies.call
         candidates=container.containing_object.getElementsByClassName(classNames.first)
       elsif tags.size==1 && tags.first.is_a?(String)
         candidates=container.containing_object.getElementsByTagName(tags.first)
@@ -127,7 +137,7 @@ module Vapir
       # return:
       if candidates.is_a?(Array)
         candidates
-      elsif Object.const_defined?('JsshObject') && candidates.is_a?(JsshObject)
+      elsif Object.const_defined?('JavascriptObject') && candidates.is_a?(JavascriptObject)
         candidates.to_array
       elsif Object.const_defined?('WIN32OLE') && candidates.is_a?(WIN32OLE)
         candidates.send :extend, Enumerable
@@ -141,15 +151,15 @@ module Vapir
       unless specifiers_list.is_a?(Enumerable) && specifiers_list.all?{|spec| spec.is_a?(Hash)}
         raise ArgumentError, "specifiers_list should be a list of Hashes!"
       end
-      if Object.const_defined?('JsshObject') && (candidates.is_a?(JsshObject) || (candidates.length != 0 && candidates.all?{|c| c.is_a?(JsshObject)}))
-        # optimize for JSSH by moving code to the other side of the socket, rather than talking across it a whole lot
+      if Object.const_defined?('JavascriptObject') && (candidates.is_a?(JavascriptObject) || (candidates.length != 0 && candidates.all?{|c| c.is_a?(JavascriptObject)}))
+        # optimize for firefox by moving code to the other side of the socket, rather than talking across it a whole lot
         # this javascript should be exactly the same as the ruby in the else (minus WIN32OLE optimization) - 
         # just written in javascript instead of ruby. 
         #
         # Note that the else block works perfectly fine, but is much much slower due to the amount of 
         # socket activity. 
-        jssh_socket= candidates.is_a?(JsshObject) ? candidates.jssh_socket : candidates.first.jssh_socket
-        match_candidates_js=JsshObject.new("
+        firefox_socket= candidates.is_a?(JavascriptObject) ? candidates.firefox_socket : candidates.first.firefox_socket
+        match_candidates_js=JavascriptObject.new("
           (function(candidates, specifiers_list, aliases)
           { candidates=$A(candidates);
             specifiers_list=$A(specifiers_list);
@@ -214,7 +224,7 @@ module Vapir
             });
             return matched_candidates;
           })
-        ", jssh_socket, :debug_name => 'match_candidates_function')
+        ", firefox_socket, :debug_name => 'match_candidates_function')
         matched_candidates=match_candidates_js.call(candidates, specifiers_list, aliases)
         if block_given?
           matched_candidates.to_array.each do |matched_candidate|
@@ -301,6 +311,9 @@ module Vapir
 
   # This is on the Vapir module itself because it's used in a number of other places, should be in a broad namespace. 
   module_function
+  # fuzzily matches the given attribute with the given 'what'. if 'what' is a regexp, matches it 
+  # against attr; if it's a string, downcases and strips before comparing; tries a couple other 
+  # things; falls back to normal equality-checking. read the source for more information. 
   def fuzzy_match(attr, what)
     # IF YOU CHANGE THIS, CHANGE THE JAVASCRIPT REIMPLEMENTATION IN match_candidates
     case what

data/lib/vapir-common/version.rb

@@ -1,5 +1,5 @@
 module Vapir
   module Common
-    VERSION = '1.8.1'
+    VERSION = '1.9.0'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: vapir-common
 version: !ruby/object:Gem::Version 
-  hash: 53
+  hash: 51
   prerelease: false
   segments: 
   - 1
-  - 8
-  - 1
-  version: 1.8.1
+  - 9
+  - 0
+  version: 1.9.0
 platform: ruby
 authors: 
 - Ethan
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-17 00:00:00 -04:00
+date: 2011-08-04 00:00:00 -04:00
 default_executable: 
 dependencies: []