vapir-ie 1.7.2 → 1.8.0

data/lib/vapir-ie.rb

@@ -6,23 +6,8 @@ module Vapir
   IE= Class.new(Vapir::Browser)
 end
 
-# these switches need to be deleted from ARGV to enable the Test::Unit
-# functionality that grabs
-# the remaining ARGV as a filter on what tests to run.
-# Note: this means that watir must be require'd BEFORE test/unit.
-# (Alternatively, you could require test/unit first and then put the Vapir::IE
-# arguments after the '--'.)
-
-# Make Internet Explorer invisible. -b stands for background
-$HIDE_IE ||= ARGV.delete('-b')
-
-# Run fast
-$FAST_SPEED = ARGV.delete('-f')
-
-# Eat the -s command line switch (deprecated)
-ARGV.delete('-s')
-
-require 'vapir-ie/ie-class'
+require 'vapir-ie/config'
+require 'vapir-ie/browser'
 require 'vapir-ie/elements'
 require 'vapir-ie/version'
 
@@ -31,14 +16,5 @@ require 'vapir-common/waiter'
 module Vapir
   include Vapir::Exception
 
-  # Directory containing the watir.rb file
-  @@dir = File.expand_path(File.dirname(__FILE__))
 
-  ATTACHER = Waiter.new
-  # Like regular Ruby "until", except that a TimeOutException is raised
-  # if the timeout is exceeded. Timeout is IE.attach_timeout.
-  def self.until_with_timeout # block
-    ATTACHER.timeout = IE.attach_timeout
-    ATTACHER.wait_until { yield }
-  end
 end

data/lib/vapir-ie/{ie-class.rb → browser.rb}

@@ -11,50 +11,6 @@ module Vapir
     include Vapir::Exception
     include IE::PageContainer
     
-    # Maximum number of seconds to wait when attaching to a window
-    @@attach_timeout = 2.0 # default value
-    def self.attach_timeout
-      @@attach_timeout
-    end
-    def self.attach_timeout=(timeout)
-      @@attach_timeout = timeout
-    end
-
-    # Return the options used when creating new instances of IE.
-    # BUG: this interface invites misunderstanding/misuse such as IE.options[:speed] = :zippy]
-    def self.options
-      {:speed => self.speed, :visible => self.visible, :attach_timeout => self.attach_timeout}
-    end
-    # set values for options used when creating new instances of IE.
-    def self.set_options options
-      options.each do |name, value|
-        send "#{name}=", value
-      end
-    end
-    # The globals $FAST_SPEED and $HIDE_IE are checked both at initialization 
-    # and later, because they
-    # might be set after initialization. Setting them beforehand (e.g. from
-    # the command line) will affect the class, otherwise it is only a temporary
-    # effect
-    @@speed = $FAST_SPEED ? :fast : :slow
-    def self.speed
-      return :fast if $FAST_SPEED
-      @@speed
-    end
-    def self.speed= x
-      $FAST_SPEED = nil
-      @@speed = x
-    end
-    @@visible = $HIDE_IE ? false : true
-    def self.visible
-      return false if $HIDE_IE
-      @@visible
-    end
-    def self.visible= x
-      $HIDE_IE = nil
-      @@visible = x
-    end
-        
     # IE inserts some element whose tagName is empty and just acts as block level element
     # Probably some IE method of cleaning things
     # To pass the same to the xml parser we need to give some name to empty tagName
@@ -64,257 +20,179 @@ module Vapir
     # the last command
     attr_reader :down_load_time
     
-    # the OLE Internet Explorer object
-    attr_accessor :ie
-    
     # access to the logger object
     attr_accessor :logger
     
     # this contains the list of unique urls that have been visited
     attr_reader :url_list
     
