capybara 2.18.0 → 3.38.0

data/lib/capybara/window.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
+
 module Capybara
   ##
-  # The Window class represents a browser window.
+  # The {Window} class represents a browser window.
   #
-  # You can get an instance of the class by calling either of:
+  # You can get an instance of the class by calling any of:
   #
   # * {Capybara::Session#windows}
   # * {Capybara::Session#current_window}
@@ -11,12 +12,12 @@ module Capybara
   # * {Capybara::Session#switch_to_window}
   #
   # Note that some drivers (e.g. Selenium) support getting size of/resizing/closing only
-  #   current window. So if you invoke such method for:
+  # current window. So if you invoke such method for:
   #
-  #   * window that is current, Capybara will make 2 Selenium method invocations
-  #     (get handle of current window + get size/resize/close).
-  #   * window that is not current, Capybara will make 4 Selenium method invocations
-  #     (get handle of current window + switch to given handle + get size/resize/close + switch to original handle)
+  # * window that is current, Capybara will make 2 Selenium method invocations
+  #   (get handle of current window + get size/resize/close).
+  # * window that is not current, Capybara will make 4 Selenium method invocations
+  #   (get handle of current window + switch to given handle + get size/resize/close + switch to original handle)
   #
   class Window
     # @return [String]   a string that uniquely identifies window within session
@@ -56,12 +57,12 @@ module Capybara
     # Close window.
     #
     # If this method was called for window that is current, then after calling this method
-    #   future invocations of other Capybara methods should raise
-    #   `session.driver.no_such_window_error` until another window will be switched to.
+    # future invocations of other Capybara methods should raise
+    # {Capybara::Driver::Base#no_such_window_error session.driver.no_such_window_error} until another window will be switched to.
     #
     # @!macro about_current
     #   If this method was called for window that is not current, then after calling this method
-    #   current window shouldn remain the same as it was before calling this method.
+    #   current window should remain the same as it was before calling this method.
     #
     def close
       @driver.close_window(handle)
@@ -81,8 +82,8 @@ module Capybara
     # Resize window.
     #
     # @macro about_current
-    # @param width [String]  the new window width in pixels
-    # @param height [String]  the new window height in pixels
+    # @param width [Integer]  the new window width in pixels
+    # @param height [Integer]  the new window height in pixels
     #
     def resize_to(width, height)
       wait_for_stable_size { @driver.resize_window_to(handle, width, height) }
@@ -92,7 +93,7 @@ module Capybara
     # Maximize window.
     #
     # If a particular driver (e.g. headless driver) doesn't have concept of maximizing it
-    #   may not support this method.
+    # may not support this method.
     #
     # @macro about_current
     #
@@ -100,41 +101,42 @@ module Capybara
       wait_for_stable_size { @driver.maximize_window(handle) }
     end
 
+    ##
+    # Fullscreen window.
+    #
+    # If a particular driver doesn't have concept of fullscreen it may not support this method.
+    #
+    # @macro about_current
+    #
+    def fullscreen
+      @driver.fullscreen_window(handle)
+    end
+
     def eql?(other)
-      other.kind_of?(self.class) && @session == other.session && @handle == other.handle
+      other.is_a?(self.class) && @session == other.session && @handle == other.handle
     end
     alias_method :==, :eql?
 
     def hash
-      @session.hash ^ @handle.hash
+      [@session, @handle].hash
     end
 
     def inspect
       "#<Window @handle=#{@handle.inspect}>"
     end
 
-    private
+  private
 
-    def wait_for_stable_size(seconds=session.config.default_max_wait_time)
+    def wait_for_stable_size(seconds = session.config.default_max_wait_time)
       res = yield if block_given?
