capybara 3.16.1 → 3.33.0

data/lib/capybara/selenium/patches/action_pauser.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActionPauser
+  def initialize(mouse, keyboard)
+    super
+    @devices[:pauser] = Pauser.new
+  end
+
+  def pause(duration)
+    @actions << [:pauser, :pause, [duration]]
+    self
+  end
+
+  class Pauser
+    def pause(duration)
+      sleep duration
+    end
+  end
+
+  private_constant :Pauser
+end
+
+if defined?(::Selenium::WebDriver::VERSION) && (::Selenium::WebDriver::VERSION.to_f < 4) &&
+   defined?(::Selenium::WebDriver::ActionBuilder)
+  ::Selenium::WebDriver::ActionBuilder.prepend(ActionPauser)
+end

data/lib/capybara/selenium/patches/atoms.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CapybaraAtoms
+private
+
+  def read_atom(function)
+    @atoms ||= Hash.new do |hash, key|
+      hash[key] = begin
+                    File.read(File.expand_path("../../atoms/#{key}.min.js", __FILE__))
+                  rescue Errno::ENOENT
+                    super
+                  end
+    end
+    @atoms[function]
+  end
+end
+
+::Selenium::WebDriver::Remote::Bridge.prepend CapybaraAtoms unless ENV['DISABLE_CAPYBARA_SELENIUM_OPTIMIZATIONS']

data/lib/capybara/selenium/patches/is_displayed.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Selenium
+    module IsDisplayed
+      def commands(command)
+        case command
+        when :is_element_displayed
+          [:get, 'session/:session_id/element/:id/displayed']
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/capybara/selenium/patches/logs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Selenium
+    module ChromeLogs
+      LOG_MSG = <<~MSG
+        Chromedriver 75+ defaults to W3C mode. Please upgrade to chromedriver >= \
+        75.0.3770.90 if you need to access logs while in W3C compliant mode.
+      MSG
+
+      COMMANDS = {
+        get_available_log_types: [:get, 'session/:session_id/se/log/types'],
+        get_log: [:post, 'session/:session_id/se/log'],
+        get_log_legacy: [:post, 'session/:session_id/log']
+      }.freeze
+
+      def commands(command)
+        COMMANDS[command] || super
+      end
+
+      def available_log_types
+        types = execute :get_available_log_types
+        Array(types).map(&:to_sym)
+      rescue ::Selenium::WebDriver::Error::UnknownCommandError
+        raise NotImplementedError, LOG_MSG
+      end
+
+      def log(type)
+        data = begin
+                 execute :get_log, {}, type: type.to_s
+               rescue ::Selenium::WebDriver::Error::UnknownCommandError
+                 execute :get_log_legacy, {}, type: type.to_s
+               end
+
+        Array(data).map do |l|
+          ::Selenium::WebDriver::LogEntry.new l.fetch('level', 'UNKNOWN'), l.fetch('timestamp'), l.fetch('message')
+        rescue KeyError
+          next
+        end
+      rescue ::Selenium::WebDriver::Error::UnknownCommandError
+        raise NotImplementedError, LOG_MSG
+      end
+    end
+  end
+end

data/lib/capybara/server.rb

@@ -24,7 +24,9 @@ module Capybara
                    host: Capybara.server_host,
                    reportable_errors: Capybara.server_errors,
                    extra_middleware: [])
-      warn 'Positional arguments, other than the application, to Server#new are deprecated, please use keyword arguments' unless deprecated_options.empty?
+      unless deprecated_options.empty?
+        warn 'Positional arguments, other than the application, to Server#new are deprecated, please use keyword arguments'
+      end
       @app = app
       @extra_middleware = extra_middleware
       @server_thread = nil # suppress warnings
@@ -61,7 +63,7 @@ module Capybara
     def wait_for_pending_requests
       timer = Capybara::Helpers.timer(expire_in: 60)
       while pending_requests?