-    # Create a new IE window. Works just like IE.new in Watir 1.4.
-    def self.new_window
-      ie = new true
-      ie._new_window_init
-      ie
+    class << self
+      # Create a new IE window in a new process. 
+      # This method will not work when
+      # Vapir/Ruby is run under a service (instead of a user).
+      def new_process(options={})
+        new(options.merge(:new_process => true))
+      end
+
+      # Create a new IE window in a new process, starting at the specified URL. 
+      # Same as IE.start.
+      def start_process(url='about:blank', options={})
+        new(options.merge(:new_process => true, :goto => url))
+      end
+
+      # Yields successively to each IE window on the current desktop. Takes a block.
+      # This method will not work when
+      # Vapir/Ruby is run under a service (instead of a user).
+      # Yields to the window and its hwnd.
+      def each_browser
+        each_browser_object do |browser_object|
+          yield attach(:browser_object, browser_object)
+        end
+      end
+      alias each each_browser
+      def browsers
+        Enumerator.new(self, :each_browser)
+      end
+
+      # yields a WIN32OLE of each IE browser object that is available. 
+      def each_browser_object
+        shell = WIN32OLE.new('Shell.Application')
+        shell.Windows.each do |window|
+          if (window.path =~ /Internet Explorer/ rescue false) && (window.hwnd rescue false)
+            yield window
+          end
+        end
+      end
+      def browser_objects
+        Enumerator.new(self, :each_browser_object)
+      end
+
     end
     
     # Create an IE browser.
-    def initialize suppress_new_window=nil 
-      _new_window_init unless suppress_new_window 
-    end
-    
-    def _new_window_init
-      create_browser_window
-      initialize_options
-      goto 'about:blank' # this avoids numerous problems caused by lack of a document
-    end
-    
-    # Create a new IE Window, starting at the specified url.
-    # If no url is given, start empty.
-    def self.start url=nil
-      start_window url
-    end
-    
-    # Create a new IE window, starting at the specified url.
-    # If no url is given, start empty. Works like IE.start in Watir 1.4.
-    def self.start_window url=nil
-      ie = new_window
-      ie.goto url if url
-      ie
-    end
-
-    # Create a new IE window in a new process. 
-    # This method will not work when
-    # Vapir/Ruby is run under a service (instead of a user).
-    def self.new_process
-      ie = new true
-      ie._new_process_init
-      ie
-    end
-    
-    def _new_process_init
-      iep = Process.start
-      @ie = iep.window
-      @process_id = iep.process_id
-      initialize_options
-      goto 'about:blank'
-    end
-    
-    # Create a new IE window in a new process, starting at the specified URL. 
-    # Same as IE.start.
-    def self.start_process url=nil
-      ie = new_process
-      ie.goto url if url
-      ie
-    end
-    
-    # Return a Vapir::IE object for an existing IE window. Window can be
-    # referenced by url, title, or window handle.
-    # Second argument can be either a string or a regular expression in the 
-    # case of of :url or :title. 
-    # IE.attach(:url, 'http://www.google.com')
-    # IE.attach(:title, 'Google')
-    # IE.attach(:hwnd, 528140)
-    # This method will not work when
-    # Vapir/Ruby is run under a service (instead of a user).
-    def self.attach how, what
-      ie = new true # don't create window
-      ie._attach_init(how, what)
-      ie
-    end
-    
-    # this method is used internally to attach to an existing window
-    def _attach_init how, what
-      attach_browser_window how, what
-      initialize_options
-      wait
-    end
-
-    # Return an IE object that wraps the given window, typically obtained from
-    # Shell.Application.windows.
-    def self.bind window
-      ie = new true
-      ie.ie = window
-      ie.initialize_options
-      ie
-    end
-  
-    def create_browser_window
-      @ie = WIN32OLE.new('InternetExplorer.Application')
-    end
-    private :create_browser_window
-    
-    def initialize_options
-      self.visible = IE.visible
-      self.speed = IE.speed
+    #
+    # Takes a hash of options:
+    # - :timeout - the number of seconds to wait for a window to appear when 
+    #   attaching or launching. 
+    # - :goto - a url to which the IE browser will navigate. by default this 
+    #   is 'about:blank' for newly-launched IE instances, and the default is 
+    #   not to navigate anywhere for attached instances. 
+    # - :new_process - true or false, default is false. whether to launch this 
+    #   IE instance as its own process (this has no effect if :attach is 
+    #   specified)
+    # - :attach - a two-element Array of [how, what] where how is one of:
+    #   - :title - a string or regexp matching the title of the browser that
+    #     should be attached to. 
+    #   - :URL - a string or regexp matching the URL of the browser that 
+    #     should be attached to. 
+    #   - :HWND - specifies the HWND of the browser that should be attached to. 
+    #   - :name - the name of the window (as specified in the second argument to a 
+    #     window.open() javascript call) 
+    #   - :browser_object - this is generally just used internally. 'what' 
+    #     is a WIN32OLE object representing the browser. 
+    #   - :wait - true or false, default is true. whether to wait for the browser
+    #     to be ready before continuing. 
+    def initialize(method_options = {})
+      if method_options==true || method_options==false
+        raise NotImplementedError, "#{self.class.name}.new takes an options hash - passing a boolean for 'suppress_new_window' is no longer supported. Please see the documentation for #{self.class}.new"
+      end
+      options = options_from_config(method_options, {:timeout => :attach_timeout, :new_process => :ie_launch_new_process, :wait => :wait, :visible => :browser_visible}, [:attach, :goto])
 