-      prev_size = size
-      start_time = Capybara::Helpers.monotonic_time
-      begin
-        sleep 0.05
-        cur_size = size
-        return res if cur_size == prev_size
-        prev_size = cur_size
-      end while (Capybara::Helpers.monotonic_time - start_time) < seconds
-      #TODO raise error in 3.0
-      #raise Capybara::WindowError, "Window size not stable."
-      warn "Window size not stable in #{seconds} seconds.  This will raise an exception in a future version of Capybara"
-      return res
-    end
-
-    def raise_unless_current(what)
-      unless current?
-        raise Capybara::WindowError, "#{what} not current window is not possible."
+      timer = Capybara::Helpers.timer(expire_in: seconds)
+      loop do
+        prev_size = size
+        sleep 0.025
+        return res if prev_size == size
+        break if timer.expired?
       end
+      raise Capybara::WindowError, "Window size not stable within #{seconds} seconds."
     end
   end
 end

data/lib/capybara.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
+
 require 'timeout'
 require 'nokogiri'
 require 'xpath'
 require 'forwardable'
 require 'capybara/config'
+require 'capybara/registration_container'
 
 module Capybara
   class CapybaraError < StandardError; end
@@ -21,7 +23,6 @@ module Capybara
   class WindowError < CapybaraError; end
   class ReadOnlyElementError < CapybaraError; end
 
-
   class << self
     extend Forwardable
 
@@ -38,6 +39,8 @@ module Capybara
     #   See {Capybara.configure}
     # @!method javascript_driver
     #   See {Capybara.configure}
+    # @!method use_html5_parsing
+    #   See {Capybara.configure}
     Config::OPTIONS.each do |method|
       def_delegators :config, method, "#{method}="
     end
@@ -51,8 +54,6 @@ module Capybara
     #   See {Capybara.configure}
     # @!method always_include_port
     #   See {Capybara.configure}
-    # @!method wait_on_first_by_default
-    #   See {Capybara.configure}
     SessionConfig::OPTIONS.each do |method|
       def_delegators :config, method, "#{method}="
     end
@@ -66,35 +67,52 @@ module Capybara
     #       config.app_host   = 'http://www.google.com'
     #     end
     #
