capybara 3.3.0 → 3.40.0

data/lib/capybara.rb

@@ -5,6 +5,7 @@ require 'nokogiri'
 require 'xpath'
 require 'forwardable'
 require 'capybara/config'
+require 'capybara/registration_container'
 
 module Capybara
   class CapybaraError < StandardError; end
@@ -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
@@ -64,32 +67,49 @@ 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)
-    # [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)
-    # [default_set_options = Hash]  The default options passed to Node::set (Default: {})
-    #
-    # === 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 config
@@ -109,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,7 +148,7 @@ module Capybara
     # @yieldparam host                        The host/ip to bind to
     #
     def register_server(name, &block)
-      servers[name.to_sym] = block
+      servers.send(:register, name.to_sym, block)
     end
 
     ##
@@ -159,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
 
     ##
@@ -170,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
     #
     #
@@ -182,11 +202,11 @@ 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
@@ -195,15 +215,13 @@ module Capybara
     # 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>
@@ -242,7 +260,7 @@ module Capybara
     #
     def current_driver
       if threadsafe
-        Thread.current['capybara_current_driver']
+        Thread.current.thread_variable_get :capybara_current_driver
       else
         @current_driver
       end || default_driver
@@ -251,7 +269,7 @@ module Capybara
 
     def current_driver=(name)
       if threadsafe
-        Thread.current['capybara_current_driver'] = name
+        Thread.current.thread_variable_set :capybara_current_driver, name
       else
         @current_driver = name
       end
@@ -291,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
 
     ##
@@ -318,7 +336,8 @@ module Capybara
     #
     def session_name
       if threadsafe
-        Thread.current['capybara_session_name'] ||= :default
+        Thread.current.thread_variable_get(:capybara_session_name) ||
+          Thread.current.thread_variable_set(:capybara_session_name, :default)
       else
         @session_name ||= :default
       end
@@ -326,7 +345,7 @@ module Capybara
 
     def session_name=(name)
       if threadsafe
-        Thread.current['capybara_session_name'] = name
+        Thread.current.thread_variable_set :capybara_session_name, name
       else
         @session_name = name
       end
@@ -334,22 +353,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
 
     ##
@@ -360,9 +388,21 @@ module Capybara
     # @return [Nokogiri::HTML::Document]      HTML document
     #
     def HTML(html) # rubocop:disable Naming/MethodName
-      Nokogiri::HTML(html).tap do |document|
+      # 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
@@ -378,7 +418,25 @@ module Capybara
     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.thread_variable_get :capybara_specified_session
+      else
+        @specified_session ||= nil
+      end
+    end
+
+    def specified_session=(session)
+      if threadsafe
+        Thread.current.thread_variable_set :capybara_specified_session, session
+      else
+        @specified_session = session
+      end
     end
   end
 
@@ -407,6 +465,7 @@ module Capybara
   require 'capybara/queries/ancestor_query'
   require 'capybara/queries/sibling_query'
   require 'capybara/queries/style_query'
+  require 'capybara/queries/active_element_query'
 
   require 'capybara/node/finders'
   require 'capybara/node/matchers'
@@ -424,45 +483,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/nodes/marionette_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|
-  begin
-    require 'rack/handler/puma'
-  rescue LoadError
-    raise LoadError, "Capybara is unable to load `puma` for its server, please add `puma` to your project or specify a different server via something like `Capybara.server = :webrick`."
-  end
-  # If we just run the Puma Rack handler it installs signal handlers which prevent us from being able to interrupt tests.
-  # Therefore construct and run the Server instance ourselves.
-  # Rack::Handler::Puma.run(app, { Host: host, Port: port, Threads: "0:4", workers: 0, daemon: false }.merge(options))
-
-  conf = Rack::Handler::Puma.config(app, { Host: host, Port: port, Threads: "0:4", workers: 0, daemon: false }.merge(options))
-  events = conf.options[:Silent] ? ::Puma::Events.strings : ::Puma::Events.stdio
-
-  events.log "Capybara starting Puma..."
-  events.log "* Version #{Puma::Const::PUMA_VERSION} , codename: #{Puma::Const::CODE_NAME}"
-  events.log "* Min threads: #{conf.options[:min_threads]}, max threads: #{conf.options[:max_threads]}"
-
-  Puma::Server.new(conf.app, events, conf.options).tap do |s|
-    s.binder.parse conf.options[:binds], s.events
-    s.min_threads = conf.options[:min_threads]
-    s.max_threads = conf.options[:max_threads]
-  end.run.join
-end
+require 'capybara/registrations/servers'
+require 'capybara/registrations/drivers'
 
 Capybara.configure do |config|
   config.always_include_port = false
@@ -470,37 +498,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.automatic_label_click = false
   config.enable_aria_label = false
+  config.enable_aria_role = false
   config.reuse_server = true
   config.default_set_options = {}
-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|
-  Capybara::Selenium::Driver.load_selenium
-  browser_options = ::Selenium::WebDriver::Chrome::Options.new
-  browser_options.args << '--headless'
-  browser_options.args << '--disable-gpu' if Gem.win_platform?
-  Capybara::Selenium::Driver.new(app, browser: :chrome, options: browser_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

data/spec/basic_node_spec.rb

@@ -3,9 +3,10 @@
 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>
@@ -46,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 value" 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