-      @element_object = nil
-      @page_container = self
       @error_checkers = []
       
       @logger = DefaultLogger.new
       @url_list = []
-    end
 
-    # Specifies the speed that commands will be executed at. Choices are:
-    # * :slow (default)
-    # * :fast 
-    # * :zippy
-    # With IE#speed=  :zippy, text fields will be entered at once, instead of
-    # character by character (default).
-    def speed= how_fast
-      case how_fast
-      when :zippy then
-        @typingspeed = 0
-        @pause_after_wait = 0.01
-        @type_keys = false
-        @speed = :fast
-      when :fast then
-        @typingspeed = 0
-        @pause_after_wait = 0.01
-        @type_keys = true
-        @speed = :fast
-      when :slow then
-        @typingspeed = 0.08
-        @pause_after_wait = 0.1
-        @type_keys = true
-        @speed = :slow
+      if options[:attach]
+        how, what = *options[:attach]
+        if how== :browser_object
+          @browser_object = what
+        else
+          orig_how=how
+          hows={
+            :title => proc{|bo| bo.document.title },
+            :URL => proc{|bo| bo.locationURL },
+            :name => proc{|bo| bo.document.parentWindow.name },
+            :HWND => proc{|bo| Vapir::IE.fix_win32ole_hwnd(bo.HWND) },
+          }
+          how=hows.keys.detect{|h| h.to_s.downcase==orig_how.to_s.downcase}
+          raise ArgumentError, "how should be one of: #{hows.keys.inspect} (was #{orig_how.inspect})" unless how
+          @browser_object = ::Waiter.try_for(options[:timeout], :exception => NoMatchingWindowFoundException.new("Unable to locate a window with #{how} of #{what}")) do
+            self.class.browser_objects.detect do |browser_object|
+              begin
+                Vapir::fuzzy_match(hows[how].call(browser_object), what)
+              rescue WIN32OLERuntimeError, NoMethodError
+                false
+              end
+            end
+          end
+        end
+        if method_options.key?(:visible)
+          # only set visibility if it's explicitly in the options given to the method - don't set from config when using attach 
+          self.visible= method_options[:visible]
+        end
       else
-        raise ArgumentError, "Invalid speed: #{how_fast}"
+        if options[:new_process]
+          iep = Process.start
+          @browser_object = iep.browser_object(:timeout => options[:timeout])
+          @process_id = iep.process_id
+        else
+          @browser_object = WIN32OLE.new('InternetExplorer.Application')
+        end
+        self.visible= options[:visible]
+        goto('about:blank')
       end
-    end
-    
-    def speed
-      return @speed if @speed == :slow
-      return @type_keys ? :fast : :zippy
-    end
-    
-    # deprecated: use speed = :fast instead
-    def set_fast_speed
-      self.speed = :fast
+      goto(options[:goto]) if options[:goto]
+      wait if options[:wait]
+      self
     end
 
-    # deprecated: use speed = :slow instead
-    def set_slow_speed
-      self.speed = :slow
-    end
-    
     def visible
       assert_exists
-      @ie.visible
+      @browser_object.visible
     end
-    def visible=(boolean)
+    def visible=(visibility)
       assert_exists
