capybara 2.15.1 → 3.36.0

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,50 @@ 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 (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_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_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 = 'false') - 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 +127,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 +144,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 +177,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 +188,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 +200,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 +249,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 +307,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 +321,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 +350,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 +384,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 +408,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 +461,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 +480,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
@@ -460,35 +496,22 @@ Capybara.configure do |config|
   config.default_selector = :css
   config.default_max_wait_time = 2
   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 = false
 end

data/spec/basic_node_spec.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
+
 require 'spec_helper'
 
 RSpec.describe Capybara do
+  include Capybara::RSpecMatchers
   describe '.string' do
     let :string do
-      Capybara.string <<-STRING
+      described_class.string <<-STRING
         <html>
           <head>
             <title>simple_node</title>
@@ -45,97 +47,121 @@ RSpec.describe Capybara do
       STRING
     end
 
-    it "allows using matchers" do
+    it 'allows using matchers' do
       expect(string).to have_css('#page')
       expect(string).not_to have_css('#does-not-exist')
     end
 
-    it "allows using custom matchers" do
-      Capybara.add_selector :lifeform do
+    it 'allows using custom matchers' do
+      described_class.add_selector :lifeform do
         xpath { |name| ".//option[contains(.,'#{name}')]" }
       end
-      expect(string).to have_selector(:id, "page")
+      expect(string).to have_selector(:id, 'page')
       expect(string).not_to have_selector(:id, 'does-not-exist')
-      expect(string).to have_selector(:lifeform, "Monkey")
-      expect(string).not_to have_selector(:lifeform, "Gorilla")
+      expect(string).to have_selector(:lifeform, 'Monkey')
+      expect(string).not_to have_selector(:lifeform, 'Gorilla')
     end
 
     it 'allows custom matcher using css' do
-      Capybara.add_selector :section do
+      described_class.add_selector :section do
         css { |css_class| "section .#{css_class}" }
       end
       expect(string).to     have_selector(:section, 'subsection')
       expect(string).not_to have_selector(:section, 'section_8')
     end
 
-    it "allows using matchers with text option" do
+    it 'allows using matchers with text option' do
       expect(string).to have_css('h1', text: 'Totally awesome')
       expect(string).not_to have_css('h1', text: 'Not so awesome')
     end
 
-    it "allows finding only visible nodes" do
+    it 'allows finding only visible nodes' do
       expect(string.all(:css, '#secret', visible: true)).to be_empty
       expect(string.all(:css, '#secret', visible: false).size).to eq(1)
     end
 
-    it "allows finding elements and extracting text from them" do
+    it 'allows finding elements and extracting text from them' do
       expect(string.find('//h1').text).to eq('Totally awesome')
     end
 
-    it "allows finding elements and extracting attributes from them" do
+    it 'allows finding elements and extracting attributes from them' do
       expect(string.find('//h1')[:data]).to eq('fantastic')
     end
 
-    it "allows finding elements and extracting the tag name from them" do
+    it 'allows finding elements and extracting the tag name from them' do
       expect(string.find('//h1').tag_name).to eq('h1')
     end
 
-    it "allows finding elements and extracting the path" do
+    it 'allows finding elements and extracting the path' do
       expect(string.find('//h1').path).to eq('/html/body/div/div[1]/h1')
     end
 
-    it "allows finding elements and extracting the path" do
+    it 'allows finding elements and extracting the value' do
       expect(string.find('//div/input').value).to eq('bar')
       expect(string.find('//select').value).to eq('Capybara')
     end
 
-    it "allows finding elements and checking if they are visible" do
+    it 'allows finding elements and checking if they are visible' do
       expect(string.find('//h1')).to be_visible
-      expect(string.find(:css, "#secret", visible: false)).not_to be_visible
+      expect(string.find(:css, '#secret', visible: false)).not_to be_visible
     end
 
-    it "allows finding elements and checking if they are disabled" do
+    it 'allows finding elements and checking if they are disabled' do
       expect(string.find('//form/input[@name="bleh"]')).to be_disabled
       expect(string.find('//form/input[@name="meh"]')).not_to be_disabled
     end
 
-    describe "#title" do
-      it "returns the page title" do
-        expect(string.title).to eq("simple_node")
+    it 'allows finding siblings' do
+      h1 = string.find(:css, 'h1')
+      expect(h1).to have_sibling(:css, 'p', text: 'Yes it is')
+      expect(h1).not_to have_sibling(:css, 'p', text: 'Jonas Nicklas')
+    end
+
+    it 'allows finding ancestor' do
+      h1 = string.find(:css, 'h1')
+      expect(h1).to have_ancestor(:css, '#content')
+      expect(h1).not_to have_ancestor(:css, '#footer')
+    end
+
+    it 'drops illegal fragments when using gumbo' do
+      skip 'libxml is less strict than Gumbo' unless Nokogiri.respond_to?(:HTML5)
+      described_class.use_html5_parsing = true
+      expect(described_class.string('<td>1</td>')).not_to have_css('td')
+    end
+
+    it 'can disable use of HTML5 parsing' do
+      skip "Test doesn't make sense unlesss HTML5 parsing is loaded (Nokogumbo or Nokogiri >= 1.12.0)" unless Nokogiri.respond_to?(:HTML5)
+      described_class.use_html5_parsing = false
+      expect(described_class.string('<td>1</td>')).to have_css('td')
+    end
+
+    describe '#title' do
+      it 'returns the page title' do
+        expect(string.title).to eq('simple_node')
       end
     end
 
-    describe "#has_title?" do
-      it "returns whether the page has the given title" do
-        expect(string.has_title?('simple_node')).to be_truthy
-        expect(string.has_title?('monkey')).to be_falsey
+    describe '#has_title?' do
+      it 'returns whether the page has the given title' do
+        expect(string.has_title?('simple_node')).to be true
+        expect(string.has_title?('monkey')).to be false
       end
 
-      it "allows regexp matches" do
-        expect(string.has_title?(/s[a-z]+_node/)).to be_truthy
-        expect(string.has_title?(/monkey/)).to be_falsey
+      it 'allows regexp matches' do
+        expect(string.has_title?(/s[a-z]+_node/)).to be true
+        expect(string.has_title?(/monkey/)).to be false
       end
     end
 
     describe '#has_no_title?' do
-      it "returns whether the page does not have the given title" do
-        expect(string.has_no_title?('simple_node')).to be_falsey
-        expect(string.has_no_title?('monkey')).to be_truthy
+      it 'returns whether the page does not have the given title' do
+        expect(string.has_no_title?('simple_node')).to be false
+        expect(string.has_no_title?('monkey')).to be true
       end
 
-      it "allows regexp matches" do
-        expect(string.has_no_title?(/s[a-z]+_node/)).to be_falsey
-        expect(string.has_no_title?(/monkey/)).to be_truthy
+      it 'allows regexp matches' do
+        expect(string.has_no_title?(/s[a-z]+_node/)).to be false
+        expect(string.has_no_title?(/monkey/)).to be true
       end
     end
   end