capybara 2.5.0 → 2.18.0

data/lib/capybara/session.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 require 'capybara/session/matchers'
+require 'addressable/uri'
 
 module Capybara
 
@@ -15,11 +17,19 @@ module Capybara
   #     session = Capybara::Session.new(:culerity)
   #     session.visit('http://www.google.com')
   #
+  # When Capybara.threadsafe == true the sessions options will be initially set to the
+  # current values of the global options and a configuration block can be passed to the session initializer.
+  # For available options see {Capybara::SessionConfig::OPTIONS}
+  #
+  #     session = Capybara::Session.new(:driver, MyRackApp) do |config|
+  #       config.app_host = "http://my_host.dev"
+  #     end
+  #
   # Session provides a number of methods for controlling the navigation of the page, such as +visit+,
   # +current_path, and so on. It also delegate a number of methods to a Capybara::Document, representing
   # the current HTML document. This allows interaction:
   #
-  #     session.fill_in('q', :with => 'Capybara')
+  #     session.fill_in('q', with: 'Capybara')
   #     session.click_button('Search')
   #     expect(session).to have_content('Capybara')
   #
@@ -39,6 +49,7 @@ module Capybara
       :has_no_table?, :has_table?, :unselect, :has_select?, :has_no_select?,
       :has_selector?, :has_no_selector?, :click_on, :has_no_checked_field?,
       :has_no_unchecked_field?, :query, :assert_selector, :assert_no_selector,
+      :assert_all_of_selectors, :assert_none_of_selectors,
       :refute_selector, :assert_text, :assert_no_text
     ]
     # @api private
@@ -47,9 +58,9 @@ module Capybara
     ]
     SESSION_METHODS = [
       :body, :html, :source, :current_url, :current_host, :current_path,
-      :execute_script, :evaluate_script, :visit, :go_back, :go_forward,
-      :within, :within_fieldset, :within_table, :within_frame, :current_window,
-      :windows, :open_new_window, :switch_to_window, :within_window, :window_opened_by,
+      :execute_script, :evaluate_script, :visit, :refresh, :go_back, :go_forward,
+      :within, :within_element, :within_fieldset, :within_table, :within_frame, :switch_to_frame,
+      :current_window, :windows, :open_new_window, :switch_to_window, :within_window, :window_opened_by,
       :save_page, :save_and_open_page, :save_screenshot,
       :save_and_open_screenshot, :reset_session!, :response_headers,
       :status_code, :current_scope,
@@ -65,10 +76,16 @@ module Capybara
     attr_accessor :synchronized
 
     def initialize(mode, app=nil)
+      raise TypeError, "The second parameter to Session::new should be a rack app if passed." if app && !app.respond_to?(:call)
+      @@instance_created = true
       @mode = mode
       @app = app
-      if Capybara.run_server and @app and driver.needs_server?
-        @server = Capybara::Server.new(@app).boot
+      if block_given?
+        raise "A configuration block is only accepted when Capybara.threadsafe == true" unless Capybara.threadsafe
+        yield config if block_given?
+      end
+      if config.run_server and @app and driver.needs_server?
+        @server = Capybara::Server.new(@app, config.server_port, config.server_host, config.server_errors).boot
       else
         @server = nil
       end
@@ -81,7 +98,9 @@ module Capybara
           other_drivers = Capybara.drivers.keys.map { |key| key.inspect }
           raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}"
         end
-        Capybara.drivers[mode].call(app)
+        driver = Capybara.drivers[mode].call(app)
+        driver.session = self if driver.respond_to?(:session=)
+        driver
       end
     end
 
@@ -106,9 +125,9 @@ module Capybara
     def reset!
       if @touched
         driver.reset!
-        assert_no_selector :xpath, "/html/body/*" if driver.browser_initialized?
         @touched = false
       end
+      @server.wait_for_pending_requests if @server
       raise_server_error!
     end
     alias_method :cleanup!, :reset!
@@ -119,9 +138,19 @@ module Capybara
     # Raise errors encountered in the server
     #
     def raise_server_error!
