capybara 2.5.0 → 2.18.0

data/lib/capybara/node/document_matchers.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Capybara
   module Node
     module DocumentMatchers
@@ -10,17 +11,12 @@ module Capybara
       #   @overload $0(regexp, options = {})
       #     @param regexp [Regexp]           The regexp that title should match to
       #   @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time that Capybara will wait for title to eq/match given string/regexp argument
+      #   @option options [Boolean] :exact (false) When passed a string should the match be exact or just substring
       # @raise [Capybara::ExpectationNotMet] if the assertion hasn't succeeded during wait time
       # @return [true]
       #
       def assert_title(title, options = {})
-        query = Capybara::Queries::TitleQuery.new(title, options)
-        synchronize(query.wait) do
-          unless query.resolves_for?(self)
-            raise Capybara::ExpectationNotMet, query.failure_message
-          end
-        end
-        return true
+        _verify_title(title,options) { |query| raise Capybara::ExpectationNotMet, query.failure_message unless query.resolves_for?(self) }
       end
 
       ##
@@ -31,13 +27,7 @@ module Capybara
       # @return [true]
       #
       def assert_no_title(title, options = {})
-        query = Capybara::Queries::TitleQuery.new(title, options)
-        synchronize(query.wait) do
-          if query.resolves_for?(self)
-            raise Capybara::ExpectationNotMet, query.negative_failure_message
-          end
-        end
-        return true
+        _verify_title(title,options) { |query| raise Capybara::ExpectationNotMet, query.negative_failure_message if query.resolves_for?(self) }
       end
 
       ##
@@ -63,6 +53,17 @@ module Capybara
       rescue Capybara::ExpectationNotMet
         return false
       end
+
+      private
+
+      def _verify_title(title, options)
+        query = Capybara::Queries::TitleQuery.new(title, options)
+        synchronize(query.wait) do
+          yield(query)
+        end
+        return true
+      end
+
     end
   end
 end

data/lib/capybara/node/element.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Capybara
   module Node
 
@@ -9,7 +10,7 @@ module Capybara
     #     session = Capybara::Session.new(:rack_test, my_app)
     #
     #     bar = session.find('#bar')              # from Capybara::Node::Finders
-    #     bar.select('Baz', :from => 'Quox')      # from Capybara::Node::Actions
+    #     bar.select('Baz', from: 'Quox')      # from Capybara::Node::Actions
     #
     # {Capybara::Node::Element} also has access to HTML attributes and other properties of the
     # element:
@@ -22,10 +23,11 @@ module Capybara
     #
     class Element < Base
 
-      def initialize(session, base, parent, query)
+      def initialize(session, base, query_scope, query)
         super(session, base)
-        @parent = parent
+        @query_scope = query_scope
         @query = query
+        @allow_reload = false
       end
 
       def allow_reload!
@@ -53,7 +55,7 @@ module Capybara
       # @return [String]              The text of the element
       #
       def text(type=nil)
-        type ||= :all unless Capybara.ignore_hidden_elements or Capybara.visible_text_only
+        type ||= :all unless session_options.ignore_hidden_elements or session_options.visible_text_only
         synchronize do
           if type == :all
             base.all_text
@@ -91,6 +93,7 @@ module Capybara
       # @param [String] value    The new value
       # @param [Hash{}] options  Driver specific options for how to set the value
       #
+      # @return [Capybara::Node::Element]  The element
       def set(value, options={})
         options ||= {}
 
@@ -107,47 +110,58 @@ module Capybara
             base.set(value)
           end
         end
+        return self
       end
 
       ##
       #
       # Select this node if is an option element inside a select tag
       #
+      # @return [Capybara::Node::Element]  The element
       def select_option
         warn "Attempt to select disabled option: #{value || text}" if disabled?
         synchronize { base.select_option }
+        return self
       end
 
       ##
       #
       # Unselect this node if is an option element inside a multiple select tag
       #
+      # @return [Capybara::Node::Element]  The element
       def unselect_option
         synchronize { base.unselect_option }
+        return self
       end
 
       ##
       #
       # Click the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def click
         synchronize { base.click }
+        return self
       end
 
       ##
       #
       # Right Click the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def right_click
         synchronize { base.right_click }