-        raise 'Requests did not finish in 60 seconds' if timer.expired?
+        raise "Requests did not finish in 60 seconds: #{middleware.pending_requests}" if timer.expired?
 
         sleep 0.01
       end
@@ -86,6 +88,10 @@ module Capybara
       self
     end
 
+    def base_url
+      "http#{'s' if using_ssl?}://#{host}:#{port}"
+    end
+
   private
 
     def middleware
@@ -102,7 +108,17 @@ module Capybara
 
     def find_available_port(host)
       server = TCPServer.new(host, 0)
-      server.addr[1]
+      port = server.addr[1]
+      server.close
+
+      # Workaround issue where some platforms (mac, ???) when passed a host
+      # of '0.0.0.0' will return a port that is only available on one of the
+      # ip addresses that resolves to, but the next binding to that port requires
+      # that port to be available on all ips
+      server = TCPServer.new(host, port)
+      port
+    rescue Errno::EADDRINUSE
+      retry
     ensure
       server&.close
     end

data/lib/capybara/server/animation_disabler.rb

@@ -36,7 +36,7 @@ module Capybara
       attr_reader :disable_markup
 
       def html_content?
-        !!(@headers['Content-Type'] =~ /html/)
+        /html/.match?(@headers['Content-Type'])
       end
 
       def insert_disable(html)
@@ -46,7 +46,7 @@ module Capybara
       DISABLE_MARKUP_TEMPLATE = <<~HTML
         <script defer>(typeof jQuery !== 'undefined') && (jQuery.fx.off = true);</script>
         <style>
-           %<selector>s {
+           %<selector>s, %<selector>s::before, %<selector>s::after {
              transition: none !important;
              animation-duration: 0s !important;
              animation-delay: 0s !important;

data/lib/capybara/server/checker.rb

@@ -25,11 +25,15 @@ module Capybara
     private
 
       def http_request(&block)
-        Net::HTTP.start(@host, @port, read_timeout: 2, &block)
+        make_request(read_timeout: 2, &block)
       end
 
       def https_request(&block)
-        Net::HTTP.start(@host, @port, ssl_options, &block)
+        make_request(**ssl_options, &block)
+      end
+
+      def make_request(**options, &block)
+        Net::HTTP.start(@host, @port, options.merge(max_retries: 0), &block)
       end
 
       def ssl_options

data/lib/capybara/server/middleware.rb

@@ -4,19 +4,25 @@ module Capybara
   class Server
     class Middleware
       class Counter
-        attr_reader :value
-
         def initialize
-          @value = 0
+          @value = []
           @mutex = Mutex.new
         end
 
-        def increment
-          @mutex.synchronize { @value += 1 }
+        def increment(uri)
+          @mutex.synchronize { @value.push(uri) }
+        end
+
+        def decrement(uri)
+          @mutex.synchronize { @value.delete_at(@value.index(uri) || @value.length) }
         end
 
-        def decrement
-          @mutex.synchronize { @value -= 1 }
+        def positive?
+          @mutex.synchronize { @value.length.positive? }
+        end
+
+        def value
+          @mutex.synchronize { @value.dup }
         end
       end
 
@@ -31,8 +37,12 @@ module Capybara
         @server_errors = server_errors
       end
 
+      def pending_requests
+        @counter.value
+      end
+
       def pending_requests?
-        @counter.value.positive?
+        @counter.positive?
       end
 
       def clear_error
@@ -43,14 +53,14 @@ module Capybara
         if env['PATH_INFO'] == '/__identify__'
           [200, {}, [@app.object_id.to_s]]
         else
-          @counter.increment
+          @counter.increment(env['REQUEST_URI'])
           begin
             @extended_app.call(env)
-          rescue *@server_errors => err
-            @error ||= err
-            raise err
+          rescue *@server_errors => e
+            @error ||= e
+            raise e
           ensure
-            @counter.decrement
+            @counter.decrement(env['REQUEST_URI'])
           end
         end
       end

data/lib/capybara/session.rb

@@ -6,7 +6,7 @@ require 'addressable/uri'
 module Capybara
   ##
   #
-  # The Session class represents a single user's interaction with the system. The Session can use
+  # The {Session} class represents a single user's interaction with the system. The {Session} can use
   # any of the underlying drivers. A session can be initialized manually like this:
   #
   #     session = Capybara::Session.new(:culerity, MyRackApp)
@@ -17,23 +17,23 @@ 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
+  # When {Capybara.configure threadsafe} is `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}
+  # 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 delegates a number of methods to a Capybara::Document, representing
+  # The {Session} provides a number of methods for controlling the navigation of the page, such as {#visit},
+  # {#current_path}, and so on. It also delegates a number of methods to a {Capybara::Document}, representing
   # the current HTML document. This allows interaction:
   #
   #     session.fill_in('q', with: 'Capybara')
   #     session.click_button('Search')
   #     expect(session).to have_content('Capybara')
   #
-  # When using capybara/dsl, the Session is initialized automatically for you.
+  # When using `capybara/dsl`, the {Session} is initialized automatically for you.
   #
   class Session
     include Capybara::SessionMatchers
@@ -75,9 +75,11 @@ 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)
+      if app && !app.respond_to?(:call)
+        raise TypeError, 'The second parameter to Session::new should be a rack app if passed.'
+      end
 
-      @@instance_created = true
+      @@instance_created = true # rubocop:disable Style/ClassVars
       @mode = mode
       @app = app
       if block_given?
@@ -88,15 +90,15 @@ module Capybara
       @server = if config.run_server && @app && driver.needs_server?
         server_options = { port: config.server_port, host: config.server_host, reportable_errors: config.server_errors }
         server_options[:extra_middleware] = [Capybara::Server::AnimationDisabler] if config.disable_animation
-        Capybara::Server.new(@app, server_options).boot
+        Capybara::Server.new(@app, **server_options).boot
       end
       @touched = false
     end
 
     def driver
       @driver ||= begin
-        unless Capybara.drivers.key?(mode)
-          other_drivers = Capybara.drivers.keys.map(&:inspect)
+        unless Capybara.drivers[mode]
+          other_drivers = Capybara.drivers.names.map(&:inspect)
           raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}"
         end
         driver = Capybara.drivers[mode].call(app)