-      raise @server.error if Capybara.raise_server_errors and @server and @server.error
-    ensure
-      @server.reset_error! if @server
+      if @server and @server.error
+        # Force an explanation for the error being raised as the exception cause
+        begin
+          if config.raise_server_errors
+            raise CapybaraError, "Your application server raised an error - It has been raised in your test code because Capybara.raise_server_errors == true"
+          end
+        rescue CapybaraError
+          #needed to get the cause set correctly in JRuby -- otherwise we could just do raise @server.error
+          raise @server.error, @server.error.message, @server.error.backtrace
+        ensure
+          @server.reset_error!
+        end
+      end
     end
 
     ##
@@ -159,7 +188,15 @@ module Capybara
     # @return [String] Path of the current page, without any domain information
     #
     def current_path
-      path = URI.parse(current_url).path
+      # Addressable parsing is more lenient than URI
+      uri = ::Addressable::URI.parse(current_url)
+
+      # If current_url ends up being nil, won't be able to call .path on a NilClass.
+      return nil if uri.nil?
+
+      # Addressable doesn't support opaque URIs - we want nil here
+      return nil if uri.scheme == "about"
+      path = uri.path
       path if path and not path.empty?
     end
 
@@ -204,32 +241,46 @@ module Capybara
     #
     # Will actually navigate to `http://google.com:4567/test`.
     #
-    # @param [#to_s] url     The URL to navigate to. The parameter will be cast to a String.
+    # @param [#to_s] visit_uri     The URL to navigate to. The parameter will be cast to a String.
     #
-    def visit(url)
+    def visit(visit_uri)
       raise_server_error!
-
-      url = url.to_s
       @touched = true
 
-      url_relative = URI.parse(url).scheme.nil?
+      visit_uri = ::Addressable::URI.parse(visit_uri.to_s)
 
-      if url_relative && Capybara.app_host
-        url = Capybara.app_host + url
-        url_relative = false
+      uri_base = if @server
+        ::Addressable::URI.parse(config.app_host || "http://#{@server.host}:#{@server.port}")
+      else
+        config.app_host && ::Addressable::URI.parse(config.app_host)
       end
 
-      if @server
-        url = "http://#{@server.host}:#{@server.port}" + url if url_relative
+      if uri_base && [nil, 'http', 'https'].include?(visit_uri.scheme)
+        if visit_uri.relative?
+          uri_base.port ||= @server.port if @server && config.always_include_port
+
+          visit_uri_parts = visit_uri.to_hash.delete_if { |k,v| v.nil? }
+
+          # Useful to people deploying to a subdirectory
+          # and/or single page apps where only the url fragment changes
+          visit_uri_parts[:path] = uri_base.path + visit_uri.path
 
-        if Capybara.always_include_port
-          uri = URI.parse(url)
-          uri.port = @server.port if uri.port == uri.default_port
-          url = uri.to_s
+          visit_uri = uri_base.merge(visit_uri_parts)
+        else
+          visit_uri.port ||= @server.port if @server && config.always_include_port
         end
       end
 
-      driver.visit(url)
+      driver.visit(visit_uri.to_s)
+    end
+
+    ##
+    #
+    # Refresh the page
+    #
+    def refresh
+      raise_server_error!
+      driver.refresh
     end
 
     ##
@@ -255,8 +306,8 @@ module Capybara
     # block, any command to Capybara will be handled as though it were scoped
     # to the given element.
     #
-    #     within(:xpath, '//div[@id="delivery-address"]') do
-    #       fill_in('Street', :with => '12 Main Street')
+    #     within(:xpath, './/div[@id="delivery-address"]') do
+    #       fill_in('Street', with: '12 Main Street')
     #     end
     #
     # Just as with `find`, if multiple elements match the selector given to
@@ -267,13 +318,13 @@ module Capybara
     # assumed to be of the type set in Capybara.default_selector.
     #
     #     within('div#delivery-address') do
-    #       fill_in('Street', :with => '12 Main Street')
+    #       fill_in('Street', with: '12 Main Street')
     #     end
     #
     # Note that a lot of uses of `within` can be replaced more succinctly with
     # chaining:
     #
-    #     find('div#delivery-address').fill_in('Street', :with => '12 Main Street')
+    #     find('div#delivery-address').fill_in('Street', with: '12 Main Street')
     #
     # @overload within(*find_args)
     #   @param (see Capybara::Node::Finders#all)