+        return self
       end
 
       ##
       #
       # Double Click the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def double_click
         synchronize { base.double_click }
+        return self
       end
 
       ##
@@ -220,16 +234,20 @@ module Capybara
       # :meta
       # :command      - alias of :meta
       #
+      # @return [Capybara::Node::Element]  The element
       def send_keys(*args)
         synchronize { base.send_keys(*args) }
+        return self
       end
 
       ##
       #
       # Hover on the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def hover
         synchronize { base.hover }
+        return self
       end
 
       ##
@@ -281,6 +299,26 @@ module Capybara
         synchronize { base.disabled? }
       end
 
+      ##
+      #
+      # Whether or not the element is readonly.
+      #
+      # @return [Boolean]     Whether the element is readonly
+      #
+      def readonly?
+        synchronize { base.readonly? }
+      end
+
+      ##
+      #
+      # Whether or not the element supports multiple results.
+      #
+      # @return [Boolean]     Whether the element supports multiple results.
+      #
+      def multiple?
+        synchronize { base.multiple? }
+      end
+
       ##
       #
       # An XPath expression describing where on the page the element can be found
@@ -298,8 +336,10 @@ module Capybara
       #
       # @param [String] event       The name of the event to trigger
       #
+      # @return [Capybara::Node::Element]  The element
       def trigger(event)
         synchronize { base.trigger(event) }
+        return self
       end
 
       ##
@@ -312,14 +352,16 @@ module Capybara
       #
       # @param [Capybara::Node::Element] node     The element to drag to
       #
+      # @return [Capybara::Node::Element]  The element
       def drag_to(node)
         synchronize { base.drag_to(node.base) }
+        return self
       end
 
       def reload
         if @allow_reload
           begin
-            reloaded = parent.reload.first(@query.name, @query.locator, @query.options)
+            reloaded = query_scope.reload.first(@query.name, @query.locator, @query.options)
             @base = reloaded.base if reloaded
           rescue => e
             raise e unless catch_error?(e)
@@ -329,9 +371,15 @@ module Capybara
       end
 
       def inspect