@@ -107,21 +109,21 @@ module Capybara
 
     ##
     #
-    # Reset the session (i.e. remove cookies and navigate to blank page)
+    # Reset the session (i.e. remove cookies and navigate to blank page).
     #
     # This method does not:
     #
-    #   * accept modal dialogs if they are present (Selenium driver now does, others may not)
-    #   * clear browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc.
-    #   * modify state of the driver/underlying browser in any other way
+    # * accept modal dialogs if they are present (Selenium driver now does, others may not)
+    # * clear browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc.
+    # * modify state of the driver/underlying browser in any other way
     #
     # as doing so will result in performance downsides and it's not needed to do everything from the list above for most apps.
     #
     # If you want to do anything from the list above on a general basis you can:
     #
-    #   * write RSpec/Cucumber/etc. after hook
-    #   * monkeypatch this method
-    #   * use Ruby's `prepend` method
+    # * write RSpec/Cucumber/etc. after hook
+    # * monkeypatch this method
+    # * use Ruby's `prepend` method
     #
     def reset!
       if @touched
@@ -136,19 +138,18 @@ module Capybara
 
     ##
     #
-    # Disconnect from the current driver.  A new driver will be instantiated on the next interaction
-    #
+    # Disconnect from the current driver. A new driver will be instantiated on the next interaction.
     #
     def quit
       @driver.quit if @driver.respond_to? :quit
-      @driver = nil
+      @document = @driver = nil
       @touched = false
       @server&.reset_error!
     end
 
     ##
     #
-    # Raise errors encountered in the server
+    # Raise errors encountered in the server.
     #
     def raise_server_error!
       return unless @server&.error
