capybara 3.29.0 → 3.33.0

data/lib/capybara/node/document.rb

@@ -40,8 +40,8 @@ module Capybara
         find(:xpath, '/html').evaluate_script(*args)
       end
 
-      def scroll_to(*args)
-        find(:xpath, '//body').scroll_to(*args)
+      def scroll_to(*args, **options)
+        find(:xpath, '//body').scroll_to(*args, **options)
       end
     end
   end

data/lib/capybara/node/document_matchers.rb

@@ -42,7 +42,7 @@ module Capybara
       # @return [Boolean]
       #
       def has_title?(title, **options)
-        make_predicate(options) { assert_title(title, options) }
+        make_predicate(options) { assert_title(title, **options) }
       end
 
       ##
@@ -52,13 +52,13 @@ module Capybara
       # @return [Boolean]
       #
       def has_no_title?(title, **options)
-        make_predicate(options) { assert_no_title(title, options) }
+        make_predicate(options) { assert_no_title(title, **options) }
       end
 
     private
 
       def _verify_title(title, options)
-        query = Capybara::Queries::TitleQuery.new(title, options)
+        query = Capybara::Queries::TitleQuery.new(title, **options)
         synchronize(query.wait) { yield(query) }
         true
       end

data/lib/capybara/node/element.rb

@@ -27,9 +27,11 @@ module Capybara
         @query_scope = query_scope
         @query = query
         @allow_reload = false
+        @query_idx = nil
       end
 
-      def allow_reload!
+      def allow_reload!(idx = nil)
+        @query_idx = idx
         @allow_reload = true
       end
 
@@ -113,10 +115,12 @@ module Capybara
       #
       # @return [Capybara::Node::Element]  The element
       def set(value, **options)
-        raise Capybara::ReadOnlyElementError, "Attempt to set readonly element with value: #{value}" if ENV['CAPYBARA_THOROUGH'] && readonly?
+        if ENV['CAPYBARA_THOROUGH'] && readonly?
+          raise Capybara::ReadOnlyElementError, "Attempt to set readonly element with value: #{value}"
+        end
 
         options = session_options.default_set_options.to_h.merge(options)
-        synchronize { base.set(value, options) }
+        synchronize { base.set(value, **options) }
         self
       end
 
@@ -161,10 +165,11 @@ module Capybara
       #       offset will be from the element center, otherwise it will be from the top left corner of the element
       #     @option options [Integer] y  Y coordinate to offset the click location. If {Capybara.configure w3c_click_offset} is `true` the
       #       offset will be from the element center, otherwise it will be from the top left corner of the element
+      # @option options [Float] delay  Delay between the mouse down and mouse up events in seconds (0)
       # @return [Capybara::Node::Element]  The element
       def click(*keys, **options)
-        perform_click_action(keys, options) do |k, opts|
-          base.click(k, opts)
+        perform_click_action(keys, **options) do |k, opts|
+          base.click(k, **opts)
         end
       end
 
@@ -174,10 +179,11 @@ module Capybara
       #
       # @macro action_waiting_behavior
       # @macro click_modifiers
+      # @option options [Float] delay  Delay between the mouse down and mouse up events in seconds (0)
       # @return [Capybara::Node::Element]  The element
       def right_click(*keys, **options)
-        perform_click_action(keys, options) do |k, opts|
-          base.right_click(k, opts)
+        perform_click_action(keys, **options) do |k, opts|
+          base.right_click(k, **opts)
         end
       end
 
@@ -189,8 +195,8 @@ module Capybara
       # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
       def double_click(*keys, **options)
-        perform_click_action(keys, options) do |k, opts|
-          base.double_click(k, opts)
+        perform_click_action(keys, **options) do |k, opts|
+          base.double_click(k, **opts)
         end
       end
 
