capybara 3.20.1 → 3.22.0

data/lib/capybara/node/element.rb

@@ -43,7 +43,7 @@ module Capybara
 
       ##
       #
-      # Retrieve the text of the element. If `Capybara.ignore_hidden_elements`
+      # Retrieve the text of the element. If {Capybara.configure ignore_hidden_elements}
       # is `true`, which it is by default, then this will return only text
       # which is visible. The exact semantics of this may differ between
       # drivers, but generally any text within elements with `display:none` is
@@ -61,7 +61,7 @@ module Capybara
 
       ##
       #
-      # Retrieve the given attribute
+      # Retrieve the given attribute.
       #
       #     element[:title] # => HTML title attribute
       #
@@ -74,7 +74,7 @@ module Capybara
 
       ##
       #
-      # Retrieve the given CSS styles
+      # Retrieve the given CSS styles.
       #
       #     element.style('color', 'font-size') # => Computed values of CSS 'color' and 'font-size' styles
       #
@@ -109,7 +109,7 @@ module Capybara
       # Set the value of the form element to the given value.
       #
       # @param [String] value    The new value
-      # @param [Hash{}] options  Driver specific options for how to set the value. Take default values from `Capybara#default_set_options` - See {Capybara::configure}
+      # @param [Hash] options    Driver specific options for how to set the value. Take default values from {Capybara.configure default_set_options}.
       #
       # @return [Capybara::Node::Element]  The element
       def set(value, **options)
@@ -122,8 +122,15 @@ module Capybara
 
       ##
       #
-      # Select this node if is an option element inside a select tag
+      # Select this node if it is an option element inside a select tag.
       #
+      # @!macro action_waiting_behavior
+      #   If the driver dynamic pages (JS) and the element is currently non-interactable, this method will
+      #   continuously retry the action until either the element becomes interactable or the maximum
+      #   wait time expires.
+      #
+      #   @param [false, Numeric] wait
+      #     Maximum time to wait for the action to succeed. Defaults to {Capybara.configure default_max_wait_time}.
       # @return [Capybara::Node::Element]  The element
       def select_option(wait: nil)
         synchronize(wait) { base.select_option }
@@ -132,8 +139,9 @@ module Capybara
 
       ##
       #
-      # Unselect this node if is an option element inside a multiple select tag
+      # Unselect this node if it is an option element inside a multiple select tag.
       #
+      # @macro action_waiting_behavior
       # @return [Capybara::Node::Element]  The element
       def unselect_option(wait: nil)
         synchronize(wait) { base.unselect_option }
@@ -142,11 +150,12 @@ module Capybara
 
       ##
       #
-      # Click the Element
+      # Click the Element.
       #
+      # @macro action_waiting_behavior
       # @!macro click_modifiers
-      #   Both x: and y: must be specified if an offset is wanted, if not specified the click will occur at the middle of the element
-      #   @overload $0(*modifier_keys, **offset)
+      #   Both x: and y: must be specified if an offset is wanted, if not specified the click will occur at the middle of the element.
+      #   @overload $0(*modifier_keys, wait: nil, **offset)
       #     @param *modifier_keys [:alt, :control, :meta, :shift] ([]) Keys to be held down when clicking
       #     @option offset [Integer] x  X coordinate to offset the click location from the top left corner of the element
       #     @option offset [Integer] y  Y coordinate to offset the click location from the top left corner of the element
@@ -160,8 +169,9 @@ module Capybara
 
       ##
       #
-      # Right Click the Element
+      # Right Click the Element.
       #
+      # @macro action_waiting_behavior
       # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
       def right_click(*keys, wait: nil, **offset)
@@ -173,8 +183,9 @@ module Capybara
 
       ##
       #
-      # Double Click the Element
+      # Double Click the Element.
       #
+      # @macro action_waiting_behavior
       # @macro click_modifiers
       # @return [Capybara::Node::Element]  The element
       def double_click(*keys, wait: nil, **offset)
@@ -186,7 +197,7 @@ module Capybara
 
       ##
       #
-      # Send Keystrokes to the Element
+      # Send Keystrokes to the Element.
       #
       # @overload send_keys(keys, ...)
       #   @param keys [String, Symbol, Array<String,Symbol>]