@@ -168,9 +169,9 @@ module Capybara
 
     ##
     #
-    # Returns a hash of response headers. Not supported by all drivers (e.g. Selenium)
+    # Returns a hash of response headers. Not supported by all drivers (e.g. Selenium).
     #
-    # @return [Hash{String => String}] A hash of response headers.
+    # @return [Hash<String, String>] A hash of response headers.
     #
     def response_headers
       driver.response_headers
@@ -178,7 +179,7 @@ module Capybara
 
     ##
     #
-    # Returns the current HTTP status code as an Integer. Not supported by all drivers (e.g. Selenium)
+    # Returns the current HTTP status code as an integer. Not supported by all drivers (e.g. Selenium).
     #
     # @return [Integer] Current HTTP status code
     #
@@ -191,7 +192,7 @@ module Capybara
     # @return [String] A snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).
     #
     def html
-      driver.html
+      driver.html || ''
     end
     alias_method :body, :html
     alias_method :source, :html
@@ -238,13 +239,13 @@ module Capybara
     #
     # For drivers which can run against an external application, such as the selenium driver
     # giving an absolute URL will navigate to that page. This allows testing applications
-    # running on remote servers. For these drivers, setting {Capybara.app_host} will make the
+    # running on remote servers. For these drivers, setting {Capybara.configure app_host} will make the
     # remote server the default. For example:
     #
     #     Capybara.app_host = 'http://google.com'
     #     session.visit('/') # visits the google homepage
     #
-    # If {Capybara.always_include_port} is set to true and this session is running against
+    # If {Capybara.configure always_include_port} is set to `true` and this session is running against
     # a rack application, then the port that the rack application is running on will automatically
     # be inserted into the URL. Supposing the app is running on port `4567`, doing something like:
     #
@@ -279,7 +280,7 @@ module Capybara
 
     ##
     #
-    # Refresh the page
+    # Refresh the page.
     #
     def refresh
       raise_server_error!
@@ -304,8 +305,8 @@ module Capybara
 
     ##
     #
-    # Executes the given block within the context of a node. `within` takes the
-    # same options as `find`, as well as a block. For the duration of the
+    # Executes the given block within the context of a node. {#within} takes the
+    # same options as {Capybara::Node::Finders#find #find}, as well as a block. For the duration of the
     # block, any command to Capybara will be handled as though it were scoped
     # to the given element.
     #
@@ -313,18 +314,18 @@ module Capybara
     #       fill_in('Street', with: '12 Main Street')
     #     end
     #
-    # Just as with `find`, if multiple elements match the selector given to
-    # `within`, an error will be raised, and just as with `find`, this
+    # Just as with `#find`, if multiple elements match the selector given to
+    # {#within}, an error will be raised, and just as with `#find`, this
     # behaviour can be controlled through the `:match` and `:exact` options.
     #
     # It is possible to omit the first parameter, in that case, the selector is
-    # assumed to be of the type set in Capybara.default_selector.
+    # assumed to be of the type set in {Capybara.configure default_selector}.
     #
     #     within('div#delivery-address') do
     #       fill_in('Street', with: '12 Main Street')
     #     end
     #
-    # Note that a lot of uses of `within` can be replaced more succinctly with
+    # 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')
@@ -337,8 +338,8 @@ module Capybara
     #
     # @raise  [Capybara::ElementNotFound]      If the scope can't be found before time expires
     #
-    def within(*args)
-      new_scope = args.first.respond_to?(:to_capybara_node) ? args.first.to_capybara_node : find(*args)
+    def within(*args, **kw_args)
+      new_scope = args.first.respond_to?(:to_capybara_node) ? args.first.to_capybara_node : find(*args, **kw_args)
       begin
         scopes.push(new_scope)
         yield if block_given?
@@ -370,18 +371,18 @@ module Capybara
 
     ##
     #
-    # Switch to the given frame
+    # Switch to the given 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.
+    # {#within_frame} is preferred over this method and should be used when possible.
     # May not be supported by all drivers.
     #
     # @overload switch_to_frame(element)