-    # === Configurable options
-    #
-    # [app_host = String/nil]             The default host to use when giving a relative URL to visit, must be a valid URL e.g. http://www.example.com
-    # [always_include_port = Boolean]     Whether the Rack server's port should automatically be inserted into every visited URL unless another port is explicitly specified (Default: false)
-    # [asset_host = String]               Where dynamic assets are hosted - will be prepended to relative asset locations if present (Default: nil)
-    # [run_server = Boolean]              Whether to start a Rack server for the given Rack app (Default: true)
-    # [raise_server_errors = Boolean]     Should errors raised in the server be raised in the tests? (Default: true)
-    # [server_errors = Array\<Class\>]    Error classes that should be raised in the tests if they are raised in the server and Capybara.raise_server_errors is true (Default: [StandardError])
-    # [default_selector = :css/:xpath]    Methods which take a selector use the given type by default (Default: :css)
-    # [default_max_wait_time = Numeric]   The maximum number of seconds to wait for asynchronous processes to finish (Default: 2)
-    # [ignore_hidden_elements = Boolean]  Whether to ignore hidden elements on the page (Default: true)
-    # [automatic_reload = Boolean]        Whether to automatically reload elements as Capybara is waiting (Default: true)
-    # [save_path = String]  Where to put pages saved through save_(page|screenshot), save_and_open_(page|screenshot) (Default: Dir.pwd)
-    # [wait_on_first_by_default = Boolean]   Whether Node#first defaults to Capybara waiting behavior for at least 1 element to match (Default: false)
-    # [automatic_label_click = Boolean]   Whether Node#choose, Node#check, Node#uncheck will attempt to click the associated label element if the checkbox/radio button are non-visible (Default: false)
-    # [enable_aria_label = Boolean]  Whether fields, links, and buttons will match against aria-label attribute (Default: false)
-    # [reuse_server = Boolean]  Reuse the server thread between multiple sessions using the same app object (Default: true)
-    # [threadsafe = Boolean]  Whether sessions can be configured individually (Default: false)
-    # [server = Symbol]  The name of the registered server to use when running the app under test (Default: :webrick)
-    #
-    # === DSL Options
-    #
-    # when using capybara/dsl, the following options are also available:
-    #
-    # [default_driver = Symbol]           The name of the driver to use by default. (Default: :rack_test)
-    # [javascript_driver = Symbol]        The name of a driver to use for JavaScript enabled tests. (Default: :selenium)
+    # #### Configurable options
+    #
+    # - **use_html5_parsing** (Boolean = `false`) - When Nokogiri >= 1.12.0 or `nokogumbo` is installed, whether HTML5 parsing will be used for HTML strings.
+    # - **always_include_port** (Boolean = `false`) - Whether the Rack server's port should automatically be inserted into every visited URL
+    #   unless another port is explicitly specified.
+    # - **app_host** (String, `nil`) - The default host to use when giving a relative URL to visit, must be a valid URL e.g. `http://www.example.com`.
+    # - **asset_host** (String = `nil`) - Where dynamic assets are hosted - will be prepended to relative asset locations if present.
+    # - **automatic_label_click** (Boolean = `false`) - Whether {Capybara::Node::Element#choose Element#choose}, {Capybara::Node::Element#check Element#check},
+    #   {Capybara::Node::Element#uncheck Element#uncheck} will attempt to click the associated `<label>` element if the checkbox/radio button are non-visible.
+    # - **automatic_reload** (Boolean = `true`) - Whether to automatically reload elements as Capybara is waiting.
+    # - **default_max_wait_time** (Numeric = `2`) - The maximum number of seconds to wait for asynchronous processes to finish.
+    # - **default_normalize_ws** (Boolean = `false`) - Whether text predicates and matchers use normalize whitespace behavior.
+    # - **default_retry_interval** (Numeric = `0.01`) - The number of seconds to delay the next check in asynchronous processes.
+    # - **default_selector** (`:css`, `:xpath` = `:css`) - Methods which take a selector use the given type by default. See also {Capybara::Selector}.
+    # - **default_set_options** (Hash = `{}`) - The default options passed to {Capybara::Node::Element#set Element#set}.
+    # - **enable_aria_label** (Boolean = `false`) - Whether fields, links, and buttons will match against `aria-label` attribute.
+    # - **enable_aria_role** (Boolean = `false`) - Selectors will check for relevant aria role (currently only `button`).
+    # - **exact** (Boolean = `false`) - Whether locators are matched exactly or with substrings. Only affects selector conditions
+    #   written using the `XPath#is` method.
+    # - **exact_text** (Boolean = `false`) - Whether the text matchers and `:text` filter match exactly or on substrings.
+    # - **ignore_hidden_elements** (Boolean = `true`) - Whether to ignore hidden elements on the page.
+    # - **match** (`:one`, `:first`, `:prefer_exact`, `:smart` = `:smart`) - The matching strategy to find nodes.
+    # - **predicates_wait** (Boolean = `true`) - Whether Capybara's predicate matchers use waiting behavior by default.
+    # - **raise_server_errors** (Boolean = `true`) - Should errors raised in the server be raised in the tests?
+    # - **reuse_server** (Boolean = `true`) - Whether to reuse the server thread between multiple sessions using the same app object.
+    # - **run_server** (Boolean = `true`) - Whether to start a Rack server for the given Rack app.
+    # - **save_path** (String = `Dir.pwd`) - Where to put pages saved through {Capybara::Session#save_page save_page}, {Capybara::Session#save_screenshot save_screenshot},
+    #   {Capybara::Session#save_and_open_page save_and_open_page}, or {Capybara::Session#save_and_open_screenshot save_and_open_screenshot}.
+    # - **server** (Symbol = `:default` (which uses puma)) - The name of the registered server to use when running the app under test.
+    # - **server_port** (Integer) - The port Capybara will run the application server on, if not specified a random port will be used.
+    # - **server_host** (String = "127.0.0.1") - The IP address Capybara will bind the application server to. If the test application is to be accessed from an external host, you will want to change this to "0.0.0.0" or to a more specific IP address that your test client can reach.
+    # - **server_errors** (Array\<Class> = `[Exception]`) - Error classes that should be raised in the tests if they are raised in the server
+    #   and {configure raise_server_errors} is `true`.
+    # - **test_id** (Symbol, String, `nil` = `nil`) - Optional attribute to match locator against with built-in selectors along with id.
+    # - **threadsafe** (Boolean = `false`) - Whether sessions can be configured individually.
+    # - **w3c_click_offset** (Boolean = 'true') - Whether click offsets should be from element center (true) or top left (false)
+    #
+    # #### DSL Options
+    #
+    # When using `capybara/dsl`, the following options are also available:
+    #
+    # - **default_driver** (Symbol = `:rack_test`) - The name of the driver to use by default.
+    # - **javascript_driver** (Symbol = `:selenium`) - The name of a driver to use for JavaScript enabled tests.
     #
     def configure