@@ -194,65 +205,65 @@ module Capybara
       # Examples:
       #
       #     element.send_keys "foo"                     #=> value: 'foo'
-      #     element.send_keys "tet", :left, "s"   #=> value: 'test'
+      #     element.send_keys "tet", :left, "s"         #=> value: 'test'
       #     element.send_keys [:control, 'a'], :space   #=> value: ' ' - assuming ctrl-a selects all contents
       #
-      # Symbols supported for keys
-      # :cancel
-      # :help
-      # :backspace
-      # :tab
-      # :clear
-      # :return
-      # :enter
-      # :shift
-      # :control
-      # :alt
-      # :pause
-      # :escape
-      # :space
-      # :page_up
-      # :page_down
-      # :end
-      # :home
-      # :left
-      # :up
-      # :right
-      # :down
-      # :insert
-      # :delete
-      # :semicolon
-      # :equals
-      # :numpad0
-      # :numpad1
-      # :numpad2
-      # :numpad3
-      # :numpad4
-      # :numpad5
-      # :numpad6
-      # :numpad7
-      # :numpad8
-      # :numpad9
-      # :multiply      - numeric keypad *
-      # :add           - numeric keypad +
-      # :separator     - numeric keypad 'separator' key ??
-      # :subtract      - numeric keypad -
-      # :decimal       - numeric keypad .
-      # :divide        - numeric keypad /
-      # :f1
-      # :f2
-      # :f3
-      # :f4
-      # :f5
-      # :f6
-      # :f7
-      # :f8
-      # :f9
-      # :f10
-      # :f11
-      # :f12
-      # :meta
-      # :command      - alias of :meta
+      # Symbols supported for keys:
+      # * :cancel
+      # * :help
+      # * :backspace
+      # * :tab
+      # * :clear
+      # * :return
+      # * :enter
+      # * :shift
+      # * :control
+      # * :alt
+      # * :pause
+      # * :escape
+      # * :space
+      # * :page_up
+      # * :page_down
+      # * :end
+      # * :home
+      # * :left
+      # * :up
+      # * :right
+      # * :down
+      # * :insert
+      # * :delete
+      # * :semicolon
+      # * :equals
+      # * :numpad0
+      # * :numpad1
+      # * :numpad2
+      # * :numpad3
+      # * :numpad4
+      # * :numpad5
+      # * :numpad6
+      # * :numpad7
+      # * :numpad8
+      # * :numpad9
+      # * :multiply      - numeric keypad *
+      # * :add           - numeric keypad +
+      # * :separator     - numeric keypad 'separator' key ??
+      # * :subtract      - numeric keypad -
+      # * :decimal       - numeric keypad .
+      # * :divide        - numeric keypad /
+      # * :f1
+      # * :f2
+      # * :f3
+      # * :f4
+      # * :f5
+      # * :f6
+      # * :f7
+      # * :f8
+      # * :f9
+      # * :f10
+      # * :f11
+      # * :f12
+      # * :meta
+      # * :command      - alias of :meta
       #
       # @return [Capybara::Node::Element]  The element
       def send_keys(*args)
@@ -262,7 +273,7 @@ module Capybara
 
       ##
       #
-      # Hover on the Element
+      # Hover on the Element.
       #
       # @return [Capybara::Node::Element]  The element
       def hover
@@ -276,7 +287,7 @@ module Capybara
       #
       def tag_name
         # Element type is immutable so cache it
-        @tag_name ||= synchronize { base.tag_name }
+        @tag_name ||= initial_cache[:tag_name] || synchronize { base.tag_name }
       end
 
       ##
@@ -353,7 +364,7 @@ module Capybara
 
       ##
       #
-      # An XPath expression describing where on the page the element can be found
+      # An XPath expression describing where on the page the element can be found.
       #
       # @return [String]      An XPath expression
       #
@@ -394,17 +405,41 @@ module Capybara
 
       ##
       #