-    #   @param [Capybara::Node::Element]  iframe/frame element to switch to
-    # @overload switch_to_frame(:parent)
-    #   Switch to the parent frame
-    # @overload switch_to_frame(:top)
-    #   Switch to the top level document
+    #   @param [Capybara::Node::Element] element    iframe/frame element to switch to
+    # @overload switch_to_frame(location)
+    #   @param [Symbol] location relative location of the frame to switch to
+    #                            * :parent - the parent frame
+    #                            * :top - the top level document
     #
     def switch_to_frame(frame)
       case frame
@@ -422,8 +423,8 @@ module Capybara
     #   @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)
-      switch_to_frame(_find_frame(*args))
+    def within_frame(*args, **kw_args)
+      switch_to_frame(_find_frame(*args, **kw_args))
       begin
         yield if block_given?
       ensure
@@ -452,8 +453,8 @@ module Capybara
     end
 
     ##
-    # Open new window.
-    # Current window doesn't change as the result of this call.
+    # Open a new window.
+    # The current window doesn't change as the result of this call.
     # It should be switched to explicitly.
     #
     # @return [Capybara::Window]   window that has been opened
@@ -469,9 +470,11 @@ module Capybara
     end
 
     ##
+    # Switch to the given window.
+    #
     # @overload switch_to_window(&block)
     #   Switches to the first window for which given block returns a value other than false or nil.
-    #   If window that matches block can't be found, the window will be switched back and `WindowError` will be raised.
+    #   If window that matches block can't be found, the window will be switched back and {Capybara::WindowError} will be raised.
     #   @example
     #     window = switch_to_window { title == 'Page title' }
     #   @raise [Capybara::WindowError]     if no window matches given block
@@ -480,8 +483,8 @@ module Capybara
     #   @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` or
-    #   `within_frame` 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, &window_locator)
@@ -493,7 +496,7 @@ module Capybara
                                     '`within` or `within_frame` blocks.'
       end
 
-      _switch_to_window(window, options, &window_locator)
+      _switch_to_window(window, **options, &window_locator)
     end
 
     ##
@@ -501,20 +504,20 @@ module Capybara
     #
     # 1. Switches to the given window (it can be located by window instance/lambda/string).
     # 2. Executes the given block (within window located at previous step).
-    # 3. Switches back (this step will be invoked even if exception will happen at second step)
+    # 3. Switches back (this step will be invoked even if an exception occurs at the second step).
     #
     # @overload within_window(window) { do_something }
-    #   @param window [Capybara::Window]       instance of `Capybara::Window` class
+    #   @param window [Capybara::Window]       instance of {Capybara::Window} class
     #     that will be switched to
     #   @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
+    #   @param lambda [Proc]                  First window for which lambda
     #     returns a value other than false or nil will be switched to.
     #   @example
     #     within_window(->{ page.title == 'Page title' }) { click_button 'Submit' }
     #   @raise [Capybara::WindowError]         if no window matching lambda was found
     #
-    # @raise [Capybara::ScopeError]        if this method is invoked inside `within_frame` method
+    # @raise [Capybara::ScopeError]        if this method is invoked inside {#within_frame} method
     # @return                              value returned by the block
     #
     def within_window(window_or_proc)
@@ -527,7 +530,7 @@ module Capybara
         when Proc
           _switch_to_window { window_or_proc.call }
         else
-          raise ArgumentError('`#within_window` requires a `Capybara::Window` instance or a lambda')
+          raise ArgumentError, '`#within_window` requires a `Capybara::Window` instance or a lambda'
         end
 
         begin
@@ -544,11 +547,11 @@ module Capybara
     # Get the window that has been opened by the passed block.
     # It will wait for it to be opened (in the same way as other Capybara methods wait).
     # It's better to use this method than `windows.last`