-      @ie.visible = boolean if boolean != @ie.visible
-    end
-    
-    # Yields successively to each IE window on the current desktop. Takes a block.
-    # This method will not work when
-    # Vapir/Ruby is run under a service (instead of a user).
-    # Yields to the window and its hwnd.
-    def self.each
-      shell = WIN32OLE.new('Shell.Application')
-      shell.Windows.each do |window|
-        next unless (window.path =~ /Internet Explorer/ rescue false)
-        next unless (hwnd = window.hwnd rescue false)
-        ie = IE.bind(window)
-        ie.hwnd = hwnd
-        yield ie
-      end
-    end
-
-    # return internet explorer instance as specified. if none is found, 
-    # return nil.
-    # arguments:
-    #   :url, url -- the URL of the IE browser window
-    #   :title, title -- the title of the browser page
-    #   :hwnd, hwnd -- the window handle of the browser window.
-    # This method will not work when
-    # Vapir/Ruby is run under a service (instead of a user).
-    def self.find(how, what)
-      ie_ole = IE._find(how, what)
-      IE.bind ie_ole if ie_ole
-    end
-
-    def self._find(how, what)
-      ieTemp = nil
-      IE.each do |ie|
-        window = ie.ie
-        
-        case how
-        when :url
-          ieTemp = window if Vapir::fuzzy_match(window.locationURL, what)
-        when :title
-          # normal windows explorer shells do not have document
-          # note window.document will fail for "new" browsers
-          begin
-            title = window.locationname
-            title = window.document.title
-          rescue WIN32OLERuntimeError, NoMethodError
-          end
-          ieTemp = window if Vapir::fuzzy_match(title, what)
-        when :hwnd
-          begin
-            ieTemp = window if what == window.HWND
-          rescue WIN32OLERuntimeError, NoMethodError
-          end
-        else
-          raise ArgumentError
-        end
-      end
-      return ieTemp
+      @browser_object.visible = visibility
     end
     
-    def attach_browser_window how, what 
-      log "Seeking Window with #{how}: #{what}"
-      ieTemp = nil
-      begin
-        Vapir::until_with_timeout do
-          ieTemp = IE._find how, what
-        end
-      rescue TimeOutException
-        raise NoMatchingWindowFoundException,
-                 "Unable to locate a window with #{how} of #{what}"
-      end
-      @ie = ieTemp
-    end
-    private :attach_browser_window
+    # the WIN32OLE Internet Explorer object
+    #
+    # See: http://msdn.microsoft.com/en-us/library/aa752085%28v=VS.85%29.aspx
+    # and http://msdn.microsoft.com/en-us/library/aa752084%28v=VS.85%29.aspx
+    attr_reader :browser_object
+    alias ie browser_object
     
-    def browser_object
+    # Return the window handle of this browser
+    def hwnd
       assert_exists
-      @ie
+      @hwnd ||= Vapir::IE.fix_win32ole_hwnd(@browser_object.HWND)
     end
     
-    # Return the current window handle
-    def hwnd
-      assert_exists
-      @hwnd ||= @ie.hwnd
+    # win32ole's #HWND method casts to signed somewhere along its way, so returns 
+    # a negative number. this is wrong, WinWindow will reject it (correctly), so we 
+    # need to fix. 
+    def self.fix_win32ole_hwnd(win32ole_hwnd)
+      win32ole_hwnd < 0 ? win32ole_hwnd % 2**32 : win32ole_hwnd
+    end
+
+    # returns the process id of this browser 
+    def process_id
+      @process_id ||= win_window.process_id
+    end
+    # kills this process. NOTE that this process may be running
+    # multiple browsers; killing the process will kill them all. 
+    # use #close to close a single browser. 
+    def kill
+      # todo: drop win32api; use ffi 
+      require 'Win32API'
+      right_to_terminate_process = 1
+      handle = Win32API.new('kernel32.dll', 'OpenProcess', 'lil', 'l').call(right_to_terminate_process, 0, process_id)
+      Win32API.new('kernel32.dll', 'TerminateProcess', 'll', 'l').call(handle, 0)
     end
-    attr_writer :hwnd
     
     def win_window
+      Vapir.require_winwindow
       @win_window||= WinWindow.new(hwnd)
     end
     
@@ -343,8 +221,8 @@ module Vapir
 
     # Are we attached to an open browser?
     def exists?