-      # Scroll the page or element
+      # Drop items on the current element.
+      #
+      #     target = page.find('#foo')
+      #     target.drop('/some/path/file.csv')
+      #
+      # @overload drop(path, ...)
+      #   @param [String, #to_path] path Location of the file to drop on the element
+      #
+      # @overload drop(strings, ...)
+      #   @param [Hash] strings A hash of type to data to be dropped - `{ "text/url" => "https://www.google.com" }`
+      #
+      # @return [Capybara::Node::Element]  The element
+      def drop(*args)
+        options = args.map do |arg|
+          return arg.to_path if arg.respond_to?(:to_path)
+
+          arg
+        end
+        synchronize { base.drop(*options) }
+        self
+      end
+
+      ##
+      #
+      # Scroll the page or element.
       #
-      # Scroll the page or element to its top, bottom or middle
       # @overload scroll_to(position, offset: [0,0])
+      #   Scroll the page or element to its top, bottom or middle.
       #   @param [:top, :bottom, :center, :current] position
-      #   @param :offset
+      #   @param [[Integer, Integer]] offset
       #
-      # Scroll the page or current element until the given element is aligned at the top, bottom, or center of it
       # @overload scroll_to(element, align: :top)
+      #   Scroll the page or current element until the given element is aligned at the top, bottom, or center of it.
       #   @param [Capybara::Node::Element] element   The element to be scrolled into view
-      #   @param [:top, :bottom, :center] :align Where to align the element being scrolled into view with relation to the current page/element if possible
+      #   @param [:top, :bottom, :center] align Where to align the element being scrolled into view with relation to the current page/element if possible
       #
       # @overload scroll_to(x,y)
       #   @param [Integer] x    Horizontal scroll offset
@@ -427,11 +462,11 @@ module Capybara
       ##
       #
       # Execute the given JS in the context of the element not returning a result. This is useful for scripts that return
-      # complex objects, such as jQuery statements. +execute_script+ should be used over
-      # +evaluate_script+ whenever possible. `this` in the script will refer to the element this is called on.
+      # complex objects, such as jQuery statements. {#execute_script} should be used over
+      # {#evaluate_script} whenever a result is not expected or needed. `this` in the script will refer to the element this is called on.
       #
       # @param [String] script   A string of JavaScript to execute
-      # @param args  Optional arguments that will be passed to the script.  Driver support for this is optional and types of objects supported may differ between drivers
+      # @param args  Optional arguments that will be passed to the script. Driver support for this is optional and types of objects supported may differ between drivers
       #
       def execute_script(script, *args)
         session.execute_script(<<~JS, self, *args)
@@ -444,7 +479,7 @@ module Capybara
       ##
       #
       # Evaluate the given JS in the context of the element and return the result. Be careful when using this with
-      # scripts that return complex objects, such as jQuery statements. +execute_script+ might
+      # scripts that return complex objects, such as jQuery statements. {#execute_script} might
       # be a better alternative. `this` in the script will refer to the element this is called on.
       #
       # @param  [String] script   A string of JavaScript to evaluate
@@ -462,7 +497,7 @@ module Capybara
       #
       # Evaluate the given JavaScript in the context of the element and obtain the result from a
       # callback function which will be passed as the last argument to the script. `this` in the
-      # script will refer to the element this is called on
+      # script will refer to the element this is called on.
       #
       # @param  [String] script   A string of JavaScript to evaluate
       # @return [Object]          The result of the evaluated JavaScript (may be driver specific)
@@ -475,6 +510,7 @@ module Capybara
         JS
       end
 
+      # @api private
       def reload
         if @allow_reload
           begin
@@ -487,6 +523,11 @@ module Capybara
         self
       end
 