-      yield ConfigureDeprecator.new(config)
+      yield config
     end
 
     ##
@@ -111,7 +129,7 @@ module Capybara
     # @yieldreturn [Capybara::Driver::Base]   A Capybara driver instance
     #
     def register_driver(name, &block)
-      drivers[name] = block
+      drivers.send(:register, name, block)
     end
 
     ##
@@ -128,10 +146,9 @@ module Capybara
     # @yieldparam [<Rack>] app                The rack application that this server will contain.
     # @yieldparam port                        The port number the server should listen on
     # @yieldparam host                        The host/ip to bind to
-    # @yieldreturn [Capybara::Driver::Base]   A Capybara driver instance
     #
     def register_server(name, &block)
-      servers[name.to_sym] = block
+      servers.send(:register, name.to_sym, block)
     end
 
     ##
@@ -162,8 +179,8 @@ module Capybara
     # @param [Symbol] name    The name of the selector to add
     # @yield                  A block executed in the context of the new {Capybara::Selector}
     #
-    def add_selector(name, &block)
-      Capybara::Selector.add(name, &block)
+    def add_selector(name, **options, &block)
+      Capybara::Selector.add(name, **options, &block)
     end
 
     ##
@@ -173,7 +190,7 @@ module Capybara
     # button style (a class) might look like this
     #
     #     Capybara.modify_selector(:button) do
-    #       filter (:style, valid_values: [:primary, :secondary]) { |node, style| node[:class].split.include? "btn-#{style}" }
+    #       filter (:btn_style, valid_values: [:primary, :secondary]) { |node, style| node[:class].split.include? "btn-#{style}" }
     #     end
     #
     #
@@ -185,30 +202,26 @@ module Capybara
     end
 
     def drivers
-      @drivers ||= {}
+      @drivers ||= RegistrationContainer.new
     end
 
     def servers
-      @servers ||= {}
+      @servers ||= RegistrationContainer.new
     end
 
-    ##
-    #
     # Wraps the given string, which should contain an HTML document or fragment
     # in a {Capybara::Node::Simple} which exposes all {Capybara::Node::Matchers},
     # {Capybara::Node::Finders} and {Capybara::Node::DocumentMatchers}. This allows you to query
     # any string containing HTML in the exact same way you would query the current document in a Capybara
     # session.
     #
-    # Example: A single element
-    #
+    # @example A single element
     #     node = Capybara.string('<a href="foo">bar</a>')
     #     anchor = node.first('a')
     #     anchor[:href] #=> 'foo'
     #     anchor.text #=> 'bar'
     #
-    # Example: Multiple elements
-    #
+    # @example Multiple elements
     #     node = Capybara.string <<-HTML
     #       <ul>
     #         <li id="home">Home</li>