@@ -292,6 +343,7 @@ module Capybara
         scopes.pop
       end
     end
+    alias_method :within_element, :within
 
     ##
     #
@@ -319,21 +371,77 @@ module Capybara
 
     ##
     #
-    # Execute the given block within the given iframe using given frame name or index.
-    # May be supported by not all drivers. Drivers that support it, may provide additional options.
+    # Switch to the given frame
     #
-    # @overload within_frame(index)
-    #   @param [Integer] index         index of a frame
-    # @overload within_frame(name)
-    #   @param [String] name           name of a frame
+    # If you use this method you are responsible for making sure you switch back to the parent frame when done in the frame changed to.
+    # Capybara::Session#within_frame is preferred over this method and should be used when possible.
+    # May not be supported by all drivers.
     #
-    def within_frame(frame_handle)
-      scopes.push(nil)
-      driver.within_frame(frame_handle) do
-        yield
+    # @overload switch_to_frame(element)
+    #   @param [Capybara::Node::Element]  iframe/frame element to switch to
+    # @overload switch_to_frame(:parent)
+    #   Switch to the parent element
+    # @overload switch_to_frame(:top)
+    #   Switch to the top level document
+    #
+    def switch_to_frame(frame)
+      case frame
+      when Capybara::Node::Element
+        driver.switch_to_frame(frame)
+        scopes.push(:frame)
+      when :parent
+        raise Capybara::ScopeError, "`switch_to_frame(:parent)` cannot be called from inside a descendant frame's "\
+                                    "`within` block." if scopes.last() != :frame
+        scopes.pop
+        driver.switch_to_frame(:parent)
+      when :top
+        idx = scopes.index(:frame)
+        if idx
+          raise Capybara::ScopeError, "`switch_to_frame(:top)` cannot be called from inside a descendant frame's "\
+                                      "`within` block." if scopes.slice(idx..-1).any? {|scope| ![:frame, nil].include?(scope)}
+          scopes.slice!(idx..-1)
+          driver.switch_to_frame(:top)
+        end
+      end
+    end
+
+    ##
+    #
+    # Execute the given block within the given iframe using given frame, frame name/id or index.
+    # May not be supported by all drivers.
+    #
+    # @overload within_frame(element)
+    #   @param [Capybara::Node::Element]  frame element
+    # @overload within_frame([kind = :frame], locator, options = {})
+    #   @param [Symobl] kind      Optional selector type (:css, :xpath, :field, etc.) - Defaults to :frame
+    #   @param [String] locator   The locator for the given selector kind.  For :frame this is the name/id of a frame/iframe element
+    # @overload within_frame(index)
+    #   @param [Integer] index         index of a frame (0 based)
+    def within_frame(*args)
+      frame = _find_frame(*args)
+
+      begin
+        switch_to_frame(frame)
+        begin
+          yield
+        ensure
+          switch_to_frame(:parent)
+        end
+      rescue Capybara::NotSupportedByDriverError
+        # Support older driver frame API for now
+        if driver.respond_to?(:within_frame)
+          begin
+            scopes.push(:frame)
+            driver.within_frame(frame) do
+              yield
+            end
+          ensure
+            scopes.pop
+          end
+        else
+          raise
+        end
       end
-    ensure
-      scopes.pop
     end
 
     ##
@@ -378,51 +486,27 @@ module Capybara
     #   @raise [Capybara::WindowError]     if no window matches given block
     # @overload switch_to_window(window)
     #   @param window [Capybara::Window]   window that should be switched to
-    #   @raise [Capybara::Driver::Base#no_such_window_error] if unexistent (e.g. closed) window was passed
+    #   @raise [Capybara::Driver::Base#no_such_window_error] if nonexistent (e.g. closed) window was passed
     #
     # @return [Capybara::Window]         window that has been switched to
-    # @raise [Capybara::ScopeError]        if this method is invoked inside `within`,
-    #   `within_frame` or `within_window` methods
+    # @raise [Capybara::ScopeError]        if this method is invoked inside `within` or
+    #   `within_frame` methods
     # @raise [ArgumentError]               if both or neither arguments were provided
     #
