capybara 3.20.2 → 3.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c90b3d75d32ab14dc3dba7f6617938c7b6c716c7709cd8c36c40c5e72ccc7ec
-  data.tar.gz: c14e027664dba55e9c697f13aad46406250e39f67dcc5372b1b73370683b63ff
+  metadata.gz: 260a1571a7fde6676b4d901b75e17035cd5c1b32b92f6c647e9d8ceadc78ae2a
+  data.tar.gz: d05339eac382154edea4059cf658c7cd828a75bd8b4570b9e85819f1641fad38
 SHA512:
-  metadata.gz: 6ce927bbbb10d21cb51c4393775e8245b845ce819868963c8930f5f03d00655399036e1ae344df4e942102a690a98b57fcdecb95e05c14b22018818bcf7e2050
-  data.tar.gz: 332ac0bb550bdca14abe803b318cefff6b1df15eb021a67d3eff790c975be5f581ab9d19b1ebb501c98be3528c523ea6ee8e7df7e3fda2f85bf98b910520604e
+  metadata.gz: ffb2ebe0f747c4519d50138f4575f07c4171b1d2bfaa978dab3f471cac9cf839e0e570b8c25b76185530960d6da42dcdb9a6f45c9ed50ebd605c5cf4da2a4da4
+  data.tar.gz: 24c034c08f20d051256444c46bb86e0ab8c8468c34e45e27bf95408074ffe1c305603d0034348582d6b719af36a08f3f88365ddcd0336ba14e8216de854034ef

data/History.md

@@ -1,3 +1,17 @@
+# Version 3.21.0
+Release date: 2019-05-24
+
+### Added
+
+* Element#drop - Chrome and Firefox, via the selenium driver, support dropping files/data on elements
+* Default CSS used for `attach_file` `make_visible: true` now includes auto for
+  height and width to handle more ways of hiding the file input element
+* Documentation Updates and Fixes - Many thanks to Masafumi Koba! [Masafumi Koba]
+
+### Changed
+
+* Deprecate support for CSS locator being a Symbol
+
 # Version 3.20.2
 Release date: 2019-05-19
 

data/README.md

@@ -7,7 +7,7 @@
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jnicklas/capybara?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=capybara&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=capybara&package-manager=bundler&version-scheme=semver)
 
-**Note** You are viewing the README for the 3.20.x version of Capybara.
+**Note** You are viewing the README for the 3.21.x version of Capybara.
 
 
 Capybara helps you test web applications by simulating how a real user would