+      ##
+      #
+      # A human-readable representation of the element.
+      #
+      # @return [String]  A string representation
       def inspect
         %(#<Capybara::Node::Element tag="#{base.tag_name}" path="#{base.path}">)
       rescue NotSupportedByDriverError

data/lib/capybara/node/finders.rb

@@ -5,26 +5,25 @@ module Capybara
     module Finders
       ##
       #
-      # Find an {Capybara::Node::Element} based on the given arguments. +find+ will raise an error if the element
+      # Find an {Capybara::Node::Element} based on the given arguments. {#find} will raise an error if the element
       # is not found.
       #
-      # @!macro waiting_behavior
-      #   If the driver is capable of executing JavaScript, this method will wait for a set amount of time
-      #   and continuously retry finding the element until either the element is found or the time
-      #   expires. The length of time +find+ will wait is controlled through {Capybara.default_max_wait_time}
-      #   and defaults to 2 seconds.
-      #   @option options [false, true, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
+      #     page.find('#foo').find('.bar')
+      #     page.find(:xpath, './/div[contains(., "bar")]')
+      #     page.find('li', text: 'Quox').click_link('Delete')
       #
-      #  page.find('#foo').find('.bar')
-      #  page.find(:xpath, './/div[contains(., "bar")]')
-      #  page.find('li', text: 'Quox').click_link('Delete')
+      # @param (see #all)
       #
-      # @param (see Capybara::Node::Finders#all)
+      # @macro waiting_behavior
       #
       # @!macro system_filters
       #   @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 elements contained text must match exactly, when Boolean controls whether the :text option must match exactly
-      #   @option options [Boolean] normalize_ws (Capybara.default_normalize_ws)  Whether the `text`/`exact_text` options are compared against elment text with whitespace normalized or as returned by the driver
+      #   @option options [String, Boolean] exact_text
+      #     When String the elements contained text must match exactly, when Boolean controls whether the `text` option must match exactly.
+      #     Defaults to {Capybara.configure exact_text}.
+      #   @option options [Boolean] normalize_ws
+      #     Whether the `text`/`exact_text` options are compared against elment text with whitespace normalized or as returned by the driver.
+      #     Defaults to {Capybara.configure default_normalize_ws}.
       #   @option options [Boolean, Symbol] visible  Only find elements with the specified visibility:
       #                                              * true - only finds visible elements.
       #                                              * false - finds invisible _and_ visible elements.
@@ -36,12 +35,14 @@ module Capybara
       #                                       * false - only find elements whose centerpoint is in the viewport and is not obscured by other non-descendant elements.
       #   @option options [String, Regexp]  id           Only find elements with an id that matches the value passed
       #   @option options [String, Array<String>, Regexp] class  Only find elements with matching class/classes.
-      #                                            + Absence of a class can be checked by prefixing the class name with !
-      #                                            + If you need to check for existence of a class name that starts with ! then prefix with !!
-      #                                            + ```class:['a', '!b', '!!!c'] # limit to elements with class 'a' and '!c' but not class 'b'```
+      #                                            * Absence of a class can be checked by prefixing the class name with `!`
+      #                                            * If you need to check for existence of a class name that starts with `!` then prefix with `!!`
+      #
+      #                                                class:['a', '!b', '!!!c'] # limit to elements with class 'a' and '!c' but not class 'b'
+      #
       #   @option options [String, Regexp, Hash] style  Only find elements with matching style. String and Regexp will be checked against text of the elements `style` attribute, while a Hash will be compared against the elements full style
-      #   @option options [Boolean] exact            Control whether `is` expressions in the given XPath match exactly or partially
-      # @option options [Symbol] match        The matching strategy to use.
+      #   @option options [Boolean] exact            Control whether `is` expressions in the given XPath match exactly or partially. Defaults to {Capybara.configure exact}.
+      #   @option options [Symbol] match        The matching strategy to use. Defaults to {Capybara.configure match}.
       #
       # @return [Capybara::Node::Element]      The found element
       # @raise  [Capybara::ElementNotFound]    If the element can't be found before time expires
@@ -53,21 +54,19 @@ module Capybara
 
       ##
       #
-      # 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.
+      # 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+.
+      # {#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)
+      # @param (see #find)
       #
       # @macro waiting_behavior
       #
-      # @option options [Symbol] 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
       #
@@ -78,22 +77,19 @@ module Capybara
 
       ##
       #
-      # 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.
-      #
+      # 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+.
+      # {#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)
+      # @param (see #find)
       #
       # @macro waiting_behavior
       #
-      # @option options [Symbol] 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
       #
@@ -107,7 +103,7 @@ module Capybara
       # Find a form field on the page. The field can be found by its name, id or label text.
       #
       # @overload find_field([locator], **options)
-      #   @param [String] locator             name, id, Capybara.test_id attribute, placeholder or text of associated label element
+      #   @param [String] locator             name, id, {Capybara.configure test_id} attribute, placeholder or text of associated label element
       #
       #   @macro waiting_behavior
       #
@@ -122,13 +118,12 @@ module Capybara
       #   @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, Regexp] id             Match fields that match the id attribute
+      #   @option options [String, Regexp] 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>, Regexp] class Match fields that match the class(es) passed
       # @return [Capybara::Node::Element]   The found element
       #
-
       def find_field(locator = nil, **options, &optional_filter_block)
         find(:field, locator, options, &optional_filter_block)
       end
@@ -138,12 +133,12 @@ module Capybara
       # Find a link on the page. The link can be found by its id or text.
       #
       # @overload find_link([locator], **options)
-      #   @param [String] locator            id, Capybara.test_id attribute, title, text, or alt of enclosed img element
+      #   @param [String] locator            id, {Capybara.configure test_id} attribute, title, text, or alt of enclosed img element
       #
       #   @macro waiting_behavior
       #
-      #   @option options [String,Regexp,nil] href        Value to match against the links href, if nil finds link placeholders (<a> elements with no href attribute), if false ignores the href
-      #   @option options [String, Regexp] id                 Match links with the id provided
+      #   @option options [String,Regexp,nil] href    Value to match against the links href, if `nil` finds link placeholders (`<a>` elements with no href attribute), if `false` ignores the href
+      #   @option options [String, Regexp] 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>, Regexp] class    Match links that match the class(es) provided
@@ -156,14 +151,12 @@ module Capybara
       ##
       #
       # Find a button on the page.
-      # 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, name, Capbyara.test_id attribute, value, or title. \<button> elements can also be found
-      # by their text content, and image \<input> elements by their alt attribute
+      # 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, name, {Capybara.configure test_id} attribute, value, or title.
+      # `<button>` elements can also be found by their text content, and image `<input>` elements by their alt attribute.
       #
       # @overload find_button([locator], **options)
-      #   @param [String] locator            id, name, Capybara.test_id attribute, value, title, text content, alt of image
-      #
-      #   @overload find_button(**options)
+      #   @param [String] locator            id, name, {Capybara.configure test_id} attribute, value, title, text content, alt of image
       #
       #   @macro waiting_behavior
       #
@@ -209,9 +202,8 @@ module Capybara
       #     page.all(:css, 'a#person_123')
       #     page.all(:xpath, './/a[@id="person_123"]')
       #
-      #
       # If the type of selector is left out, Capybara uses
-      # {Capybara.default_selector}. It's set to :css by default.
+      # {Capybara.configure default_selector}. It's set to `:css` by default.
       #
       #     page.all("a#person_123")
       #
@@ -224,28 +216,25 @@ module Capybara
       #     page.all('a', text: 'Home')
       #     page.all('#menu li', visible: true)
       #
-      # By default Capybara's waiting behavior will wait up to `Capybara.default_max_wait_time`
+      # By default Capybara's waiting behavior will wait up to {Capybara.configure default_max_wait_time}
       # seconds for matching elements to be available and then return an empty result if none
       # are available. It is possible to set expectations on the number of results located and
       # Capybara will raise an exception if the number of elements located don't satisfy the
-      # specified conditions.  The expectations can be set using
+      # specified conditions. 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)
       #
-      # See {Capybara::Helpers#matches_count?} for additional information about
-      # count matching.
-      #
-      # @param [Symbol] kind                       Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
+      # @param [Symbol] kind                       Optional selector type (:css, :xpath, :field, etc.). Defaults to {Capybara.configure default_selector}.
       # @param [String] locator                    The locator for the specified selector
       # @macro system_filters
+      # @macro waiting_behavior
       # @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 [false, true, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
       # @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
@@ -276,7 +265,7 @@ module Capybara
       ##
       #
       # Find the first element on the page matching the given selector
-      # and options. By default `first` will wait up to `Capybara.default_max_wait_time`
+      # and options. By default {#first} will wait up to {Capybara.configure default_max_wait_time}
       # seconds for matching elements to appear and then raise an error if no matching
       # element is found, or `nil` if the provided count options allow for empty results.
       #