@@ -405,6 +411,8 @@ module Capybara
       # @option options [Boolean] :html5   When using Chrome/Firefox with Selenium enables to force the use of HTML5
       #                                    (true) or legacy (false) dragging. If not specified the driver will attempt to
       #                                    detect the correct method to use.
+      # @option options [Array<Symbol>,Symbol] :drop_modifiers   Modifier keys which should be held while the dragged element is dropped.
+      #
       #
       # @return [Capybara::Node::Element]  The dragged element
       def drag_to(node, **options)
@@ -543,14 +551,13 @@ module Capybara
 
       # @api private
       def reload
-        if @allow_reload
-          begin
-            reloaded = @query.resolve_for(query_scope.reload)&.first
+        return self unless @allow_reload
 
-            @base = reloaded.base if reloaded
-          rescue StandardError => e
-            raise e unless catch_error?(e)
-          end
+        begin
+          reloaded = @query.resolve_for(query_scope.reload)[@query_idx.to_i]
+          @base = reloaded.base if reloaded
+        rescue StandardError => e
+          raise e unless catch_error?(e)
         end
         self
       end

data/lib/capybara/node/finders.rb

@@ -49,7 +49,7 @@ module Capybara
       #
       def find(*args, **options, &optional_filter_block)
         options[:session_options] = session_options
-        synced_resolve Capybara::Queries::SelectorQuery.new(*args, options, &optional_filter_block)
+        synced_resolve Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
       end
 
       ##
@@ -72,7 +72,7 @@ module Capybara
       #
       def ancestor(*args, **options, &optional_filter_block)
         options[:session_options] = session_options
-        synced_resolve Capybara::Queries::AncestorQuery.new(*args, options, &optional_filter_block)
+        synced_resolve Capybara::Queries::AncestorQuery.new(*args, **options, &optional_filter_block)
       end
 
       ##
@@ -95,7 +95,7 @@ module Capybara
       #
       def sibling(*args, **options, &optional_filter_block)
         options[:session_options] = session_options
-        synced_resolve Capybara::Queries::SiblingQuery.new(*args, options, &optional_filter_block)
+        synced_resolve Capybara::Queries::SiblingQuery.new(*args, **options, &optional_filter_block)
       end
 
       ##
@@ -125,7 +125,7 @@ module Capybara
       # @return [Capybara::Node::Element]   The found element
       #
       def find_field(locator = nil, **options, &optional_filter_block)