@@ -238,7 +251,7 @@ module Capybara
     # @param [Integer] port              The port to run the application on
     #
     def run_default_server(app, port)
-      servers[:webrick].call(app, port, server_host)
+      servers[:puma].call(app, port, server_host)
     end
 
     ##
@@ -296,12 +309,12 @@ module Capybara
 
     ##
     #
-    # The current Capybara::Session based on what is set as Capybara.app and Capybara.current_driver
+    # The current {Capybara::Session} based on what is set as {app} and {current_driver}.
     #
     # @return [Capybara::Session]     The currently used session
     #
     def current_session
-      session_pool["#{current_driver}:#{session_name}:#{app.object_id}"] ||= Capybara::Session.new(current_driver, app)
+      specified_session || session_pool["#{current_driver}:#{session_name}:#{app.object_id}"]
     end
 
     ##
@@ -310,7 +323,7 @@ module Capybara
     # as cookies.
     #
     def reset_sessions!
-      #reset in reverse so sessions that started servers are reset last
+      # reset in reverse so sessions that started servers are reset last
       session_pool.reverse_each { |_mode, session| session.reset! }
     end
     alias_method :reset!, :reset_sessions!
@@ -339,22 +352,31 @@ module Capybara
 
     ##
     #
-    # Yield a block using a specific session name.
+    # Yield a block using a specific session name or {Capybara::Session} instance.
     #
-    def using_session(name)
+    def using_session(name_or_session, &block)
+      previous_session = current_session
       previous_session_info = {
+        specified_session: specified_session,
         session_name: session_name,
         current_driver: current_driver,
         app: app
       }
-      self.session_name = name
-      yield
-    ensure
-      self.session_name = previous_session_info[:session_name]
-      if threadsafe
-        self.current_driver = previous_session_info[:current_driver]
-        self.app = previous_session_info[:app]
+      self.specified_session = self.session_name = nil
+      if name_or_session.is_a? Capybara::Session
+        self.specified_session = name_or_session
+      else
+        self.session_name = name_or_session
+      end
+
+      if block.arity.zero?
+        yield
+      else
+        yield current_session, previous_session
       end
+    ensure
+      self.session_name, self.specified_session = previous_session_info.values_at(:session_name, :specified_session)
+      self.current_driver, self.app = previous_session_info.values_at(:current_driver, :app) if threadsafe
     end
 
     ##
@@ -364,10 +386,22 @@ module Capybara
     # @param [String] html              The raw html
     # @return [Nokogiri::HTML::Document]      HTML document
     #
-    def HTML(html)
-      Nokogiri::HTML(html).tap do |document|
+    def HTML(html) # rubocop:disable Naming/MethodName
+      # Nokogiri >= 1.12.0 or Nokogumbo installed and allowed for use
+      html_parser, using_html5 = if defined?(Nokogiri::HTML5) && Capybara.use_html5_parsing
+        [Nokogiri::HTML5, true]
+      else
+        [defined?(Nokogiri::HTML4) ? Nokogiri::HTML4 : Nokogiri::HTML, false]
+      end
+
+      html_parser.parse(html).tap do |document|
+        document.xpath('//template').each do |template|
+          # template elements content is not part of the document
+          template.inner_html = ''
+        end
         document.xpath('//textarea').each do |textarea|
-          textarea['_capybara_raw_value'] = textarea.content.sub(/\A\n/,'')
+          # The Nokogiri HTML5 parser already returns spec compliant contents
+          textarea['_capybara_raw_value'] = using_html5 ? textarea.content : textarea.content.delete_prefix("\n")
         end
       end
     end
@@ -376,18 +410,32 @@ module Capybara
       config.session_options
     end
 
-    def included(base)
-      base.send(:include, Capybara::DSL)
-      warn "`include Capybara` is deprecated. Please use `include Capybara::DSL` instead."
-    end
-
   private