-    def switch_to_window(window = nil, options= {})
-      if window.is_a? Hash
-        options = window
-        window = nil
-      end
+    def switch_to_window(window = nil, options= {}, &window_locator)
+      options, window = window, nil if window.is_a? Hash
+
       block_given = block_given?
       if window && block_given
         raise ArgumentError, "`switch_to_window` can take either a block or a window, not both"
       elsif !window && !block_given
         raise ArgumentError, "`switch_to_window`: either window or block should be provided"
-      elsif scopes.size > 1
+      elsif !scopes.last.nil?
         raise Capybara::ScopeError, "`switch_to_window` is not supposed to be invoked from "\
-                                    "`within`'s, `within_frame`'s' or `within_window`'s' block."
+                                    "`within` or `within_frame` blocks."
       end
 
-      if window
-        driver.switch_to_window(window.handle)
-        window
-      else
-        wait_time = Capybara::Query.new(options).wait
-        document.synchronize(wait_time, errors: [Capybara::WindowError]) do
-          original_window_handle = driver.current_window_handle
-          begin
-            driver.window_handles.each do |handle|
-              driver.switch_to_window handle
-              if yield
-                return Window.new(self, handle)
-              end
-            end
-          rescue => e
-            driver.switch_to_window(original_window_handle)
-            raise e
-          else
-            driver.switch_to_window(original_window_handle)
-            raise Capybara::WindowError, "Could not find a window matching block/lambda"
-          end
-        end
-      end
+      _switch_to_window(window, options, &window_locator)
     end
 
     ##
@@ -435,7 +519,7 @@ module Capybara
     # @overload within_window(window) { do_something }
     #   @param window [Capybara::Window]       instance of `Capybara::Window` class
     #     that will be switched to
-    #   @raise [driver#no_such_window_error] if unexistent (e.g. closed) window was passed
+    #   @raise [driver#no_such_window_error] if nonexistent (e.g. closed) window was passed
     # @overload within_window(proc_or_lambda) { do_something }
     #   @param lambda [Proc]                  lambda. First window for which lambda
     #     returns a value other than false or nil will be switched to.
@@ -446,30 +530,35 @@ module Capybara
     #   @deprecated                            Pass window or lambda instead
     #   @param [String]                        handle, name, url or title of the window
     #
-    # @raise [Capybara::ScopeError]        if this method is invoked inside `within`,
-    #   `within_frame` or `within_window` methods
+    # @raise [Capybara::ScopeError]        if this method is invoked inside `within_frame` method
     # @return                              value returned by the block
     #
     def within_window(window_or_handle)
       if window_or_handle.instance_of?(Capybara::Window)
         original = current_window
-        switch_to_window(window_or_handle) unless original == window_or_handle
         scopes << nil
         begin
-          yield
+          _switch_to_window(window_or_handle) unless original == window_or_handle
+          begin
+            yield
+          ensure
+            _switch_to_window(original) unless original == window_or_handle
+          end
         ensure
-          @scopes.pop
-          switch_to_window(original) unless original == window_or_handle
+          scopes.pop
         end
       elsif window_or_handle.is_a?(Proc)
         original = current_window
-        switch_to_window { window_or_handle.call }
         scopes << nil
         begin
-          yield
+          _switch_to_window { window_or_handle.call }
+          begin
+            yield
+          ensure
+            _switch_to_window(original)
+          end
         ensure
-          @scopes.pop
-          switch_to_window(original)
+          scopes.pop
         end
       else
         offending_line = caller.first
@@ -480,7 +569,7 @@ module Capybara
           scopes << nil
           driver.within_window(window_or_handle) { yield }
         ensure
-          @scopes.pop
+          scopes.pop
         end
       end
     end
@@ -501,7 +590,7 @@ module Capybara
       old_handles = driver.window_handles
       block.call
 
-      wait_time = Capybara::Query.new(options).wait
+      wait_time = Capybara::Queries::BaseQuery.wait(options, config.default_max_wait_time)
       document.synchronize(wait_time, errors: [Capybara::WindowError]) do
         opened_handles = (driver.window_handles - old_handles)
         if opened_handles.size != 1
@@ -519,10 +608,16 @@ module Capybara
     # +evaluate_script+ whenever possible.
     #
     # @param [String] script   A string of JavaScript to execute
