vapir-firefox 1.7.2 → 1.8.0

data/lib/vapir-firefox/{firefox.rb → browser.rb}

@@ -97,16 +97,16 @@ module Vapir
     include Firefox::Window
     include Firefox::ModalDialogContainer
 
-    def self.initialize_jssh_socket
-      # if it already exists and is not nil, then we are clobbering an existing one, presumably dead. but a new socket will not have any objects of the old one, so warn 
-      if class_variable_defined?('@@jssh_socket') && @@jssh_socket 
-        Kernel.warn "WARNING: JSSH_SOCKET RESET: resetting jssh socket. Any active javascript references will not exist on the new socket!"
-      end
+    # initializes a JsshSocket and stores in a class variable. 
+    def self.initialize_jssh_socket # :nodoc:
+      uninitialize_jssh_socket
       @@jssh_socket=JsshSocket.new
       @@firewatir_jssh_objects=@@jssh_socket.object("Vapir").assign({})
       @@jssh_socket
     end
-    def self.jssh_socket(options={})
+    # returns a connected JsshSocket. pass :reset_if_dead => true if you suspect an existing 
+    # socket may be dead, and you want a new one. a warning will be printed if this occurs. 
+    def self.jssh_socket(options={}) # :nodoc:
       if options[:reset] || !(class_variable_defined?('@@jssh_socket') && @@jssh_socket)
         initialize_jssh_socket
       end
@@ -114,11 +114,17 @@ module Vapir
         begin
           @@jssh_socket.assert_socket
         rescue JsshConnectionError
+          Kernel.warn "WARNING: JsshSocket RESET: resetting jssh socket. Any active javascript references will not exist on the new socket!"
           initialize_jssh_socket
         end
       end
       @@jssh_socket
     end
+    # unsets a the current jssh socket 
+    def self.uninitialize_jssh_socket # :nodoc:
+      @@jssh_socket=nil
+      @@firewatir_jssh_objects=nil
+    end
     def jssh_socket(options=nil)
       options ? self.class.jssh_socket(options) : @@jssh_socket
     end
@@ -129,19 +135,25 @@ module Vapir
     #
     # Input:
     #   options  - Hash of any of the following options:
-    #     :wait_time - Time to wait for Firefox to start. By default it waits for 2 seconds.
+    #     :timeout  - Time to wait for Firefox to start. By default it waits for 2 seconds.
     #                 This is done because if Firefox is not started and we try to connect
     #                 to jssh on port 9997 an exception is thrown.
     #     :profile  - The Firefox profile to use. If none is specified, Firefox will use
     #                 the last used profile.
-    #     :suppress_launch_process - do not create a new firefox process. Connect to an existing one.
-    # TODO: Start the firefox version given by user.
     def initialize(options = {})
       if(options.kind_of?(Integer))
-        options = {:wait_time => options}
-        Kernel.warn "DEPRECATION WARNING: #{self.class.name}.new takes an options hash - passing a number is deprecated. Please use #{self.class.name}.new(:wait_time => #{options[:wait_time]})\n(called from #{caller.map{|c|"\n"+c}})"
+        options = {:timeout => options}
+        if config.warn_deprecated
+          Kernel.warn_with_caller "DEPRECATION WARNING: #{self.class.name}.new takes an options hash - passing a number is deprecated. Please use #{self.class.name}.new(:timeout => #{options[:timeout]})"
+        end
+      end
+      options = options_from_config(options, {:timeout => :attach_timeout, :binary_path => :firefox_binary_path, :profile => :firefox_profile, :wait => :wait}, [:attach, :goto, :wait_time])
+      if options[:wait_time]
+        if config.warn_deprecated
+          Kernel.warn_with_caller "DEPRECATION WARNING: the :wait_time option for #{self.class.name}.new has been renamed to :timeout for consistency. Please use #{self.class.name}.new(:timeout => #{options[:wait_time]})"
+        end
+        options[:timeout] = options[:wait_time]
       end