@@ -38,8 +38,6 @@ GitHub): http://groups.google.com/group/ruby-capybara
     - [RackTest](#racktest)
     - [Selenium](#selenium)
     - [Apparition](#apparition)
-    - [Capybara-webkit](#capybara-webkit)
-    - [Poltergeist](#poltergeist)
 - [The DSL](#the-dsl)
     - [Navigating](#navigating)
     - [Clicking links and buttons](#clicking-links-and-buttons)
@@ -59,11 +57,13 @@ GitHub): http://groups.google.com/group/ruby-capybara
 - [Using the DSL elsewhere](#using-the-dsl-elsewhere)
 - [Calling remote servers](#calling-remote-servers)
 - [Using sessions](#using-sessions)
+    - [Named sessions](#named-sessions)
+    - [Using sessions manually](#using-sessions-manually)
 - [XPath, CSS and selectors](#xpath-css-and-selectors)
 - [Beware the XPath // trap](#beware-the-xpath--trap)
 - [Configuring and adding drivers](#configuring-and-adding-drivers)
 - [Gotchas:](#gotchas)
-- ["Threadsafe" mode](#threadsafe)
+- ["Threadsafe" mode](#threadsafe-mode)
 - [Development](#development)
 
 ## <a name="key-benefits"></a>Key benefits

data/lib/capybara.rb

@@ -73,22 +73,24 @@ module Capybara
     # [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: [Exception])
+    # [server_errors = Array\<Class\>]    Error classes that should be raised in the tests if they are raised in the server and {configure raise_server_errors} is true (Default: [Exception])
     # [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)
+    # [automatic_label_click = Boolean]   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 (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: {})
+    # [server = Symbol]  The name of the registered server to use when running the app under test (Default: :default which uses puma)
+    # [default_set_options = Hash]  The default options passed to {Capybara::Node::Element#set Element#set} (Default: {})
     # [test_id = Symbol/String/nil] Optional attribute to match locator aginst with builtin selectors along with id (Default: nil)
-    # [predicates_wait = Boolean]  Whether Capybaras predicate matchers use waiting behavior by default (Default: true)
+    # [predicates_wait = Boolean]  Whether Capybara's predicate matchers use waiting behavior by default (Default: true)
     # [default_normalize_ws = Boolean] Whether text predicates and matchers use normalize whitespace behaviour (Default: false)
     # [allow_gumbo = Boolean] When `nokogumbo` is available, whether it will be used to parse HTML strings (Default: false)
+    # [match = :one/:first/:prefer_exact/:smart] The matching strategy to find nodes (Default: :smart)
+    # [exact_text = Boolean] Whether the text matchers and `:text` filter match exactly or on substrings (Default: false)
     #
     # === DSL Options
     #
@@ -201,15 +203,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>
@@ -297,7 +297,7 @@ 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
     #
@@ -340,7 +340,7 @@ module Capybara
 
     ##
     #
-    # Yield a block using a specific session name or Capybara::Session instance.
+    # Yield a block using a specific session name or {Capybara::Session} instance.
     #
     def using_session(name_or_session)
       previous_session_info = {

data/lib/capybara/driver/node.rb

@@ -69,6 +69,10 @@ module Capybara
         raise NotImplementedError
       end
 
+      def drop(*args)
+        raise NotImplementedError
+      end
+
       def scroll_by(x, y)
         raise NotImplementedError
       end

data/lib/capybara/helpers.rb

@@ -41,7 +41,7 @@ module Capybara
     ##
     #
     # Injects a `<base>` tag into the given HTML code, pointing to
-    # `Capybara.asset_host`.
+    # {Capybara.configure asset_host}.
     #
     # @param [String] html     HTML code to inject into
     # @param [URL] host (Capybara.asset_host) The host from which assets should be loaded

data/lib/capybara/minitest.rb

@@ -150,27 +150,27 @@ module Capybara
     # Assertion that there is xpath
     #
     # @!method assert_xpath
-    #   see Capybara::Node::Matchers#has_xpath?
+    #   see {Capybara::Node::Matchers#has_xpath?}
 
     ##
     # Assertion that there is no xpath
     #
     # @!method refute_xpath
     # @!method assert_no_xpath
-    #   see Capybara::Node::Matchers#has_no_xpath?
+    #   see {Capybara::Node::Matchers#has_no_xpath?}
 
     ##
     # Assertion that there is css
     #
     # @!method assert_css
-    #   see Capybara::Node::Matchers#has_css?
+    #   see {Capybara::Node::Matchers#has_css?}
 
     ##
     # Assertion that there is no css
     #
     # @!method refute_css
     # @!method assert_no_css
-    #   see Capybara::Node::Matchers#has_no_css?
+    #   see {Capybara::Node::Matchers#has_no_css?}
 
     ##
     # Assertion that there is link

data/lib/capybara/node/actions.rb

@@ -6,18 +6,19 @@ module Capybara
       # @!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}
+      #   expires. The length of time this method will wait is controlled through {Capybara.configure default_max_wait_time}.
       #
-      #   @option options [false, true, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
+      #   @option options [false, true, Numeric] wait
+      #     Maximum time to wait for matching element to appear. Defaults to {Capybara.configure default_max_wait_time}.
 
       ##
       #
-      # Finds a button or link and clicks it.  See {Capybara::Node::Actions#click_button} and
-      # {Capybara::Node::Actions#click_link} for what locator will match against for each type of element
+      # Finds a button or link and clicks it. See {#click_button} and
+      # {#click_link} for what locator will match against for each type of element.
       #
       # @overload click_link_or_button([locator], **options)
       #   @macro waiting_behavior
-      #   @param [String] locator      See {Capybara::Node::Actions#click_button} and {Capybara::Node::Actions#click_link}
+      #   @param [String] locator      See {#click_button} and {#click_link}
       #
       # @return [Capybara::Node::Element]  The element clicked
       #
@@ -28,13 +29,13 @@ module Capybara
 
       ##
       #
-      # Finds a link by id, Capybara.test_id attribute, text or title and clicks it. Also looks at image
+      # Finds a link by id, {Capybara.configure test_id} attribute, text or title and clicks it. Also looks at image
       # alt text inside the link.
       #
       # @overload click_link([locator], **options)
       #   @macro waiting_behavior
-      #   @param [String] locator         text, id, Capybara.test_id attribute, title or nested image's alt attribute
-      #   @param options                  See {Capybara::Node::Finders#find_link}
+      #   @param [String] locator         text, id, {Capybara.configure test_id} attribute, title or nested image's alt attribute
+      #   @param [Hash] options           See {Capybara::Node::Finders#find_link}
       #
       # @return [Capybara::Node::Element]  The element clicked
       def click_link(locator = nil, **options)
@@ -44,14 +45,14 @@ module Capybara
       ##
       #
       # Finds a button on the page and clicks it.
-      # 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.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 click_button([locator], **options)
       #   @macro waiting_behavior
       #   @param [String] locator      Which button to find
-      #   @param options     See {Capybara::Node::Finders#find_button}
+      #   @param [Hash] options        See {Capybara::Node::Finders#find_button}
       # @return [Capybara::Node::Element]  The element clicked
       def click_button(locator = nil, **options)
         find(:button, locator, options).click
@@ -59,9 +60,9 @@ module Capybara
 
       ##
       #
-      # Locate a text field or text area and fill it in with the given text
-      # The field can be found via its name, id, Capybara.test_id attribute, or label text.
-      # If no locator is provided will operate on self or a descendant
+      # Locate a text field or text area and fill it in with the given text.
+      # The field can be found via its name, id, {Capybara.configure test_id} attribute, or label text.
+      # If no locator is provided this will operate on self or a descendant.
       #
       #     # will fill in a descendant fillable field with name, id, or label text matching 'Name'
       #     page.fill_in 'Name', with: 'Bob'
@@ -73,7 +74,7 @@ module Capybara
       # @overload fill_in([locator], with:, **options)
       #   @param [String] locator                 Which field to fill in
       #   @param [Hash] options
-      #   @param with: [String]                  The value to fill_in
+      #   @param with: [String]                  The value to fill in
       #   @macro waiting_behavior
       #   @option options [String] currently_with The current value property of the field to fill in
       #   @option options [Boolean] multiple      Match fields that can have multiple values?
@@ -81,9 +82,9 @@ module Capybara
       #   @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) provided
-      #   @option options [Hash] fill_options     Driver specific options regarding how to fill fields (Defaults come from Capybara.default_set_options)
+      #   @option options [Hash] fill_options     Driver specific options regarding how to fill fields (Defaults come from {Capybara.configure default_set_options})
       #
-      # @return [Capybara::Node::Element]  The element filled_in
+      # @return [Capybara::Node::Element]  The element filled in
       def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **find_options)
         find_options[:with] = currently_with if currently_with
         find_options[:allow_self] = true if locator.nil?
@@ -91,7 +92,8 @@ module Capybara
       end
 
       # @!macro label_click
-      #   @option options [Boolean] allow_label_click (Capybara.automatic_label_click) Attempt to click the label to toggle state if element is non-visible.
+      #   @option options [Boolean] allow_label_click
+      #     Attempt to click the label to toggle state if element is non-visible. Defaults to {Capybara.configure automatic_label_click}.
 
       ##
       #
@@ -178,10 +180,10 @@ module Capybara
 
       ##
       #
-      # If `:from` option is present, `select` finds a select box, or text input with associated datalist,
+      # If `from` option is present, {#select} finds a select box, or text input with associated datalist,
       # on the page and selects a particular option from it.
       # Otherwise it finds an option inside current scope and selects it.
-      # If the select box is a multiple select, +select+ can be called multiple times to select more than
+      # If the select box is a multiple select, {#select} can be called multiple times to select more than
       # one option.
       # The select box can be found via its name, id or label text. The option can be found by its text.
       #
@@ -191,7 +193,7 @@ module Capybara
       #   @macro waiting_behavior
       #
       #   @param value [String] Which option to select
-      #   @param from [String]  The id, Capybara.test_id attribute, name or label of the select box
+      #   @param from [String]  The id, {Capybara.configure test_id} attribute, name or label of the select box
       #
       # @return [Capybara::Node::Element]  The option element selected
       def select(value = nil, from: nil, **options)
@@ -209,7 +211,7 @@ module Capybara
       ##
       #
       # Find a select box on the page and unselect a particular option from it. If the select
-      # box is a multiple select, +unselect+ can be called multiple times to unselect more than
+      # box is a multiple select, {#unselect} can be called multiple times to unselect more than
       # one option. The select box can be found via its name, id or label text.
       #
       #     page.unselect 'March', from: 'Month'
@@ -218,7 +220,7 @@ module Capybara
       #   @macro waiting_behavior
       #
       #   @param value [String]     Which option to unselect
-      #   @param from [String]      The id, Capybara.test_id attribute, name or label of the select box
+      #   @param from [String]      The id, {Capybara.configure test_id} attribute, name or label of the select box
       #
       #
       # @return [Capybara::Node::Element]  The option element unselected
@@ -232,7 +234,7 @@ module Capybara
       ##
       #
       # Find a descendant file field on the page and attach a file given its path. There are two ways to use
-      # `attach_file`, in the first method the file field can be found via its name, id or label text.
+      # {#attach_file}, in the first method the file field can be found via its name, id or label text.
       # In the case of the file field being hidden for
       # styling reasons the `make_visible` option can be used to temporarily change the CSS of
       # the file field, attach the file, and then revert the CSS back to original. If no locator is
@@ -257,13 +259,16 @@ module Capybara
       #   @param [String] locator                  Which field to attach the file to
       #   @param [String, Array<String>] paths     The path(s) of the file(s) that will be attached
       #
-      #   @option options [Symbol] match (Capybara.match)     The matching strategy to use (:one, :first, :prefer_exact, :smart).
-      #   @option options [Boolean] exact (Capybara.exact)    Match the exact label name/contents or accept a partial match.
+      #   @option options [Symbol] match
+      #     The matching strategy to use (:one, :first, :prefer_exact, :smart). Defaults to {Capybara.configure match}.
+      #   @option options [Boolean] exact
+      #     Match the exact label name/contents or accept a partial match. Defaults to {Capybara.configure exact}.
       #   @option options [Boolean] multiple Match field which allows multiple file selection
       #   @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, Array<String>, Regexp] class    Match fields that match the class(es) provided
-      #   @option options [true, Hash] make_visible   A Hash of CSS styles to change before attempting to attach the file, if `true` { opacity: 1, display: 'block', visibility: 'visible' } is used (may not be supported by all drivers)
+      #   @option options [true, Hash] make_visible
+      #     A Hash of CSS styles to change before attempting to attach the file, if `true`, `{ opacity: 1, display: 'block', visibility: 'visible' }` is used (may not be supported by all drivers).
       # @overload attach_file(paths, &blk)
       #   @param [String, Array<String>] paths     The path(s) of the file(s) that will be attached
       #   @yield Block whose actions will trigger the system file chooser to be shown
@@ -326,7 +331,9 @@ module Capybara
       end
 
       def while_visible(element, visible_css)
-        visible_css = { opacity: 1, display: 'block', visibility: 'visible' } if visible_css == true
+        if visible_css == true
+          visible_css = { opacity: 1, display: 'block', visibility: 'visible', width: 'auto', height: 'auto' }
+        end
         _update_style(element, visible_css)
         raise ExpectationNotMet, 'The style changes in :make_visible did not make the file input visible' unless element.visible?
 

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