+    # @param args  Optional arguments that will be passed to the script.  Driver support for this is optional and types of objects supported may differ between drivers
     #
-    def execute_script(script)
+    def execute_script(script, *args)
       @touched = true
-      driver.execute_script(script)
+      if args.empty?
+        driver.execute_script(script)
+      else
+        raise Capybara::NotSupportedByDriverError, "The current driver does not support execute_script arguments" if driver.method(:execute_script).arity == 1
+        driver.execute_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ?  arg.base : arg} )
+      end
     end
 
     ##
@@ -534,9 +629,33 @@ module Capybara
     # @param  [String] script   A string of JavaScript to evaluate
     # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
     #
-    def evaluate_script(script)
+    def evaluate_script(script, *args)
       @touched = true
-      driver.evaluate_script(script)
+      result = if args.empty?
+        driver.evaluate_script(script)
+      else
+        raise Capybara::NotSupportedByDriverError, "The current driver does not support evaluate_script arguments" if driver.method(:evaluate_script).arity == 1
+        driver.evaluate_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ?  arg.base : arg} )
+      end
+      element_script_result(result)
+    end
+
+    ##
+    #
+    # Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.
+    #
+    # @param  [String] script   A string of JavaScript to evaluate
+    # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
+    #
+    def evaluate_async_script(script, *args)
+      @touched = true
+      result = if args.empty?
+        driver.evaluate_async_script(script)
+      else
+        raise Capybara::NotSupportedByDriverError, "The current driver does not support evaluate_async_script arguments" if driver.method(:evaluate_async_script).arity == 1
+        driver.evaluate_async_script(script, *args.map { |arg| arg.is_a?(Capybara::Node::Element) ?  arg.base : arg} )
+      end
+      element_script_result(result)
     end
 
     ##
@@ -544,21 +663,24 @@ module Capybara
     # Execute the block, accepting a alert.
     #
     # @!macro modal_params
+    #   Expects a block whose actions will trigger the display modal to appear
+    #   @example
+    #     $0 do
+    #       click_link('link that triggers appearance of system modal')
+    #     end
     #   @overload $0(text, options = {}, &blk)
     #     @param text [String, Regexp]  Text or regex to match against the text in the modal.  If not provided any modal is matched
+    #     @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time to wait for the modal to appear after executing the block.
+    #     @yield Block whose actions will trigger the system modal
     #   @overload $0(options = {}, &blk)
-    #   @option options [Numeric] :wait  How long to wait for the modal to appear after executing the block.
+    #     @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time to wait for the modal to appear after executing the block.
+    #     @yield Block whose actions will trigger the system modal
     #   @return [String]  the message shown in the modal
     #   @raise [Capybara::ModalNotFound]  if modal dialog hasn't been found
     #
+    #
     def accept_alert(text_or_options=nil, options={}, &blk)
-      if text_or_options.is_a? Hash
-        options=text_or_options
-      else
-        options[:text]=text_or_options
-      end
-
-      driver.accept_modal(:alert, options, &blk)
+      accept_modal(:alert, text_or_options, options, &blk)
     end
 
     ##
@@ -568,13 +690,7 @@ module Capybara
     # @macro modal_params
     #
     def accept_confirm(text_or_options=nil, options={}, &blk)
-      if text_or_options.is_a? Hash
-        options=text_or_options
-      else
-        options[:text]=text_or_options
-      end
-
-      driver.accept_modal(:confirm, options, &blk)
+      accept_modal(:confirm, text_or_options, options, &blk)
     end
 
     ##
@@ -584,13 +700,7 @@ module Capybara
     # @macro modal_params
     #
     def dismiss_confirm(text_or_options=nil, options={}, &blk)
-      if text_or_options.is_a? Hash
-        options=text_or_options
-      else
-        options[:text]=text_or_options
-      end
-
-      driver.dismiss_modal(:confirm, options, &blk)
+      dismiss_modal(:confirm, text_or_options, options, &blk)
     end
 
     ##
@@ -601,13 +711,7 @@ module Capybara
     # @option options [String] :with   Response to provide to the prompt
     #
     def accept_prompt(text_or_options=nil, options={}, &blk)