-    # {https://dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html#h_note_10 as order of windows isn't defined in some drivers}
+    # {https://dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html#h_note_10 as order of windows isn't defined in some drivers}.
     #
     # @overload window_opened_by(**options, &block)
     #   @param options [Hash]
-    #   @option options [Numeric] :wait (Capybara.default_max_wait_time) maximum wait time
+    #   @option options [Numeric] :wait  maximum wait time. Defaults to {Capybara.configure default_max_wait_time}
     #   @return [Capybara::Window]       the window that has been opened within a block
     #   @raise [Capybara::WindowError]   if block passed to window hasn't opened window
     #     or opened more than one window
@@ -570,11 +573,11 @@ module Capybara
     ##
     #
     # Execute the given script, not returning a result. This is useful for scripts that return
-    # complex objects, such as jQuery statements. +execute_script+ should be used over
-    # +evaluate_script+ whenever possible.
+    # complex objects, such as jQuery statements. {#execute_script} should be used over
+    # {#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
+    # @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, *args)
       @touched = true
@@ -584,10 +587,11 @@ module Capybara
     ##
     #
     # Evaluate the given JavaScript and return the result. Be careful when using this with
-    # scripts that return complex objects, such as jQuery statements. +execute_script+ might
+    # scripts that return complex objects, such as jQuery statements. {#execute_script} might
     # be a better alternative.
     #
     # @param  [String] script   A string of JavaScript to evaluate
+    # @param           args     Optional arguments that will be passed to the script
     # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
     #
     def evaluate_script(script, *args)
@@ -601,6 +605,7 @@ module Capybara
     # 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
+    # @param           args     Optional arguments that will be passed to the script
     # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
     #
     def evaluate_async_script(script, *args)
@@ -614,17 +619,17 @@ module Capybara
     # Execute the block, accepting a alert.
     #
     # @!macro modal_params
-    #   Expects a block whose actions will trigger the display modal to appear
+    #   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.
+    #     @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  Maximum time to wait for the modal to appear after executing the block. Defaults to {Capybara.configure default_max_wait_time}.
     #     @yield Block whose actions will trigger the system modal
     #   @overload $0(**options, &blk)
-    #     @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time to wait for the modal to appear after executing the block.
+    #     @option options [Numeric] :wait  Maximum time to wait for the modal to appear after executing the block. Defaults to {Capybara.configure default_max_wait_time}.
     #     @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
@@ -676,12 +681,12 @@ module Capybara
 
     ##
     #
-    # Save a snapshot of the page. If `Capybara.asset_host` is set it will inject `base` tag
-    #   pointing to `asset_host`.
+    # Save a snapshot of the page. If {Capybara.configure asset_host} is set it will inject `base` tag
+    # pointing to {Capybara.configure asset_host}.
     #
-    # 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`
+    # If invoked without arguments it will save file to {Capybara.configure save_path}
+    # and file will be given randomly generated filename. If invoked with a relative path
+    # the path will be relative to {Capybara.configure save_path}.
     #
     # @param [String] path  the path to where it should be saved
     # @return [String]      the path to which the file was saved
@@ -696,9 +701,9 @@ 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_path`
-    #   and file will be given randomly generated filename. If invoked with a relative path
-    #   the path will be relative to `Capybara.save_path`
+    # If invoked without arguments it will save file to {Capybara.configure save_path}
+    # and file will be given randomly generated filename. If invoked with a relative path
+    # the path will be relative to {Capybara.configure save_path}.
     #
     # @param [String] path  the path to where it should be saved
     #
@@ -710,32 +715,30 @@ module Capybara
     #
     # Save a screenshot of page.
     #
-    # 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`
+    # If invoked without arguments it will save file to {Capybara.configure save_path}
+    # and file will be given randomly generated filename. If invoked with a relative path
+    # the path will be relative to {Capybara.configure save_path}.
     #
     # @param [String] path    the path to where it should be saved
     # @param [Hash] options   a customizable set of options
     # @return [String]        the path to which the file was saved
     def save_screenshot(path = nil, **options)