+
     def config
       @config ||= Capybara::Config.new
     end
 
     def session_pool
-      @session_pool ||= {}
+      @session_pool ||= Hash.new do |hash, name|
+        hash[name] = Capybara::Session.new(current_driver, app)
+      end
+    end
+
+    def specified_session
+      if threadsafe
+        Thread.current['capybara_specified_session']
+      else
+        @specified_session ||= nil
+      end
+    end
+
+    def specified_session=(session)
+      if threadsafe
+        Thread.current['capybara_specified_session'] = session
+      else
+        @specified_session = session
+      end
     end
   end
 
@@ -415,7 +463,8 @@ module Capybara
   require 'capybara/queries/match_query'
   require 'capybara/queries/ancestor_query'
   require 'capybara/queries/sibling_query'
-  require 'capybara/query'
+  require 'capybara/queries/style_query'
+  require 'capybara/queries/active_element_query'
 
   require 'capybara/node/finders'
   require 'capybara/node/matchers'
@@ -433,25 +482,14 @@ module Capybara
   require 'capybara/rack_test/node'
   require 'capybara/rack_test/form'
   require 'capybara/rack_test/browser'
-  require 'capybara/rack_test/css_handlers.rb'
+  require 'capybara/rack_test/css_handlers'
 
   require 'capybara/selenium/node'
   require 'capybara/selenium/driver'
 end
 
-Capybara.register_server :default do |app, port, _host|
-  Capybara.run_default_server(app, port)
-end
-
-Capybara.register_server :webrick do |app, port, host, options={}|
-  require 'rack/handler/webrick'
-  Rack::Handler::WEBrick.run(app, {Host: host, Port: port, AccessLog: [], Logger: WEBrick::Log::new(nil, 0)}.merge(options))
-end
-
-Capybara.register_server :puma do |app, port, host, options={}|
-  require 'rack/handler/puma'
-  Rack::Handler::Puma.run(app, {Host: host, Port: port, Threads: "0:4", workers: 0, daemon: false}.merge(options))
-end
+require 'capybara/registrations/servers'
+require 'capybara/registrations/drivers'
 
 Capybara.configure do |config|
   config.always_include_port = false
@@ -459,36 +497,24 @@ Capybara.configure do |config|
   config.server = :default
   config.default_selector = :css
   config.default_max_wait_time = 2
+  config.default_retry_interval = 0.01
   config.ignore_hidden_elements = true
-  config.default_host = "http://www.example.com"
+  config.default_host = 'http://www.example.com'
   config.automatic_reload = true
   config.match = :smart
   config.exact = false
   config.exact_text = false
   config.raise_server_errors = true
-  config.server_errors = [StandardError]
+  config.server_errors = [Exception]
   config.visible_text_only = false
-  config.wait_on_first_by_default = false
   config.automatic_label_click = false
   config.enable_aria_label = false
+  config.enable_aria_role = false
   config.reuse_server = true
-end
-
-Capybara.register_driver :rack_test do |app|
-  Capybara::RackTest::Driver.new(app)
-end
-
-Capybara.register_driver :selenium do |app|
-  Capybara::Selenium::Driver.new(app)
-end
-
-Capybara.register_driver :selenium_chrome do |app|
-  Capybara::Selenium::Driver.new(app, :browser => :chrome)
-end
-
-Capybara.register_driver :selenium_chrome_headless do |app|
-  browser_options = ::Selenium::WebDriver::Chrome::Options.new()
-  browser_options.args << '--headless'
-  browser_options.args << '--disable-gpu'
-  Capybara::Selenium::Driver.new(app, browser: :chrome, options: browser_options)
+  config.default_set_options = {}
+  config.test_id = nil
+  config.predicates_wait = true
+  config.default_normalize_ws = false
+  config.use_html5_parsing = false
+  config.w3c_click_offset = true
 end