-      if text_or_options.is_a? Hash
-        options=text_or_options
-      else
-        options[:text]=text_or_options
-      end
-
-      driver.accept_modal(:prompt, options, &blk)
+      accept_modal(:prompt, text_or_options, options, &blk)
     end
 
     ##
@@ -617,13 +721,7 @@ module Capybara
     # @macro modal_params
     #
     def dismiss_prompt(text_or_options=nil, options={}, &blk)
-      if text_or_options.is_a? Hash
-        options=text_or_options
-      else
-        options[:text]=text_or_options
-      end
-
-      driver.dismiss_modal(:prompt, options, &blk)
+      dismiss_modal(:prompt, text_or_options, options, &blk)
     end
 
     ##
@@ -631,15 +729,18 @@ module Capybara
     # Save a snapshot of the page. If `Capybara.asset_host` is set it will inject `base` tag
     #   pointing to `asset_host`.
     #
-    # If invoked without arguments it will save file to `Capybara.save_and_open_page_path`
-    #   and file will be given randomly generated filename.
+    # If invoked without arguments it will save file to `Capybara.save_path`
+    #   and file will be given randomly generated filename. If invoked with a relative path
+    #   the path will be relative to `Capybara.save_path`, which is different from
+    #   the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
+    #   relative to Dir.pwd
     #
     # @param [String] path  the path to where it should be saved
     # @return [String]      the path to which the file was saved
     #
     def save_page(path = nil)
       path = prepare_path(path, 'html')
-      File.write(path, Capybara::Helpers.inject_asset_host(body), mode: 'wb')
+      File.write(path, Capybara::Helpers.inject_asset_host(body, config.asset_host), mode: 'wb')
       path
     end
 
@@ -647,8 +748,11 @@ module Capybara
     #
     # Save a snapshot of the page and open it in a browser for inspection.
     #
-    # If invoked without arguments it will save file to `Capybara.save_and_open_page_path`
-    #   and file will be given randomly generated filename.
+    # If invoked without arguments it will save file to `Capybara.save_path`
+    #   and file will be given randomly generated filename. If invoked with a relative path
+    #   the path will be relative to `Capybara.save_path`, which is different from
+    #   the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
+    #   relative to Dir.pwd
     #
     # @param [String] path  the path to where it should be saved
     #
@@ -661,8 +765,11 @@ module Capybara
     #
     # Save a screenshot of page.
     #
-    # If invoked without `path` argument it will save file to `Capybara.save_and_open_page_path`
-    #   and file will be given randomly generated filename.
+    # If invoked without arguments it will save file to `Capybara.save_path`
+    #   and file will be given randomly generated filename. If invoked with a relative path
+    #   the path will be relative to `Capybara.save_path`, which is different from
+    #   the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
+    #   relative to Dir.pwd
     #
     # @param [String] path    the path to where it should be saved
     # @param [Hash] options   a customizable set of options
@@ -677,8 +784,11 @@ module Capybara
     #
     # Save a screenshot of the page and open it for inspection.
     #
-    # If invoked without `path` argument it will save file to `Capybara.save_and_open_page_path`
-    #   and file will be given randomly generated filename.
+    # If invoked without arguments it will save file to `Capybara.save_path`
+    #   and file will be given randomly generated filename. If invoked with a relative path
+    #   the path will be relative to `Capybara.save_path`, which is different from
+    #   the previous behavior with `Capybara.save_and_open_page_path` where the relative path was
+    #   relative to Dir.pwd
     #
     # @param [String] path    the path to where it should be saved
     # @param [Hash] options   a customizable set of options
@@ -710,11 +820,70 @@ module Capybara
     end
 
     def current_scope
-      scopes.last || document
+      scope = scopes.last
+      scope = document if [nil, :frame].include? scope
+      scope
     end
 