-      options=handle_options(options, {:wait_time => 20}, [:attach, :goto, :binary_path])
       if options[:binary_path]
         @binary_path=options[:binary_path]
       end
@@ -156,7 +168,7 @@ module Vapir
         if options[:attach]
           raise Vapir::Exception::NoBrowserException, "cannot attach using #{options[:attach].inspect} - could not connect to Firefox with JSSH"
         else
-          launch_browser
+          launch_browser(options)
           # if we just launched a the browser process, attach to the window
           # that opened when we did that. 
           # but if options[:attach] is explicitly given as false (not nil), 
@@ -166,7 +178,7 @@ module Vapir
             options[:attach]=[:title, //]
           end
         end
-        ::Waiter.try_for(options[:wait_time], :exception => Vapir::Exception::NoBrowserException.new("Could not connect to the JSSH socket on the browser after #{options[:wait_time]} seconds. Either Firefox did not start or JSSH is not installed and listening.")) do
+        ::Waiter.try_for(options[:timeout], :exception => Vapir::Exception::NoBrowserException.new("Could not connect to the JSSH socket on the browser after #{options[:timeout]} seconds. Either Firefox did not start or JSSH is not installed and listening.")) do
           begin
             jssh_socket(:reset_if_dead => true).assert_socket
             true
@@ -177,6 +189,12 @@ module Vapir
       end
       @browser_jssh_objects = jssh_socket.object('{}').store_rand_object_key(@@firewatir_jssh_objects) # this is an object that holds stuff for this browser 
       
+      @pid = begin
+        self.pid
+      rescue NotImplementedError
+        nil
+      end
+      
       if options[:attach]
         attach(*options[:attach])
       else
@@ -187,16 +205,9 @@ module Vapir
       if options[:goto]
         goto(options[:goto])
       end
+      wait if options[:wait]
     end
     
-#    def self.firefox_is_running?
-      # TODO/FIX: implement!
-#      true
-#    end
-#    def firefox_is_running?
-#      self.class.firefox_is_running?
-#    end
-
     def mozilla_window_class_name
       'MozillaUIWindowClass'
     end
@@ -207,7 +218,7 @@ module Vapir
     
     def exists?
       # jssh_socket may be nil if the window has closed 
-      jssh_socket && browser_window_object && jssh_socket.object('getWindows()').to_js_array.include(browser_window_object)
+      jssh_socket && browser_window_object && self.class.browser_window_objects.include?(browser_window_object)
     end
     
     # Launches firebox browser
@@ -216,22 +227,15 @@ module Vapir
     def launch_browser(options = {})
       ff_options = []
       if(options[:profile])
-        ff_options << ['-no-remote', '-P', options[:profile]]
+        ff_options += ['-no-remote', '-P', options[:profile]]
       end
 
       bin = path_to_bin()
-      @t = Thread.new { system(bin, '-jssh', *ff_options) }
+      @self_launched_browser = true
+      @t = Thread.new { system(bin, '-jssh', *ff_options) } # TODO: launch process in such a way that @pid can be noted 
     end
     private :launch_browser
 
-    # Creates a new instance of Firefox. Loads the URL and return the instance.
-    # Input:
-    #   url - url of the page to be loaded.
-    def self.start(url)
-      new(:goto => url)
-    end
-    
-
     # Loads the given url in the browser. Waits for the page to get loaded.
     def goto(url)
       assert_exists
@@ -239,6 +243,41 @@ module Vapir
       wait
     end
 
+    # Performs a HTTP POST action to an arbitrary URL with the given data. The data are represented 
+    # to this method as a Hash, which is converted to the standard form of &-separated key=value 
+    # strings POST data use. 
+    # 
+    # The data hash should be keyed with strings or symbols (which are converted to strings before 
+    # being sent along), and its values should all be strings. 
+    #
+    # If no post_data_hash is given, the body of the POST is empty. 
+    def post_to(url, post_data_hash={})
+      require 'cgi'
+      raise ArgumentError, "post_data_hash must be a Hash!" unless post_data_hash.is_a?(Hash)
+      dataString = post_data_hash.map do |(key, val)|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "post_data_hash keys must be strings or symbols; got key #{key.inspect} in hash #{post_data_hash.inspect}"
+        end
+        unless val.is_a?(String)
+          raise ArgumentError, "post_data_hash values must all be string;s got value #{val.inspect} in hash #{post_data_hash.inspect}"
+        end
+        CGI.escape(key.to_s)+'='+CGI.escape(val)
+      end.join("&")
+      stringStream = jssh_socket.Components.classes["@mozilla.org/io/string-input-stream;1"].createInstance(jssh_socket.Components.interfaces.nsIStringInputStream)
+      if stringStream.to_hash.key?('data')
+        stringStream.data=dataString
+      else
+        stringStream.setData(dataString, dataString.unpack("U*").length)
+      end
+      postData = jssh_socket.Components.classes["@mozilla.org/network/mime-input-stream;1"].createInstance(jssh_socket.Components.interfaces.nsIMIMEInputStream)
+      postData.addHeader("Content-Type", "application/x-www-form-urlencoded")
+      postData.addContentLength = true
+      postData.setData(stringStream)
+
+      browser_object.loadURIWithFlags(url, 0, nil, nil, postData)
+      wait
+    end
+
     # Loads the previous page (if there is any) in the browser. Waits for the page to get loaded.
     def back
       if browser_object.canGoBack
@@ -266,8 +305,6 @@ module Vapir
     end
     
     private
-    # This function creates a new socket at port 9997 and sets the default values for instance and class variables.
-    # Generatesi UnableToStartJSShException if cannot connect to jssh even after 3 tries.
     def set_defaults(no_of_tries = 0)
       @error_checkers = []
     end
@@ -302,16 +339,15 @@ module Vapir
       # Details : http://zenit.senecac.on.ca/wiki/index.php/Mozilla.dev.tech.xul#What_is_an_example_of_addProgressListener.3F
       @browser_jssh_objects[:listener_object]={}
       listener_object=@browser_jssh_objects[:listener_object]
-      listener_object[:QueryInterface]=jssh_socket.object(
-        "function(aIID)
-         { if(aIID.equals(Components.interfaces.nsIWebProgressListener) || aIID.equals(Components.interfaces.nsISupportsWeakReference) || aIID.equals(Components.interfaces.nsISupports))
+      listener_object[:QueryInterface]=jssh_socket.function(:aIID) do %Q(
+           if(aIID.equals(Components.interfaces.nsIWebProgressListener) || aIID.equals(Components.interfaces.nsISupportsWeakReference) || aIID.equals(Components.interfaces.nsISupports))
            { return this;
            }
            throw Components.results.NS_NOINTERFACE;
-         }")
-      listener_object[:onStateChange]= jssh_socket.object(
-        "function(aWebProgress, aRequest, aStateFlags, aStatus)
-         { var requests_in_progress=#{@requests_in_progress.ref};
+      )
+      end
+      listener_object[:onStateChange]= jssh_socket.function(:aWebProgress, :aRequest, :aStateFlag, :aStatus) do %Q(
+           var requests_in_progress=#{@requests_in_progress.ref};
            if(aStateFlags & Components.interfaces.nsIWebProgressListener.STATE_STOP)
            { #{@updated_at_epoch_ms.ref}=new Date().getTime();
              #{browser_object.ref}=#{browser_window_object.ref}.getBrowser();
@@ -347,7 +383,8 @@ module Vapir
                --i;
              }
            }*/
-         }")
+      )
+      end
       browser_object.addProgressListener(listener_object)
     end
 
@@ -363,22 +400,36 @@ module Vapir
     end
 
     public
-    #   Closes the window.
+    # Closes the browser window.
+    #
+    # This will also quit the browser (see #quit_browser) only if this instance of Vapir::Firefox launched the browser when 
+    # it was created, AND there are no other windows remaining open. On Windows, closing the last browser window quits
+    # the browser anyway; on other operating systems it does not. 
     def close
       assert_exists
+      # we expect the browser may exit if there are no windows which aren't ourself. except on mac. 
+      expect_exit = !self.class.window_objects.any?{|other_window| other_window != self.browser_window_object } && current_os != :macosx
       begin
         browser_window_object.close
         # TODO/fix timeout; this shouldn't be a hard-coded magic number. 
         ::Waiter.try_for(32, :exception => Exception::WindowFailedToCloseException.new("The browser window did not close")) do
           !exists?
         end
-        @@jssh_socket.assert_socket
+        if expect_exit
+          ::Waiter.try_for(8, :exception => nil) do
+            jssh_socket.assert_socket # this should error, going up past the waiter to the rescue block above 
+            false
+          end
+        else
+          jssh_socket.assert_socket
+        end
       rescue JsshConnectionError # the socket may disconnect when we close the browser, causing the JsshSocket to complain 
-        @@jssh_socket=nil
+        Vapir::Firefox.uninitialize_jssh_socket
+        wait_for_process_exit(@pid)
       end
+        
       @browser_window_object=@browser_object=@document_object=@content_window_object=@body_object=nil
-@launched_browser_process=false #TODO/FIX: check here if we originally launched the browser process
-      if @launched_browser_process && @@jssh_socket
+      if @self_launched_browser && jssh_socket && !self.class.window_objects.any?{ true }
         quit_browser(:force => false)
       end
     end
@@ -388,34 +439,143 @@ module Vapir
       quit_browser(:force => false)
     end
 
-    # quits the browser. 
-    # quit_browser(:force => true) will force the browser to quit. 
-    def quit_browser(options={})
-      options=handle_options(options, :force => false)
-      # from https://developer.mozilla.org/en/How_to_Quit_a_XUL_Application
-      appStartup= jssh_socket.Components.classes['@mozilla.org/toolkit/app-startup;1'].getService(jssh_socket.Components.interfaces.nsIAppStartup)
-      quitSeverity = options[:force] ? jssh_socket.Components.interfaces.nsIAppStartup.eForceQuit : jssh_socket.Components.interfaces.nsIAppStartup.eAttemptQuit
-      begin
-        appStartup.quit(quitSeverity)
-        ::Waiter.try_for(8, :exception => Exception::WindowFailedToCloseException.new("The browser did not quit")) do
-          @@jssh_socket.assert_socket # this should error, going up past the waiter to the rescue block above 
-          false
+    module FirefoxClassAndInstanceMethods
+      # quits the browser. 
+      #
+      # quit_browser(:force => true) will force the browser to quit. 
+      #
+      # if there is no existing connection to JSSH, this will attempt to create one. If that fails, JsshUnableToStart will be raised. 
+      def quit_browser(options={})
+        jssh_socket(:reset_if_dead => true).assert_socket
+        options=handle_options(options, :force => false)
+        
+        pid = @pid || begin
+          self.pid
+        rescue NotImplementedError
+          nil
+        end
+        
+        # from https://developer.mozilla.org/en/How_to_Quit_a_XUL_Application
+        appStartup= jssh_socket.Components.classes['@mozilla.org/toolkit/app-startup;1'].getService(jssh_socket.Components.interfaces.nsIAppStartup)
+        quitSeverity = options[:force] ? jssh_socket.Components.interfaces.nsIAppStartup.eForceQuit : jssh_socket.Components.interfaces.nsIAppStartup.eAttemptQuit
+        begin
+          appStartup.quit(quitSeverity)
+          ::Waiter.try_for(8, :exception => Exception::WindowFailedToCloseException.new("The browser did not quit")) do
+            jssh_socket.assert_socket # this should error, going up past the waiter to the rescue block above 
+            false
+          end
+        rescue JsshConnectionError
+          Vapir::Firefox.uninitialize_jssh_socket
+        end
+        
+        wait_for_process_exit(pid)
+        
+        @browser_window_object=@browser_object=@document_object=@content_window_object=@body_object=nil
+        nil
+      end
+      
+      # returns the pid of the currently-attached Firefox process. 
+      #
+      # This only works on Firefox >= 3.6, on platforms supported (see #current_os), and raises 
+      # NotImplementedError if it can't get the pid. 
+      def pid
+        begin
+          begin
+            ctypes = jssh_socket.Components.utils.import("resource://gre/modules/ctypes.jsm").ctypes
+          rescue JsshJavascriptError
+            raise NotImplementedError, "Firefox 3.6 or greater is required for this method.\n\nOriginal error from firefox: #{$!.class}: #{$!.message}", $!.backtrace
+          end
+          lib, pidfunction, abi = *case current_os
+          when :macosx
+            ["libc.dylib", 'getpid', ctypes.default_abi]
+          when :linux
+            ["libc.so.6", 'getpid', ctypes.default_abi]
+          when :windows
+            ['kernel32', 'GetCurrentProcessId', ctypes.stdcall_abi]
+          else
+            raise NotImplementedError, "don't know how to get pid for #{current_os}"
+          end
+          getpid = ctypes.open(lib).declare(pidfunction, abi, ctypes.int32_t)
+          getpid.call()
         end
-      rescue JsshConnectionError
-        @@jssh_socket=nil
-      end
-      # TODO/FIX: poll to wait for the process itself to finish? the socket closes (which we wait for 
-      # above) before the process itself has exited, so if Firefox.new is called between the socket 
-      # closing and the process exiting, Firefox pops up with:
-      #  Close Firefox
-      #  A copy of Firefox is already open. Only one copy of Firefox can be open at a time.
-      #  [OK]
-      # until that's implemented, just wait for an arbitrary amount of time. (ick)
-      sleep 2
+      end
+      
+      # attempts to determine whether the given process is still running. will raise 
+      # NotImplementedError if it can't determine this. 
+      def process_running?(pid)
+        case current_os
+        when :windows
+          kernel32 = Vapir::Firefox.instance_eval do # define this on the class for reuse 
+            @kernel32 ||= begin
+              require 'ffi'
+              kernel32 = Module.new
+              kernel32.send :extend, FFI::Library
+              kernel32.ffi_lib 'kernel32'
+              kernel32.ffi_convention :stdcall
+              kernel32.attach_function :OpenProcess, [:ulong, :char, :ulong], :pointer
+              kernel32.attach_function :GetExitCodeProcess, [:pointer, :pointer], :char
+              kernel32.const_set('PROCESS_QUERY_INFORMATION', 0x0400)
+              kernel32.const_set('STILL_ACTIVE', 259)
+              kernel32
+            end
+          end
+          process_handle = kernel32.OpenProcess(kernel32::PROCESS_QUERY_INFORMATION, 0, pid)
+          exit_code=FFI::MemoryPointer.new(:ulong)
+          result = kernel32.GetExitCodeProcess(process_handle, exit_code)
+          if result == 0
+            raise "GetExitCodeProcess failed"
+          end
+          return exit_code.get_ulong(0)==kernel32::STILL_ACTIVE
+        when :linux, :macosx
+          `ps -p #{pid}`
+          $? == 0
+        else
+          raise NotImplementedError
+        end
+      end
 
-      @browser_window_object=@browser_object=@document_object=@content_window_object=@body_object=nil
-      nil
+      # waits until the Firefox process with the given pid has exited. 
+      #
+      # if no pid is given, waits the configured amount of time until it is safe to assume
+      # the pfirefox process has exited. 
+      def wait_for_process_exit(pid)
+        if pid
+          ::Waiter.try_for(16, :exception => Exception::WindowFailedToCloseException.new("The browser did not quit")) do
+            !process_running?(pid)
+          end
+        else
+          sleep config.firefox_quit_sleep_time
+        end
+      end
+
+      # returns a symbol representing the platform we're currently running on - currently 
+      # implemented platforms are :windows, :macosx, and :linux. raises NotImplementedError if the 
+      # current platform isn't one of those. 
+      def current_os
+        @current_os ||= begin
+          platform= if RUBY_PLATFORM =~ /java/
+            require 'java'
+            java.lang.System.getProperty("os.name")
+          else
+            RUBY_PLATFORM
+          end
+          case platform
+          when /mswin|windows|mingw32/i
+            :windows
+          when /darwin|mac os/i
+            :macosx
+          when /linux/i
+            :linux
+          else
+            raise NotImplementedError, "Unidentified platform #{platform}"
+          end
+        end
+      end
     end
+    include FirefoxClassAndInstanceMethods
+    extend FirefoxClassAndInstanceMethods
+
+    
 
     #   Used for attaching pop up window to an existing Firefox window, either by url or title.
     #   ff.attach(:url, 'http://www.google.com')
@@ -425,7 +585,7 @@ module Vapir
     #   Instance of newly attached window.
     def attach(how, what)
       @browser_window_object = case how
-      when :jssh_object
+      when :browser_window_object
         what
       else
         find_window(how, what)
@@ -437,24 +597,15 @@ module Vapir
       set_browser_document
       self
     end
-
-    # Class method to return a browser object if a window matches for how
-    # and what. Window can be referenced by url or title.
-    # The second argument can be either a string or a regular expression.
-    # Vapir::Browser.attach(:url, 'http://www.google.com')
-    # Vapir::Browser.attach(:title, 'Google')
-    def self.attach how, what
-      new(:attach => [how, what])
-    end
+    private :attach
 
     # loads up a new window in an existing process
     # Vapir::Browser.attach() with no arguments passed the attach method will create a new window
     # this will only be called one time per instance we're only ever going to run in 1 window
-
     def open_window
       begin
         @browser_window_name="firewatir_window_%.16x"%rand(2**64)
-      end while jssh_socket.value_json("$A(getWindows()).detect(function(win){return win.name==#{@browser_window_name.to_jssh}}) ? true : false")
+      end while self.class.browser_window_objects.any?{|browser_window_object| browser_window_object.name == @browser_window_name }
       watcher=jssh_socket.Components.classes["@mozilla.org/embedcomp/window-watcher;1"].getService(jssh_socket.Components.interfaces.nsIWindowWatcher)
       # nsIWindowWatcher is used to launch new top-level windows. see https://developer.mozilla.org/en/Working_with_windows_in_chrome_code
       
@@ -463,47 +614,44 @@ module Vapir
     end
     private :open_window
 
-    def self.each
-      each_browser_window_object do |win|
-        yield self.attach(:jssh_object, win)
+    class << self
+      def each_browser
+        each_browser_window_object do |win|
+          yield self.attach(:browser_window_object, win)
+        end
       end
-    end
-
-    def self.each_browser_window_object
-      mediator=jssh_socket.Components.classes["@mozilla.org/appshell/window-mediator;1"].getService(jssh_socket.Components.interfaces.nsIWindowMediator)
-      enumerator=mediator.getEnumerator("navigator:browser")
-      while enumerator.hasMoreElements
-        win=enumerator.getNext
-        yield win
+      alias each each_browser
+      def browsers
+        Enumerator.new(self, :each_browser)
       end
-      nil
-    end
-    def self.browser_window_objects
-      window_objects=[]
-      each_browser_window_object do |window_object|
-        window_objects << window_object
+      def each_browser_window_object
+        mediator=jssh_socket.Components.classes["@mozilla.org/appshell/window-mediator;1"].getService(jssh_socket.Components.interfaces.nsIWindowMediator)
+        enumerator=mediator.getEnumerator("navigator:browser")
+        while enumerator.hasMoreElements
+          win=enumerator.getNext
+          yield win
+        end
+        nil
       end
-      window_objects
-    end
-    def self.each_window_object
-      mediator=jssh_socket.Components.classes["@mozilla.org/appshell/window-mediator;1"].getService(jssh_socket.Components.interfaces.nsIWindowMediator)
-      enumerator=mediator.getEnumerator(nil)
-      while enumerator.hasMoreElements
-        win=enumerator.getNext
-        yield win
+      def browser_window_objects
+        Enumerator.new(self, :each_browser_window_object)
       end
-      nil
-    end
-    def self.window_objects
-      window_objects=[]
-      each_window_object do |window_object|
-        window_objects << window_object
+      def each_window_object
+        mediator=jssh_socket.Components.classes["@mozilla.org/appshell/window-mediator;1"].getService(jssh_socket.Components.interfaces.nsIWindowMediator)
+        enumerator=mediator.getEnumerator(nil)
+        while enumerator.hasMoreElements
+          win=enumerator.getNext
+          yield win
+        end
+        nil
+      end
+      def window_objects
+        Enumerator.new(self, :each_window_object)
       end
-      window_objects
     end
     
     # return the window jssh object for the browser window with the given title or url.
-    #   how - :url or :title
+    #   how - :url, :title, or :name
     #   what - string or regexp
     #
     # Start searching windows in reverse order so that we attach/find the latest opened window.
@@ -511,6 +659,7 @@ module Vapir
       orig_how=how
       hows={ :title => proc{|content_window| content_window.title },
              :URL => proc{|content_window| content_window.location.href },
+             :name => proc{|content_window| content_window.name },
            }
       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
@@ -538,6 +687,16 @@ module Vapir
       body_object.textContent
     end
 
+    # the HTTP response status code for the currently loaded document 
+    def response_status_code
+      channel = nil
+      ::Waiter.try_for(8, :exception => nil) do
+        channel=browser.browser_object.docShell.currentDocumentChannel
+        channel.is_a?(JsshObject) && channel.instanceof(browser.jssh_socket.Components.interfaces.nsIHttpChannel) && channel.respond_to?(:responseStatus)
+      end || raise(RuntimeError, "expected currentDocumentChannel to exist and be a nsIHttpChannel but it wasn't; was #{channel.is_a?(JsshObject) ? channel.toString : channel.inspect}")
+      status = channel.responseStatus
+    end
+    
     # Maximize the current browser window.
     def maximize()
       browser_window_object.maximize
@@ -556,11 +715,8 @@ module Vapir
       end
       options={:sleep => false, :last_url => nil, :timeout => 120}.merge(options)
       started=Time.now
-      while browser_object.webProgress.isLoadingDocument
-        sleep 0.1
-        if Time.now - started > options[:timeout]
-          raise "Page Load Timeout"
-        end
+      ::Waiter.try_for(options[:timeout] - (Time.now - started), :exception => "Waiting for the document to finish loading timed out") do
+        browser_object.webProgress.isLoadingDocument==false
       end
 
       # If the redirect is to a download attachment that does not reload this page, this
@@ -569,12 +725,8 @@ module Vapir
       url= document_object.URL
 
       if(url != options[:last_url])
-        # Check for Javascript redirect. As we are connected to Firefox via JSSh. JSSh
-        # doesn't detect any javascript redirects so check it here.
-        # If page redirects to itself that this code will enter in infinite loop.
-        # So we currently don't wait for such a page.
-        # wait variable in JSSh tells if we should wait more for the page to get loaded
-        # or continue. -1 means page is not redirected. Anyother positive values means wait.
+        # check for meta redirects, except for redirects back to the same page (infinite
+        # loop redirects). 
         metas=document_object.getElementsByTagName 'meta'
         wait_time=metas.to_array.map do |meta|
           return_time=true
@@ -601,6 +753,83 @@ module Vapir
       return self
     end
 
+    # saves a screenshot of this browser window to the given filename. 
+    #
+    # the last argument is an optional options hash, taking options:
+    # - :dc => context to capture (stands for device context). default is :page. may be one of: 
+    #   - :page takes a screenshot of the full page, and none of the browser chrome. this is supported cross-platform. 
+    #   - :client takes a screenshot of the client area, which excludes the menu bar and other window trimmings. 
+    #     only supported on windows. 
+    #   - :window takes a screenshot of the full browser window. only supported on windows. 
+    #   - :desktop takes a screenshot of the full desktop. only supported on windows. 
+    # - :format => a valid format. if :dc is :window, the default is 'png' ('jpeg' is also supported); if :dc is anything else, 'bmp' is both the
+    #   default and the only supported format. 
+    def screen_capture(filename, options = {})
+      options = handle_options(options, :format => nil, :dc => :page)
+      
+      if options[:dc] == :page
+        options[:format] ||= 'png'
+        jssh_socket.call_function(:window => content_window_object, :options => options, :filename => File.expand_path(filename)) do
+        %q(
+          // this is adapted from Selenium's method Selenium.prototype.doCaptureEntirePageScreenshot
+          var document = window.document;
+          var document_element = document.documentElement;
+          var width = document_element.scrollWidth;
+          var height = document_element.scrollHeight;
+          var styleWidth = width.toString() + 'px';
+          var styleHeight = height.toString() + 'px';
+
+          var canvas = document.createElementNS('http://www.w3.org/1999/xhtml', 'html:canvas'), grabCanvas=canvas;
+          grabCanvas.style.display = 'none';
+          grabCanvas.width = width;
+          grabCanvas.style.width = styleWidth;
+          grabCanvas.style.maxWidth = styleWidth;
+          grabCanvas.height = height;
+          grabCanvas.style.height = styleHeight;
+          grabCanvas.style.maxHeight = styleHeight;
+          
+          document_element.appendChild(canvas);
+          try
+          {
+            var context = canvas.getContext('2d');
+            context.clearRect(0, 0, width, height);
+            context.save();
+            
+            var prefs=Components.classes['@mozilla.org/preferences-service;1'].getService(Components.interfaces.nsIPrefBranch);
+            var background_color = prefs.getCharPref('browser.display.background_color');
+            
+            context.drawWindow(window, 0, 0, width, height, background_color);
+            context.restore();
+            var dataUrl = canvas.toDataURL("image/" + options['format']);
+            
+            var nsIoService = Components.classes["@mozilla.org/network/io-service;1"].getService(Components.interfaces.nsIIOService);
+            var channel = nsIoService.newChannelFromURI(nsIoService.newURI(dataUrl, null, null));
+            var binaryInputStream = Components.classes["@mozilla.org/binaryinputstream;1"].createInstance(Components.interfaces.nsIBinaryInputStream);
+            binaryInputStream.setInputStream(channel.open());
+            var numBytes = binaryInputStream.available();
+            var bytes = binaryInputStream.readBytes(numBytes);
+
+            var nsFile = Components.classes["@mozilla.org/file/local;1"].createInstance(Components.interfaces.nsILocalFile);
+            nsFile.initWithPath(filename);
+            var writeFlag = 0x02; // write only
+            var createFlag = 0x08; // create
+            var truncateFlag = 0x20; // truncate
+            var fileOutputStream = Components.classes["@mozilla.org/network/file-output-stream;1"].createInstance(Components.interfaces.nsIFileOutputStream);
+            fileOutputStream.init(nsFile, writeFlag | createFlag | truncateFlag, 0664, null);
+            fileOutputStream.write(bytes, numBytes);
+            fileOutputStream.close();
+            document_element.removeChild(canvas);
+          }
+          catch(e)
+          { document_element.removeChild(canvas);
+          }
+        )
+        end
+      else
+        screen_capture_win_window(filename, options)
+      end
+    end
+
     # Add an error checker that gets called on every page load.
     # * checker - a Proc object
     def add_checker(checker)
@@ -640,22 +869,6 @@ module Vapir
       path
     end
 
-    def current_os
-      @current_os ||= begin
-        platform= RUBY_PLATFORM =~ /java/ ? java.lang.System.getProperty("os.name") : RUBY_PLATFORM
-        case platform
-        when /mswin|windows|mingw32/i
-          :windows
-        when /darwin|mac os/i
-          :macosx
-        when /linux/i
-          :linux
-        else
-          raise "Unidentified platform #{platform}"
-        end
-      end
-    end
-
     def path_from_registry
       raise NotImplementedError, "(need to know how to access windows registry on JRuby)" if RUBY_PLATFORM =~ /java/
       require 'win32/registry'