-        find(:field, locator, options, &optional_filter_block)
+        find(:field, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -145,7 +145,7 @@ module Capybara
       # @return [Capybara::Node::Element]   The found element
       #
       def find_link(locator = nil, **options, &optional_filter_block)
-        find(:link, locator, options, &optional_filter_block)
+        find(:link, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -172,7 +172,7 @@ module Capybara
       # @return [Capybara::Node::Element]   The found element
       #
       def find_button(locator = nil, **options, &optional_filter_block)
-        find(:button, locator, options, &optional_filter_block)
+        find(:button, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -186,7 +186,7 @@ module Capybara
       # @return [Capybara::Node::Element]   The found element
       #
       def find_by_id(id, **options, &optional_filter_block)
-        find(:id, id, options, &optional_filter_block)
+        find(:id, id, **options, &optional_filter_block)
       end
 
       ##
@@ -235,21 +235,25 @@ module Capybara
       # @option options [Integer] maximum          Maximum number of matches that are expected to be found
       # @option options [Integer] minimum          Minimum number of matches that are expected to be found
       # @option options [Range]   between          Number of matches found must be within the given range
+      # @option options [Boolean] allow_reload     Beta feature - May be removed in any version.
+      #   When `true` allows elements to be reloaded if they become stale. This is an advanced behavior and should only be used
+      #   if you fully understand the potential ramifications. The results can be confusing on dynamic pages. Defaults to `false`
       # @overload all([kind = Capybara.default_selector], locator = nil, **options)
       # @overload all([kind = Capybara.default_selector], locator = nil, **options, &filter_block)
       #   @yieldparam element [Capybara::Node::Element]  The element being considered for inclusion in the results
       #   @yieldreturn [Boolean]                     Should the element be considered in the results?
       # @return [Capybara::Result]                   A collection of found elements
       # @raise [Capybara::ExpectationNotMet]         The number of elements found doesn't match the specified conditions
-      def all(*args, **options, &optional_filter_block)
+      def all(*args, allow_reload: false, **options, &optional_filter_block)
         minimum_specified = options_include_minimum?(options)
         options = { minimum: 1 }.merge(options) unless minimum_specified
         options[:session_options] = session_options
-        query = Capybara::Queries::SelectorQuery.new(*args, options, &optional_filter_block)
+        query = Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
         result = nil
         begin
           synchronize(query.wait) do
             result = query.resolve_for(self)
+            result.allow_reload! if allow_reload
             raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count?
 
             result
@@ -278,7 +282,7 @@ module Capybara
       #
       def first(*args, **options, &optional_filter_block)
         options = { minimum: 1 }.merge(options) unless options_include_minimum?(options)
-        all(*args, options, &optional_filter_block).first
+        all(*args, **options, &optional_filter_block).first
       end
 
     private
@@ -292,7 +296,9 @@ module Capybara
             result = query.resolve_for(self)
           end
 
-          raise Capybara::Ambiguous, "Ambiguous match, found #{result.size} elements matching #{query.applied_description}" if ambiguous?(query, result)
+          if ambiguous?(query, result)
+            raise Capybara::Ambiguous, "Ambiguous match, found #{result.size} elements matching #{query.applied_description}"
+          end
           raise Capybara::ElementNotFound, "Unable to find #{query.applied_description}" if result.empty?
 
           result.first

data/lib/capybara/node/matchers.rb

@@ -61,7 +61,7 @@ module Capybara
       # @return [Boolean]                       If the styles match
       #
       def matches_style?(styles, **options)
-        make_predicate(options) { assert_matches_style(styles, options) }
+        make_predicate(options) { assert_matches_style(styles, **options) }
       end
 
       ##
@@ -107,7 +107,9 @@ module Capybara
       #
       def assert_selector(*args, &optional_filter_block)
         _verify_selector_result(args, optional_filter_block) do |result, query|
-          raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count? && (result.any? || query.expects_none?)
+          unless result.matches_count? && (result.any? || query.expects_none?)
+            raise Capybara::ExpectationNotMet, result.failure_message
+          end
         end
       end
 
@@ -121,8 +123,8 @@ module Capybara
       # @raise [Capybara::ExpectationNotMet]    If the element doesn't have the specified styles
       #
       def assert_matches_style(styles, **options)
-        query_args = _set_query_session_options(styles, options)
-        query = Capybara::Queries::StyleQuery.new(*query_args)
+        query_args, query_opts = _set_query_session_options(styles, options)
+        query = Capybara::Queries::StyleQuery.new(*query_args, **query_opts)
         synchronize(query.wait) do
           raise Capybara::ExpectationNotMet, query.failure_message unless query.resolves_for?(self)
         end
@@ -153,7 +155,7 @@ module Capybara
       # @overload assert_all_of_selectors([kind = Capybara.default_selector], *locators, **options)
       #
       def assert_all_of_selectors(*args, **options, &optional_filter_block)
-        _verify_multiple(*args, options) do |selector, locator, opts|
+        _verify_multiple(*args, **options) do |selector, locator, opts|
           assert_selector(selector, locator, opts, &optional_filter_block)
         end
       end
@@ -174,7 +176,7 @@ module Capybara
       # @overload assert_none_of_selectors([kind = Capybara.default_selector], *locators, **options)
       #
       def assert_none_of_selectors(*args, **options, &optional_filter_block)
-        _verify_multiple(*args, options) do |selector, locator, opts|
+        _verify_multiple(*args, **options) do |selector, locator, opts|
           assert_no_selector(selector, locator, opts, &optional_filter_block)
         end
       end
@@ -199,12 +201,10 @@ module Capybara
         selector = extract_selector(args)
         synchronize(wait) do
           res = args.map do |locator|
-            begin
-              assert_selector(selector, locator, options, &optional_filter_block)
-              break nil
-            rescue Capybara::ExpectationNotMet => e
-              e.message
-            end
+            assert_selector(selector, locator, options, &optional_filter_block)
+            break nil
+          rescue Capybara::ExpectationNotMet => e
+            e.message
           end
           raise Capybara::ExpectationNotMet, res.join(' or ') if res
 
@@ -266,7 +266,7 @@ module Capybara
       # @return [Boolean]                         If the expression exists
       #
       def has_xpath?(path, **options, &optional_filter_block)
-        has_selector?(:xpath, path, options, &optional_filter_block)
+        has_selector?(:xpath, path, **options, &optional_filter_block)
       end
 
       ##
@@ -278,7 +278,7 @@ module Capybara
       # @return [Boolean]
       #
       def has_no_xpath?(path, **options, &optional_filter_block)
-        has_no_selector?(:xpath, path, options, &optional_filter_block)
+        has_no_selector?(:xpath, path, **options, &optional_filter_block)
       end
 
       ##
@@ -305,7 +305,7 @@ module Capybara
       # @return [Boolean]                         If the selector exists
       #
       def has_css?(path, **options, &optional_filter_block)
-        has_selector?(:css, path, options, &optional_filter_block)
+        has_selector?(:css, path, **options, &optional_filter_block)
       end
 
       ##
@@ -317,7 +317,7 @@ module Capybara
       # @return [Boolean]
       #
       def has_no_css?(path, **options, &optional_filter_block)
-        has_no_selector?(:css, path, options, &optional_filter_block)
+        has_no_selector?(:css, path, **options, &optional_filter_block)
       end
 
       ##
@@ -330,7 +330,7 @@ module Capybara
       # @return [Boolean]                 Whether it exists
       #
       def has_link?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:link, locator, options, &optional_filter_block)
+        has_selector?(:link, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -342,7 +342,7 @@ module Capybara
       # @return [Boolean]            Whether it doesn't exist
       #
       def has_no_link?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:link, locator, options, &optional_filter_block)
+        has_no_selector?(:link, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -354,7 +354,7 @@ module Capybara
       # @return [Boolean]            Whether it exists
       #
       def has_button?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:button, locator, options, &optional_filter_block)
+        has_selector?(:button, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -366,7 +366,7 @@ module Capybara
       # @return [Boolean]            Whether it doesn't exist
       #
       def has_no_button?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:button, locator, options, &optional_filter_block)
+        has_no_selector?(:button, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -392,7 +392,7 @@ module Capybara
       # @return [Boolean]                        Whether it exists
       #
       def has_field?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:field, locator, options, &optional_filter_block)
+        has_selector?(:field, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -406,7 +406,7 @@ module Capybara
       # @return [Boolean]                        Whether it doesn't exist
       #
       def has_no_field?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:field, locator, options, &optional_filter_block)
+        has_no_selector?(:field, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -419,7 +419,7 @@ module Capybara
       # @return [Boolean]                 Whether it exists
       #
       def has_checked_field?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:field, locator, options.merge(checked: true), &optional_filter_block)
+        has_selector?(:field, locator, **options.merge(checked: true), &optional_filter_block)
       end
 
       ##
@@ -432,7 +432,7 @@ module Capybara
       # @return [Boolean]                 Whether it doesn't exist
       #
       def has_no_checked_field?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:field, locator, options.merge(checked: true), &optional_filter_block)
+        has_no_selector?(:field, locator, **options.merge(checked: true), &optional_filter_block)
       end
 
       ##
@@ -445,7 +445,7 @@ module Capybara
       # @return [Boolean]                 Whether it exists
       #
       def has_unchecked_field?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:field, locator, options.merge(unchecked: true), &optional_filter_block)