-      !!(@ie && begin
-        @ie.name
+      !!(@browser_object && begin
+        @browser_object.name
       rescue WIN32OLERuntimeError, NoMethodError
         raise unless $!.message =~ ExistenceFailureCodesRE
         false
@@ -367,12 +245,12 @@ module Vapir
     
     # Return the title of the document
     def title
-      @ie.document.title
+      @browser_object.document.title
     end
     
     # Return the status of the window, typically from the status bar at the bottom.
     def status
-      return @ie.statusText
+      return @browser_object.statusText
     end
     
     #
@@ -383,7 +261,7 @@ module Vapir
     #  * url - string - the URL to navigate to
     def goto(url)
       assert_exists do
-        @ie.navigate(url)
+        @browser_object.navigate(url)
         wait
         return @down_load_time
       end
@@ -393,7 +271,7 @@ module Vapir
     # an WIN32OLERuntimeError exception is raised if the browser cant go back
     def back
       assert_exists do
-        @ie.GoBack
+        @browser_object.GoBack
         wait
       end
     end
@@ -402,7 +280,7 @@ module Vapir
     # an WIN32OLERuntimeError exception is raised if the browser cant go forward
     def forward
       assert_exists do
-        @ie.GoForward
+        @browser_object.GoForward
         wait
       end
     end
@@ -417,7 +295,7 @@ module Vapir
     # an WIN32OLERuntimeError exception is raised if the browser cant refresh
     def refresh
       assert_exists do
-        @ie.refresh2(RefreshConstants::REFRESH_COMPLETELY)
+        @browser_object.refresh2(RefreshConstants::REFRESH_COMPLETELY)
         wait
       end
     end
@@ -430,13 +308,13 @@ module Vapir
     # Closes the Browser
     def close
       assert_exists
-      @ie.stop
-      @ie.quit
+      @browser_object.stop
+      @browser_object.quit
       # TODO/fix timeout; this shouldn't be a hard-coded magic number. 
       ::Waiter.try_for(32, :exception => WindowFailedToCloseException.new("The browser window did not close"), :interval => 1) do
         begin
           if exists?
-            @ie.quit
+            @browser_object.quit
             false
           else
             true
@@ -446,7 +324,7 @@ module Vapir
           true
         end
       end
-      @ie=nil
+      @browser_object=nil
     end
     
     # Maximize the window (expands to fill the screen)
@@ -486,18 +364,22 @@ module Vapir
     
     # saves a screenshot of this browser window to the given filename. 
     #
-    # second argument, optional, specifies what area to take a screenshot of. 
-    # - :client takes a screenshot of the client area, which excludes the menu bar and other window trimmings.
-    # - :window (default) takes a screenshot of the full browser window
-    # - :desktop takes a screenshot of the full desktop
-    def screen_capture(filename, dc=:window)
-      if dc==:desktop
-        screenshot_win=WinWindow.desktop_window
-        dc=:window
-      else
-        screenshot_win=win_window
+    # the screenshot format is BMP (DIB), so you should name your files to end with .bmp 
+    #
+    # the last argument is an optional options hash, taking options:
+    # - :dc => (default is :window). may be one of: 
+    #   - :client takes a screenshot of the client area, which excludes the menu bar and other window trimmings.
+    #   - :window (default) takes a screenshot of the full browser window
+    #   - :desktop takes a screenshot of the full desktop
+    def screen_capture(filename, options = {})
+      unless options.is_a?(Hash)
+        dc = options
+        options = {:dc => dc}
+        if config.warn_deprecated
+          Kernel.warn_with_caller("WARNING: The API for #screen_capture has changed and the last argument is now an options hash. Please change calls to this method to specify :dc => #{dc.inspect}")
+        end
       end
-      screenshot_win.capture_to_bmp_file(filename, :dc => dc)
+      screen_capture_win_window(filename, options)
     end
     
     def dir
@@ -511,7 +393,7 @@ module Vapir
     # Return the current document
     def document
       assert_exists
-      return @ie.document
+      return @browser_object.document
     end
     alias document_object document
     
@@ -522,7 +404,7 @@ module Vapir
     # returns the current url, as displayed in the address bar of the browser
     def url
       assert_exists
-      return @ie.LocationURL
+      return @browser_object.LocationURL
     end
 
     # Error checkers
@@ -778,12 +660,7 @@ module Vapir
         temp = element_by_absolute_xpath(modifiedXpath) # temp = a DOM/COM element
         selectedElements << temp if temp != nil
       end
-      #puts selectedElements.length
-      if selectedElements.length == 0
-        return nil
-      else
-        return selectedElements
-      end
+      return selectedElements
     end
     
     # Method that iterates over IE DOM object and get the elements for the given
@@ -875,4 +752,21 @@ module Vapir
     end
     
   end # class IE
+  module WatirConfigCompatibility
+    module Visible
+      def visible
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #visible is deprecated; please use the new config framework with config.browser_visible"
+        end
+        config.browser_visible
+      end
+      def visible= visibility
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #visible= is deprecated; please use the new config framework with config.browser_visible="
+        end
+        config.browser_visible=visibility
+      end
+    end
+    Vapir::IE.send(:extend, Visible)
+  end
 end