vapir-common 1.7.0.rc1

data/History.txt

@@ -0,0 +1,5 @@
+=== 0.0.1 / 2008-08-28
+
+* Created
+
+

data/README.txt

@@ -0,0 +1,11 @@
+= vapir-common
+
+* http://vapir.org
+
+== DESCRIPTION:
+
+Common code used by Vapir-IE and Vapir-Firefox
+
+== INSTALL:
+
+* sudo gem install vapir-common

data/lib/vapir/common.rb

@@ -0,0 +1 @@
+require 'vapir-common'

data/lib/vapir-common/browser.rb

@@ -0,0 +1,184 @@
+# vapir-common/browser
+require 'vapir-common/options'
+module Vapir
+  
+=begin rdoc
+
+Watir is a family of open-source drivers for automating web browsers. You
+can use it to write tests that are easy to read and maintain. 
+
+Watir drives browsers the same way people do. It clicks links, fills in forms,
+presses buttons. Watir also checks results, such as whether expected text 
+appears on a page.
+
+The Watir family currently includes support for Internet Explorer (on Windows),
+Firefox (on Windows, Mac and Linux) and Safari (on Mac). 
+
+Project Homepage: http://wtr.rubyforge.org
+
+This Browser module provides a generic interface
+that tests can use to access any browser. The actual browser (and thus
+the actual Watir driver) is determined at runtime based on configuration
+settings.
+
+  require 'vapir'
+  browser = Watir::Browser.new
+  browser.goto 'http://google.com'
+  browser.text_field(:name, 'q').set 'pickaxe'
+  browser.button(:name, 'btnG').click
+  if browser.text.include? 'Programming Ruby'
+    puts 'Text was found'
+  else
+    puts 'Text was not found'
+  end
+
+A comprehensive summary of the Watir API can be found here
+http://wiki.openqa.org/display/WTR/Methods+supported+by+Element
+
+There are two ways to configure the browser that will be used by your tests.
+
+One is to set the +watir_browser+ environment variable to +ie+ or +firefox+. 
+(How you do this depends on your platform.)
+
+The other is to create a file that looks like this.
+
+  browser: ie
+
+And then to add this line to your script, after the require statement and 
+before you invoke Browser.new.
+
+  Watir.options_file = 'path/to/the/file/you/just/created'
+
+=end rdoc
+  
+  class Browser
+    @@browser_classes = {}
+    @@sub_options = {}
+    @@default = nil
+    class << self
+      alias __new__ new
+      def inherited(subclass)
+        class << subclass
+          alias new __new__
+        end
+      end
+
+      # Create a new instance of a browser driver, as determined by the
+      # configuration settings. (Don't be fooled: this is not actually 
+      # an instance of Browser class.)
+      def new *args, &block
+        #set_sub_options
+        browser=klass.new *args, &block
+        #browser=klass.allocate
+        #browser.send :initialize, *args, &block
+        browser
+      end
+      # makes sure that the class methods of Browser that call to the class methods of klass 
+      # are overridden so that Browser class methods aren't inherited causing infinite loop. 
+      def ensure_overridden
+        if self==klass
+          raise NotImplementedError, "This method must be overridden by #{self}!"
+        end
+      end
+
+      # Create a new instance as with #new and start the browser on the
+      # specified url.
+      def start url
+        ensure_overridden
+        set_sub_options
+        klass.start url
+      end
+      # Attach to an existing browser.
+      def attach(how, what)
+        ensure_overridden
+        set_sub_options
+        klass.attach(how, what)
+      end
+      def set_options options
+        #ensure_overridden
+        unless self==klass
+          klass.set_options options
+        end
+      end
+      def options
+        self==klass ? {} : klass.options
+      end
+
+      def klass
+        key = Vapir.options[:browser]
+        #eval(@@browser_classes[key]) # this triggers the autoload
+        browser_class_name=@@browser_classes[key]
+        klass=browser_class_name.split('::').inject(Object) do |namespace, name_part|
+          namespace.const_get(name_part)
+        end
+      end
+      private :klass
+      # Add support for the browser option, using the specified class, 
+      # provided as a string. Optionally, additional options supported by
+      # the class can be specified as an array of symbols. Options specified
+      # by the user and included in this list will be passed (as a hash) to 
+      # the set_options class method (if defined) before creating an instance.
+      def support hash_args
+        option = hash_args[:name]
+        class_string = hash_args[:class]
+        additional_options = hash_args[:options]
+        library = hash_args[:library]
+        gem = hash_args[:gem] || library
+
+        @@browser_classes[option] = class_string
+        @@sub_options[option] = additional_options
+
+        autoload class_string, library
+        activate_gem gem, option
+      end
+      
+      def default
+        @@default
+      end
+      # Specifies a default browser. Must be specified before options are parsed.
+      def default= option
+        @@default = option
+      end
+      # Returns the names of the browsers that are supported by this module.
+      # These are the options for 'watir_browser' (env var) or 'browser:' (yaml).
+      def browser_names
+        @@browser_classes.keys
+      end
+      
+      private
+      def autoload class_string, library
+        mod, klass = class_string.split('::')
+        eval "module ::#{mod}; autoload :#{klass}, '#{library}'; end"
+      end
+      # Activate the gem (if installed). The default browser will be set
+      # to the first gem that activates.
+      def activate_gem gem_name, option
+        begin
+          gem gem_name 
+          @@default ||= option
+        rescue Gem::LoadError
+        end
+      end
+      def set_sub_options
+        sub_options = @@sub_options[Vapir.options[:browser]]
+        return if sub_options.nil?
+        specified_options = Vapir.options.reject {|k, v| !sub_options.include? k}
+        self.set_options specified_options
+      end
+    end
+    # locate is used by stuff that uses container. this doesn't actually locate the browser
+    # but checks if it (still) exists. 
+    def locate(options={})
+      exists?
+    end
+    def locate!(options={})
+      locate(options) || raise(Vapir::Exception::NoMatchingWindowFoundException, "The browser window seems to be gone")
+    end
+    def inspect
+      "#<#{self.class}:0x#{(self.hash*2).to_s(16)} " + (exists? ? "url=#{url.inspect} title=#{title.inspect}" : "exists?=false") + '>'
+    end
+  end
+
+end
+
+require 'vapir-common/browsers'