-      prepare_path(path, 'png').tap { |p_path| driver.save_screenshot(p_path, options) }
+      prepare_path(path, 'png').tap { |p_path| driver.save_screenshot(p_path, **options) }
     end
 
     ##
     #
     # Save a screenshot of the page and open it for inspection.
     #
-    # 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`
+    # If invoked without arguments it will save file to {Capybara.configure save_path}
+    # and file will be given randomly generated filename. If invoked with a relative path
+    # the path will be relative to {Capybara.configure save_path}.
     #
     # @param [String] path    the path to where it should be saved
     # @param [Hash] options   a customizable set of options
     #
     def save_and_open_screenshot(path = nil, **options)
-      # rubocop:disable Lint/Debugger
-      save_screenshot(path, options).tap { |s_path| open_file(s_path) }
-      # rubocop:enable Lint/Debugger
+      save_screenshot(path, **options).tap { |s_path| open_file(s_path) } # rubocop:disable Lint/Debugger
     end
 
     def document
@@ -743,15 +746,32 @@ module Capybara
     end
 
     NODE_METHODS.each do |method|
-      define_method method do |*args, &block|
-        @touched = true
-        current_scope.send(method, *args, &block)
+      if RUBY_VERSION >= '2.7'
+        class_eval <<~METHOD, __FILE__, __LINE__ + 1
+          def #{method}(...)
+            @touched = true
+            current_scope.#{method}(...)
+          end
+        METHOD
+      else
+        define_method method do |*args, &block|
+          @touched = true
+          current_scope.send(method, *args, &block)
+        end
       end
     end
 
     DOCUMENT_METHODS.each do |method|
-      define_method method do |*args, &block|
-        document.send(method, *args, &block)
+      if RUBY_VERSION >= '2.7'
+        class_eval <<~METHOD, __FILE__, __LINE__ + 1
+          def #{method}(...)
+            document.#{method}(...)
+          end
+        METHOD
+      else
+        define_method method do |*args, &block|
+          document.send(method, *args, &block)
+        end
       end
     end
 
@@ -766,7 +786,7 @@ module Capybara
 
     ##
     #
-    # Yield a block using a specific wait time
+    # Yield a block using a specific maximum wait time.
     #
     def using_wait_time(seconds)
       if Capybara.threadsafe
@@ -784,8 +804,8 @@ module Capybara
 
     ##
     #
-    #  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
+    # Accepts a block to set the configuration options if {Capybara.configure threadsafe} is `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
@@ -805,20 +825,24 @@ module Capybara
       end
     end
 
+    def server_url
+      @server&.base_url
+    end
+
   private
 
-    @@instance_created = false
+    @@instance_created = false # rubocop:disable Style/ClassVars
 
     def driver_args(args)
       args.map { |arg| arg.is_a?(Capybara::Node::Element) ? arg.base : arg }
     end
 
     def accept_modal(type, text_or_options, options, &blk)
-      driver.accept_modal(type, modal_options(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)
+      driver.dismiss_modal(type, **modal_options(text_or_options, **options), &blk)
     end
 
     def modal_options(text = nil, **options)
@@ -862,24 +886,18 @@ module Capybara
       end
     end
 
-    def server_url
-      "http#{'s' if @server.using_ssl?}://#{@server.host}:#{@server.port}" if @server
-    end
-
     def adjust_server_port(uri)
       uri.port ||= @server.port if @server && config.always_include_port
     end
 
-    def _find_frame(*args)
-      return find(:frame) if args.length.zero?
-
+    def _find_frame(*args, **kw_args)
       case args[0]
       when Capybara::Node::Element
         args[0]
-      when String, Hash
-        find(:frame, *args)
+      when String, nil
+        find(:frame, *args, **kw_args)
       when Symbol
-        find(*args)
+        find(*args, **kw_args)
       when Integer
         idx = args[0]
         all(:frame, minimum: idx + 1)[idx]