+    ##
+    #
+    # Yield a block using a specific wait time
+    #
+    def using_wait_time(seconds)
+      if Capybara.threadsafe
+        begin
+          previous_wait_time = config.default_max_wait_time
+          config.default_max_wait_time = seconds
+          yield
+        ensure
+          config.default_max_wait_time = previous_wait_time
+        end
+      else
+        Capybara.using_wait_time(seconds) { yield }
+      end
+    end
+
+    ##
+    #
+    #  Accepts a block to set the configuration options if Capybara.threadsafe == true. Note that some options only have an effect
+    #  if set at initialization time, so look at the configuration block that can be passed to the initializer too
+    #
+    def configure
+      raise "Session configuration is only supported when Capybara.threadsafe == true" unless Capybara.threadsafe
+      yield config
+    end
+
+    def self.instance_created?
+      @@instance_created
+    end
+
+    def config
+      @config ||= if Capybara.threadsafe
+        Capybara.session_options.dup
+      else
+        Capybara::ReadOnlySessionConfig.new(Capybara.session_options)
+      end
+    end
   private
 
+    @@instance_created = false
+
+    def accept_modal(type, text_or_options, options, &blk)
+      driver.accept_modal(type, modal_options(text_or_options, options), &blk)
+    end
+
+    def dismiss_modal(type, text_or_options, options, &blk)
+      driver.dismiss_modal(type, modal_options(text_or_options, options), &blk)
+    end
+
+    def modal_options(text_or_options, options)
+      text_or_options, options = nil, text_or_options if text_or_options.is_a?(Hash)
+      options[:text] ||= text_or_options unless text_or_options.nil?
+      options[:wait] ||= config.default_max_wait_time
+      options
+    end
+
+
     def open_file(path)
       begin
         require "launchy"
@@ -726,19 +895,85 @@ module Capybara
     end
 
     def prepare_path(path, extension)
-      path = default_path(extension) if path.nil?
+      if config.save_path || config.save_and_open_page_path.nil?
+        path = File.expand_path(path || default_fn(extension), config.save_path)
+      else
+        path = File.expand_path(default_fn(extension), config.save_and_open_page_path) if path.nil?
+      end
       FileUtils.mkdir_p(File.dirname(path))
       path
     end
 
-    def default_path(extension)
+    def default_fn(extension)
       timestamp = Time.new.strftime("%Y%m%d%H%M%S")
-      path = "capybara-#{timestamp}#{rand(10**10)}.#{extension}"
-      File.expand_path(path, Capybara.save_and_open_page_path)
+      "capybara-#{timestamp}#{rand(10**10)}.#{extension}"
     end
 
     def scopes
       @scopes ||= [nil]
     end
+
+    def element_script_result(arg)
+      case arg
+      when Array
+        arg.map { |e| element_script_result(e) }
+      when Hash
+        arg.each { |k, v| arg[k] = element_script_result(v) }
+      when Capybara::Driver::Node
+        Capybara::Node::Element.new(self, arg, nil, nil)
+      else
+        arg
+      end
+    end
+
+    def _find_frame(*args)
+      within(document) do  # Previous 2.x versions ignored current scope when finding frames - consider changing in 3.0
+        case args[0]
+        when Capybara::Node::Element
+          args[0]
+        when String, Hash
+          find(:frame, *args)
+        when Symbol
+          find(*args)
+        when Integer
+          idx = args[0]
+          all(:frame, minimum: idx+1)[idx]
+        else
+          raise TypeError
+        end
+      end
+    end
+
+    def _switch_to_window(window = nil, options= {})
+      options, window = window, nil if window.is_a? Hash
+
+      raise Capybara::ScopeError, "Window cannot be switched inside a `within_frame` block" if scopes.include?(:frame)
+      raise Capybara::ScopeError, "Window cannot be switch inside a `within` block" unless scopes.last.nil?
+
+      if window
+        driver.switch_to_window(window.handle)
+        window
+      else
+        wait_time = Capybara::Queries::BaseQuery.wait(options, config.default_max_wait_time)
+        document.synchronize(wait_time, errors: [Capybara::WindowError]) do
+          original_window_handle = driver.current_window_handle
+          begin
+            driver.window_handles.each do |handle|
+              driver.switch_to_window handle
+              if yield
+                return Window.new(self, handle)
+              end
+            end
+          rescue => e
+            driver.switch_to_window(original_window_handle)
+            raise e
+          else
+            driver.switch_to_window(original_window_handle)
+            raise Capybara::WindowError, "Could not find a window matching block/lambda"
+          end
+        end
+      end
+    end
+
   end
 end