data/lib/vapir-common/browsers.rb

@@ -0,0 +1,9 @@
+# vapir-common/browsers
+# Define browsers supported by Vapir
+
+Vapir::Browser.support :name => 'ie', :class => 'Vapir::IE', 
+  :library => 'vapir-ie', :gem => 'vapir-ie', 
+  :options => [:speed, :visible]
+
+Vapir::Browser.support :name => 'firefox', :class => 'Vapir::Firefox',
+  :library => 'vapir-firefox'

data/lib/vapir-common/container.rb

@@ -0,0 +1,163 @@
+require 'vapir-common/specifier'
+
+module Vapir
+  module Container
+    module_function
+    # returns an Element of the given class klass with the specified how & what, and
+    # with self as its container. 
+    # takes options:
+    # - :locate => true, false, :assert, or :nil_unless_exists
+    #    whether the element should locate itself. 
+    #    - false -  will not attempt to locate element at all
+    #    - true - will try to locate element but not complain if it can't
+    #    - :assert - will raise UnkownObjectException if it can't locate. 
+    #    - :nil_unless_exists - will attempt to locate the element, and only return it if 
+    #      successful - returns nil otherwise. 
+    # - :other_attributes => Hash, attributes other than the given how/what to look for. This is
+    #    used by radio and checkbox to specify :value (the third argument). 
+    #
+    # the arguments 'first' and 'second' (they are the first and second arguments given
+    # to the container method, not to this method) correspond to 'how' and 'what, after a fashion. 
+    # 
+    # see also #extra_for_contained on inheriting classes (IE::Element, Firefox::Element) for what this passes to the created 
+    # element, in terms of browser, container, other things each element uses. 
+    def element_by_howwhat(klass, first, second, other={})
+      other={:other_attributes => nil}.merge(other)
+      
+      how, what, index= *normalize_how_what_index(first, second, klass)
+
+      if other[:other_attributes]
+        if how==:attributes
+          what.merge!(other[:other_attributes])
+        else
+          raise ArgumentError, "other attributes were given, but we are not locating by attributes. We are locating by how=#{how.inspect} what=#{what.inspect}. other attributes given were #{other[:other_attributes].inspect}"
+        end
+      end
+      extra=extra_for_contained.merge(:index => index)
+      case other[:locate]
+      when :assert, true, false
+        element=klass.new(how, what, extra.merge(:locate => other[:locate]))
+      when :nil_unless_exists
+        element=klass.new(how, what, extra.merge(:locate => true))
+        element.exists? ? element : nil
+      else
+        raise ArgumentError, "Unrecognized value given for :locate: #{other[:locate].inspect} (#{other[:locate].class})"
+      end
+    end
+    
+    # figure out how and what from the form(s) that users give to the container methods, and translate 
+    # that to real how and what where 'how' is one of Vapir::ElementObjectCandidates::HowList and 
+    # 'what' corresponds. 
+    # this also determines index, when appropriate. 
+    def normalize_how_what_index(first, second, klass)
+      case first
+      when nil
+        raise Vapir::Exception::MissingWayOfFindingObjectException, "no first argument (how) was given!"
+      when Hash
+        how=:attributes
+        what=first.dup
+        index=what.delete(:index)
+        unless second==nil
+          raise(ArgumentError, "first argument was given as a Hash, so assumed to be the 'what' for how=:attributes, but a second argument was also given. arguments were #{first.inspect}, #{second.inspect}")
+        end
+      when String, Symbol
+        if Vapir::ElementObjectCandidates::HowList.include?(first)
+          how=first
+          what=second
+          index=nil
+        else
+          if second.nil?
+            if klass.default_how
+              how=:attributes
+              what={klass.default_how => first}
+              index=nil
+            else
+              raise Vapir::Exception::MissingWayOfFindingObjectException, "Cannot search using arguments #{first.inspect} (#{first.class}) and #{second.inspect} (#{second.class})"
+            end
+          elsif first==:index # this is different because the index number doesn't go in the 'what'
+            how=first
+            what=nil
+            index=second
+          else
+            if klass.all_dom_attr_aliases.any?{|(dom_attr, aliases)| aliases.include?(first.to_sym) || dom_attr==first.to_sym}
+              how=:attributes
+              what={first.to_sym => second}
+              index=nil
+            else
+              raise Vapir::Exception::MissingWayOfFindingObjectException, "Cannot search for a #{klass} using the given argument: #{first.inspect} (other argument was #{second.inspect})"
+            end
+          end
+        end
+      else
+        raise Vapir::Exception::MissingWayOfFindingObjectException, "Locating with the given arguments is not recognized or supported: #{first.inspect}, #{second.inspect}"
+      end
+      return [how, what, index]
+    end
+
+    public
+    # asserts that this element exists - optionally, takes a block, and other calls to assert_exists
+    # over the course of the block will not cause redundant assertions. 
+    def assert_exists(options={})
+      was_asserting_exists=@asserting_exists
+      if (!@asserting_exists || options[:force])
+        locate!
+      end
+      @asserting_exists=true
+      begin
+        if block_given?
+          result=yield
+        end
+      ensure
+        @asserting_exists=was_asserting_exists
+      end
+      result
+    end
+    
+    def default_extra_for_contained
+      extra={:container => self}
+      extra[:browser]= browser if respond_to?(:browser)
+      extra[:page_container]= page_container if respond_to?(:page_container)
+      extra
+    end
+    alias extra_for_contained default_extra_for_contained
+
+    # Checks if this container's text includes the given regexp or string. 
+    # Returns true if the container's #text matches the given String or Regexp; otherwise false. 
+    # 
+    # *Deprecated* 
+    # Instead use 
+    #   Container#text.include? target 
+    # or
+    #   Container#text.match target
+    def contains_text?(match)
+      if match.kind_of? Regexp
+        !!(text =~ match)
+      elsif match.kind_of? String
+        text.include?(match)
+      else
+        raise TypeError, "Expected String or Regexp, got #{match.inspect} (#{match.class.name})"
+      end
+    end
+    alias contains_text contains_text?
+
+    # 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
+    # when developing a test case using Vapir.
+    #
+    # Typical Usage:
+    #   browser.show_all_objects
+    #   browser.div(:id, 'foo').show_all_objects
+    #
+    # API: no
+    def show_all_objects(write_to=$stdout)
+      # this used to reject tagNames 'br', 'hr', 'doctype', 'meta', and elements with no tagName
+      elements.map do |element| 
+        element=element.to_factory
+        write_to.write element.to_s+"\n"
+        write_to.write '-'*42+"\n"
+        element
+      end
+    end
+  end
+end