+        has_selector?(:field, locator, **options.merge(unchecked: true), &optional_filter_block)
       end
 
       ##
@@ -458,7 +458,7 @@ module Capybara
       # @return [Boolean]                 Whether it doesn't exist
       #
       def has_no_unchecked_field?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:field, locator, options.merge(unchecked: true), &optional_filter_block)
+        has_no_selector?(:field, locator, **options.merge(unchecked: true), &optional_filter_block)
       end
 
       ##
@@ -491,7 +491,7 @@ module Capybara
       # @return [Boolean]                               Whether it exists
       #
       def has_select?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:select, locator, options, &optional_filter_block)
+        has_selector?(:select, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -503,7 +503,7 @@ module Capybara
       # @return [Boolean]     Whether it doesn't exist
       #
       def has_no_select?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:select, locator, options, &optional_filter_block)
+        has_no_selector?(:select, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -525,7 +525,7 @@ module Capybara
       # @return [Boolean]        Whether it exists
       #
       def has_table?(locator = nil, **options, &optional_filter_block)
-        has_selector?(:table, locator, options, &optional_filter_block)
+        has_selector?(:table, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -537,7 +537,7 @@ module Capybara
       # @return [Boolean]       Whether it doesn't exist
       #
       def has_no_table?(locator = nil, **options, &optional_filter_block)
-        has_no_selector?(:table, locator, options, &optional_filter_block)
+        has_no_selector?(:table, locator, **options, &optional_filter_block)
       end
 
       ##
@@ -595,7 +595,7 @@ module Capybara
       # @return [Boolean]
       #
       def matches_xpath?(xpath, **options, &optional_filter_block)
-        matches_selector?(:xpath, xpath, options, &optional_filter_block)
+        matches_selector?(:xpath, xpath, **options, &optional_filter_block)
       end
 
       ##
@@ -606,7 +606,7 @@ module Capybara
       # @return [Boolean]
       #
       def matches_css?(css, **options, &optional_filter_block)
-        matches_selector?(:css, css, options, &optional_filter_block)
+        matches_selector?(:css, css, **options, &optional_filter_block)
       end
 
       ##
@@ -629,7 +629,7 @@ module Capybara
       # @return [Boolean]
       #
       def not_matches_xpath?(xpath, **options, &optional_filter_block)
-        not_matches_selector?(:xpath, xpath, options, &optional_filter_block)
+        not_matches_selector?(:xpath, xpath, **options, &optional_filter_block)
       end
 
       ##
@@ -640,7 +640,7 @@ module Capybara
       # @return [Boolean]
       #
       def not_matches_css?(css, **options, &optional_filter_block)
-        not_matches_selector?(:css, css, options, &optional_filter_block)
+        not_matches_selector?(:css, css, **options, &optional_filter_block)
       end
 
       ##
@@ -670,8 +670,8 @@ module Capybara
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #
-      def assert_text(*args)
-        _verify_text(args) do |count, query|
+      def assert_text(type_or_text, *args, **opts)
+        _verify_text(type_or_text, *args, **opts) do |count, query|
           unless query.matches_count?(count) && (count.positive? || query.expects_none?)
             raise Capybara::ExpectationNotMet, query.failure_message
           end
@@ -686,8 +686,8 @@ module Capybara
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #
-      def assert_no_text(*args)
-        _verify_text(args) do |count, query|
+      def assert_no_text(type_or_text, *args, **opts)
+        _verify_text(type_or_text, *args, **opts) do |count, query|
           if query.matches_count?(count) && (count.positive? || query.expects_none?)
             raise Capybara::ExpectationNotMet, query.negative_failure_message
           end
@@ -709,7 +709,7 @@ module Capybara
       # @return [Boolean]                            Whether it exists
       #
       def has_text?(*args, **options)
-        make_predicate(options) { assert_text(*args, options) }
+        make_predicate(options) { assert_text(*args, **options) }
       end
       alias_method :has_content?, :has_text?
 
@@ -721,7 +721,7 @@ module Capybara
       # @return [Boolean]  Whether it doesn't exist
       #
       def has_no_text?(*args, **options)
-        make_predicate(options) { assert_no_text(*args, options) }
+        make_predicate(options) { assert_no_text(*args, **options) }
       end
       alias_method :has_no_content?, :has_no_text?
 
@@ -738,7 +738,9 @@ module Capybara
       #
       def assert_ancestor(*args, &optional_filter_block)
         _verify_selector_result(args, optional_filter_block, Capybara::Queries::AncestorQuery) do |result, query|
-          raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count? && (result.any? || query.expects_none?)
+          unless result.matches_count? && (result.any? || query.expects_none?)
+            raise Capybara::ExpectationNotMet, result.failure_message
+          end
         end
       end
 
@@ -779,7 +781,9 @@ module Capybara
       #
       def assert_sibling(*args, &optional_filter_block)
         _verify_selector_result(args, optional_filter_block, Capybara::Queries::SiblingQuery) do |result, query|
-          raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count? && (result.any? || query.expects_none?)
+          unless result.matches_count? && (result.any? || query.expects_none?)
+            raise Capybara::ExpectationNotMet, result.failure_message
+          end
         end
       end
 
@@ -826,8 +830,14 @@ module Capybara
       end
 
       def _verify_selector_result(query_args, optional_filter_block, query_type = Capybara::Queries::SelectorQuery)
-        query_args = _set_query_session_options(*query_args)
-        query = query_type.new(*query_args, &optional_filter_block)
+        # query_args, query_opts = if query_args[0].is_a? Symbol
+        #   a,o = _set_query_session_options(*query_args.slice(2..))
+        #   [query_args.slice(0..1).concat(a), o]
+        # else
+        #   _set_query_session_options(*query_args)
+        # end
+        query_args, query_opts = _set_query_session_options(*query_args)
+        query = query_type.new(*query_args, **query_opts, &optional_filter_block)
         synchronize(query.wait) do
           yield query.resolve_for(self), query
         end
@@ -835,26 +845,29 @@ module Capybara
       end
 
       def _verify_match_result(query_args, optional_filter_block)
-        query_args = _set_query_session_options(*query_args)
-        query = Capybara::Queries::MatchQuery.new(*query_args, &optional_filter_block)
+        query_args, query_opts = _set_query_session_options(*query_args)
+        query = Capybara::Queries::MatchQuery.new(*query_args, **query_opts, &optional_filter_block)
         synchronize(query.wait) do
           yield query.resolve_for(parent || session&.document || query_scope)
         end
         true
       end
 
-      def _verify_text(query_args)
-        query_args = _set_query_session_options(*query_args)
-        query = Capybara::Queries::TextQuery.new(*query_args)
+      def _verify_text(type = nil, expected_text, **query_options) # rubocop:disable Style/OptionalArguments
+        query_options[:session_options] = session_options
+        query = Capybara::Queries::TextQuery.new(type, expected_text, **query_options)
         synchronize(query.wait) do
           yield query.resolve_for(self), query
         end
         true
       end
 
-      def _set_query_session_options(*query_args, **query_options)
+      def _set_query_session_options(*query_args)
+        query_args, query_options = query_args.dup, {}
+        # query_options = query_args.pop if query_options.empty? && query_args.last.is_a?(Hash)
+        query_options = query_args.pop if query_args.last.is_a?(Hash)
         query_options[:session_options] = session_options
-        query_args.push(query_options)
+        [query_args, query_options]
       end
 
       def make_predicate(options)