-        %(#<Capybara::Node::Element tag="#{tag_name}" path="#{path}">)
+        %(#<Capybara::Node::Element tag="#{base.tag_name}" path="#{base.path}">)
       rescue NotSupportedByDriverError
-        %(#<Capybara::Node::Element tag="#{tag_name}">)
+        %(#<Capybara::Node::Element tag="#{base.tag_name}">)
+      rescue => e
+        if session.driver.invalid_element_errors.any? { |et| e.is_a?(et)}
+          %(Obsolete #<Capybara::Node::Element>)
+        else
+          raise
+        end
       end
     end
   end

data/lib/capybara/node/finders.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Capybara
   module Node
     module Finders
@@ -17,8 +18,8 @@ module Capybara
       # +find+ takes the same options as +all+.
       #
       #     page.find('#foo').find('.bar')
-      #     page.find(:xpath, '//div[contains(., "bar")]')
-      #     page.find('li', :text => 'Quox').click_link('Delete')
+      #     page.find(:xpath, './/div[contains(., "bar")]')
+      #     page.find('li', text: 'Quox').click_link('Delete')
       #
       # @param (see Capybara::Node::Finders#all)
       #
@@ -27,43 +28,104 @@ module Capybara
       # @return [Capybara::Node::Element]      The found element
       # @raise  [Capybara::ElementNotFound]    If the element can't be found before time expires
       #
-      def find(*args)
-        query = Capybara::Query.new(*args)
-        synchronize(query.wait) do
-          if query.match == :smart or query.match == :prefer_exact
-            result = query.resolve_for(self, true)
-            result = query.resolve_for(self, false) if result.size == 0 && !query.exact?
-          else
-            result = query.resolve_for(self)
-          end
-          if query.match == :one or query.match == :smart and result.size > 1
-            raise Capybara::Ambiguous.new("Ambiguous match, found #{result.size} elements matching #{query.description}")
-          end
-          if result.size == 0
-            raise Capybara::ElementNotFound.new("Unable to find #{query.description}")
-          end
-          result.first
-        end.tap(&:allow_reload!)
+      def find(*args, &optional_filter_block)
+        if args.last.is_a? Hash
+          args.last[:session_options] = session_options
+        else
+          args.push(session_options: session_options)
+        end
+        synced_resolve Capybara::Queries::SelectorQuery.new(*args, &optional_filter_block)
       end
 
       ##
       #
-      # Find a form field on the page. The field can be found by its name, id or label text.
+      # Find an {Capybara::Node::Element} based on the given arguments that is also an ancestor of the element called on. +ancestor+ will raise an error if the element
+      # is not found.
+      #
+      # +ancestor+ takes the same options as +find+.
+      #
+      #     element.ancestor('#foo').find('.bar')
+      #     element.ancestor(:xpath, './/div[contains(., "bar")]')
+      #     element.ancestor('ul', text: 'Quox').click_link('Delete')
+      #
+      # @param (see Capybara::Node::Finders#find)
+      #
+      # @!macro waiting_behavior
+      #
+      # @option options [Boolean] match        The matching strategy to use.
+      #
+      # @return [Capybara::Node::Element]      The found element
+      # @raise  [Capybara::ElementNotFound]    If the element can't be found before time expires
+      #
+      def ancestor(*args, &optional_filter_block)
+        if args.last.is_a? Hash
+          args.last[:session_options] = session_options
+        else
+          args.push(session_options: session_options)
+        end
+        synced_resolve Capybara::Queries::AncestorQuery.new(*args, &optional_filter_block)
+      end
+
+      ##
+      #
+      # Find an {Capybara::Node::Element} based on the given arguments that is also a sibling of the element called on. +sibling+ will raise an error if the element
+      # is not found.
+      #
+      #
+      # +sibling+ takes the same options as +find+.
+      #
+      #     element.sibling('#foo').find('.bar')
+      #     element.sibling(:xpath, './/div[contains(., "bar")]')
+      #     element.sibling('ul', text: 'Quox').click_link('Delete')
+      #
+      # @param (see Capybara::Node::Finders#find)
       #
       # @macro waiting_behavior
       #
-      # @param [String] locator             Which field to find
+      # @option options [Boolean] match        The matching strategy to use.
+      #
+      # @return [Capybara::Node::Element]      The found element
+      # @raise  [Capybara::ElementNotFound]    If the element can't be found before time expires
+      #
+      def sibling(*args, &optional_filter_block)
+        if args.last.is_a? Hash
+          args.last[:session_options] = session_options
+        else
+          args.push(session_options: session_options)
+        end
+        synced_resolve Capybara::Queries::SiblingQuery.new(*args, &optional_filter_block)
+      end
+
+      ##
+      #
+      # Find a form field on the page. The field can be found by its name, id or label text.
       #
-      # @option options [Boolean] checked  Match checked field?
-      # @option options [Boolean] unchecked   Match unchecked field?
-      # @option options [Boolean] disabled (false)  Match disabled field?
-      # @option options [Boolean] readonly Match readonly field?
-      # @option options [String] with   Value of field to match on
-      # @option options [String] type   Type of field to match on
+      # @overload find_field([locator], options={})
+      #   @param [String] locator             name, id, placeholder or text of associated label element
+      #
+      #   @macro waiting_behavior
+      #
+      #
+      #   @option options [Boolean] checked       Match checked field?
+      #   @option options [Boolean] unchecked     Match unchecked field?
+      #   @option options [Boolean, Symbol] disabled (false)  Match disabled field?
+      #                                                       * true - only finds a disabled field
+      #                                                       * false - only finds an enabled field
+      #                                                       * :all - finds either an enabled or disabled field
+      #   @option options [Boolean] readonly      Match readonly field?
+      #   @option options [String, Regexp] with   Value of field to match on
+      #   @option options [String] type           Type of field to match on
+      #   @option options [Boolean] multiple      Match fields that can have multiple values?
+      #   @option options [String] id             Match fields that match the id attribute
+      #   @option options [String] name           Match fields that match the name attribute
+      #   @option options [String] placeholder    Match fields that match the placeholder attribute
+      #   @option options [String, Array<String>] Match fields that match the class(es) passed
       # @return [Capybara::Node::Element]   The found element
       #
-      def find_field(locator, options={})
-        find(:field, locator, options)
+
+      def find_field(locator=nil, options={}, &optional_filter_block)
+        locator, options = nil, locator if locator.is_a? Hash
+        find(:field, locator, options, &optional_filter_block)
       end
       alias_method :field_labeled, :find_field
 
@@ -71,14 +133,21 @@ module Capybara
       #
       # Find a link on the page. The link can be found by its id or text.
       #
-      # @macro waiting_behavior
+      # @overload find_link([locator], options={})
+      #   @param [String] locator            id, title, text, or alt of enclosed img element
+      #
+      #   @macro waiting_behavior
       #
-      # @param [String] locator             Which link to find
-      # @option options [String,Regexp] href        Value to match against the links href
+      #   @option options [String,Regexp,nil] href        Value to match against the links href, if nil finds link placeholders (<a> elements with no href attribute)
+      #   @option options [String] id                 Match links with the id provided
+      #   @option options [String] title              Match links with the title provided
+      #   @option options [String] alt                Match links with a contained img element whose alt matches
+      #   @option options [String, Array<String>] class    Match links that match the class(es) provided
       # @return [Capybara::Node::Element]   The found element
       #
-      def find_link(locator, options={})
-        find(:link, locator, options)
+      def find_link(locator=nil, options={}, &optional_filter_block)
+        locator, options = nil, locator if locator.is_a? Hash
+        find(:link, locator, options, &optional_filter_block)
       end
 
       ##
@@ -87,15 +156,27 @@ module Capybara
       # This can be any \<input> element of type submit, reset, image, button or it can be a
       # \<button> element. All buttons can be found by their id, value, or title. \<button> elements can also be found
       # by their text content, and image \<input> elements by their alt attribute
-
-      # @macro waiting_behavior
       #
-      # @param [String] locator             Which button to find
-      # @option options [Boolean] disabled (false)  Match disabled button?
+      # @overload find_button([locator], options={})
+      #   @param [String] locator            id, value, title, text content, alt of image
+      #
+      #   @overload find_button(options={})
+      #
+      #   @macro waiting_behavior
+      #
+      #   @option options [Boolean, Symbol] disabled (false)  Match disabled button?
+      #                                                       * true - only finds a disabled button
+      #                                                       * false - only finds an enabled button
+      #                                                       * :all - finds either an enabled or disabled button
+      #   @option options [String] id                 Match buttons with the id provided
+      #   @option options [String] title              Match buttons with the title provided
+      #   @option options [String] value              Match buttons with the value provided
+      #   @option options [String, Array<String>] class    Match buttons that match the class(es) provided
       # @return [Capybara::Node::Element]   The found element
       #
-      def find_button(locator, options={})
-        find(:button, locator, options)
+      def find_button(locator=nil, options={}, &optional_filter_block)
+        locator, options = nil, locator if locator.is_a? Hash
+        find(:button, locator, options, &optional_filter_block)
       end
 
       ##
@@ -104,15 +185,16 @@ module Capybara
       #
       # @macro waiting_behavior
       #
-      # @param [String] id                  Which element to find
+      # @param [String] id                  id of element
       #
       # @return [Capybara::Node::Element]   The found element
       #
-      def find_by_id(id, options={})
-        find(:id, id, options)
+      def find_by_id(id, options={}, &optional_filter_block)
+        find(:id, id, options, &optional_filter_block)
       end
 
       ##
+      # @!method all([kind = Capybara.default_selector], locator = nil, options = {})
       #
       # Find all elements on the page matching the given selector
       # and options.
@@ -122,7 +204,7 @@ module Capybara
       # following statements are equivalent:
       #
       #     page.all(:css, 'a#person_123')
-      #     page.all(:xpath, '//a[@id="person_123"]')
+      #     page.all(:xpath, './/a[@id="person_123"]')
       #
       #
       # If the type of selector is left out, Capybara uses
@@ -131,47 +213,56 @@ module Capybara
       #     page.all("a#person_123")
       #
       #     Capybara.default_selector = :xpath
-      #     page.all('//a[@id="person_123"]')
+      #     page.all('.//a[@id="person_123"]')
       #
       # The set of found elements can further be restricted by specifying
       # options. It's possible to select elements by their text or visibility:
       #
-      #     page.all('a', :text => 'Home')
-      #     page.all('#menu li', :visible => true)
+      #     page.all('a', text: 'Home')
+      #     page.all('#menu li', visible: true)
       #
       # By default if no elements are found, an empty array is returned;
       # however, expectations can be set on the number of elements to be found which
       # will trigger Capybara's waiting behavior for the expectations to match.The
       # expectations can be set using
       #
-      #     page.assert_selector('p#foo', :count => 4)
-      #     page.assert_selector('p#foo', :maximum => 10)
-      #     page.assert_selector('p#foo', :minimum => 1)
-      #     page.assert_selector('p#foo', :between => 1..10)
+      #     page.assert_selector('p#foo', count: 4)
+      #     page.assert_selector('p#foo', maximum: 10)
+      #     page.assert_selector('p#foo', minimum: 1)
+      #     page.assert_selector('p#foo', between: 1..10)
       #
       # See {Capybara::Helpers#matches_count?} for additional information about
       # count matching.
       #
-      # @overload all([kind], locator, options)
-      #   @param [:css, :xpath] kind                 The type of selector
-      #   @param [String] locator                    The selector
-      #   @option options [String, Regexp] text      Only find elements which contain this text or match this regexp
-      #   @option options [Boolean, Symbol] visible  Only find elements with the specified visibility:
+      # @param [Symbol] kind                       Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
+      # @param [String] locator                    The selector
+      # @option options [String, Regexp] text      Only find elements which contain this text or match this regexp
+      # @option options [String, Boolean] exact_text (Capybara.exact_text) When String the string the elements contained text must match exactly, when Boolean controls whether the :text option must match exactly
+      # @option options [Boolean, Symbol] visible  Only find elements with the specified visibility:
       #                                              * true - only finds visible elements.
       #                                              * false - finds invisible _and_ visible elements.
       #                                              * :all - same as false; finds visible and invisible elements.
       #                                              * :hidden - only finds invisible elements.
       #                                              * :visible - same as true; only finds visible elements.
-      #   @option options [Integer] count            Exact number of matches that are expected to be found
-      #   @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] exact            Control whether `is` expressions in the given XPath match exactly or partially
-      #   @option options [Integer] wait (Capybara.default_max_wait_time)  The time to wait for element count expectations to become true
+      # @option options [Integer] count            Exact number of matches that are expected to be found
+      # @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] exact            Control whether `is` expressions in the given XPath match exactly or partially
+      # @option options [Integer] wait (Capybara.default_max_wait_time)  The time to wait for element count expectations to become true
+      # @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
       #
-      def all(*args)
-        query = Capybara::Query.new(*args)
+      def all(*args, &optional_filter_block)
+        if args.last.is_a? Hash
+          args.last[:session_options] = session_options
+        else
+          args.push(session_options: session_options)
+        end
+        query = Capybara::Queries::SelectorQuery.new(*args, &optional_filter_block)
         synchronize(query.wait) do
           result = query.resolve_for(self)
           raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count?
@@ -195,15 +286,36 @@ module Capybara
       #   @param [Hash] options                      Additional options; see {#all}
       # @return [Capybara::Node::Element]            The found element or nil
       #
-      def first(*args)
-        if Capybara.wait_on_first_by_default
+      def first(*args, &optional_filter_block)
+        if session_options.wait_on_first_by_default
           options = if args.last.is_a?(Hash) then args.pop.dup else {} end
           args.push({minimum: 1}.merge(options))
         end
-        all(*args).first
+        all(*args, &optional_filter_block).first
       rescue Capybara::ExpectationNotMet
         nil
       end
+
+      private
+
+      def synced_resolve(query)
+        synchronize(query.wait) do
+          if (query.match == :smart or query.match == :prefer_exact)
+            result = query.resolve_for(self, true)
+            result = query.resolve_for(self, false) if result.empty? && query.supports_exact? && !query.exact?
+          else
+            result = query.resolve_for(self)
+          end
+
+          if query.match == :one or query.match == :smart and result.size > 1
+            raise Capybara::Ambiguous.new("Ambiguous match, found #{result.size} elements matching #{query.description}")
+          end
+          if result.empty?
+            raise Capybara::ElementNotFound.new("Unable to find #{query.description}")
+          end
+          result.first
+        end.tap(&:allow_reload!)
+      end
     end
   end
 end