capybara 3.20.2 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c90b3d75d32ab14dc3dba7f6617938c7b6c716c7709cd8c36c40c5e72ccc7ec
-  data.tar.gz: c14e027664dba55e9c697f13aad46406250e39f67dcc5372b1b73370683b63ff
+  metadata.gz: 33bde7b48182b5c3dd5679c621882392d87bc8b9303cffabf963fe84186768b1
+  data.tar.gz: 4d9ccd2f5c45a87586f87f29f9df888af7102bf6e86042993c36ed858fc07537
 SHA512:
-  metadata.gz: 6ce927bbbb10d21cb51c4393775e8245b845ce819868963c8930f5f03d00655399036e1ae344df4e942102a690a98b57fcdecb95e05c14b22018818bcf7e2050
-  data.tar.gz: 332ac0bb550bdca14abe803b318cefff6b1df15eb021a67d3eff790c975be5f581ab9d19b1ebb501c98be3528c523ea6ee8e7df7e3fda2f85bf98b910520604e
+  metadata.gz: a128be647b867602954cc51cf603e020c3eceb938b5761766982a00e91fd0fccbc7aff02c49fc2c3064cdf489cc7a812c25818b5ca675ddf87c6a7a6822bd45a
+  data.tar.gz: 40d9831cc35bf0d1af71722718cea81ac2a075b5bbc067a89edb78e56572d8e0ad56455abd47b2b5ba3e0edd5b76ed4eb77de63255773e70cfd261bfa064092f

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/History.md

@@ -1,3 +1,31 @@
+# Version 3.22.0
+Release date: 2019-05-29
+
+### Added
+
+* `ancestor`/`sibling` assertions and matchers added
+* Documentation Updates and Fixes - Many thanks again to Masafumi Koba! [Masafumi Koba]
+* Added `:with` alias for `:option` filter on `:checkbox` and `:radio_button` selectors
+
+### Changed
+
+* Selenium driver with Chrome >= 73 now resets cookies and local/session storage after navigating
+  to 'about:blank' when possible to minimize potential race condition
+
+# 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.22.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
@@ -925,12 +925,17 @@ Capybara.default_selector = :xpath
 find('.//ul/li').text
 ```
 
-Capybara allows you to add custom selectors, which can be very useful if you
-find yourself using the same kinds of selectors very often:
+Capybara provides a number of other built-in selector types. The full list, along
+with applicable filters, can be seen at [built-in selectors](https://www.rubydoc.info/github/teamcapybara/capybara/Capybara/Selector)
+
+Capybara also allows you to add custom selectors, which can be very useful if you
+find yourself using the same kinds of selectors very often. The examples below are very
+simple, and there are many available features not demonstrated. For more in-depth examples
+please see Capybaras built-in selector definitions.
 
 ```ruby
-Capybara.add_selector(:id) do
-  xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+Capybara.add_selector(:my_attribute) do
+  xpath { |id| XPath.descendant[XPath.attr(:my_attribute) == id.to_s] }
 end
 
 Capybara.add_selector(:row) do
@@ -947,9 +952,9 @@ an XPath expression generated through the XPath gem. You can now use these
 selectors like this:
 
 ```ruby
-find(:id, 'post_123')
-find(:row, 3)
-find(:flash_type, :notice)
+find(:my_attribute, 'post_123') # find element with matching attribute
+find(:row, 3) # find 3rd row in table body
+find(:flash_type, :notice) # find element with id of 'flash' and class of 'notice'
 ```
 
 ## <a name="beware-the-xpath--trap"></a>Beware the XPath // trap

data/lib/capybara/driver/node.rb

@@ -31,8 +31,8 @@ module Capybara
         raise NotImplementedError
       end
 
-      # @param value String or Array. Array is only allowed if node has 'multiple' attribute
-      # @param options [Hash{}] Driver specific options for how to set a value on a node
+      # @param value [String, Array] Array is only allowed if node has 'multiple' attribute
+      # @param options [Hash] Driver specific options for how to set a value on a node
       def set(value, **options)
         raise NotImplementedError
       end
@@ -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/spec.rb

@@ -11,13 +11,14 @@ module Capybara
       end
 
       # rubocop:disable Style/MultilineBlockChain
-      (%w[selector xpath css link button field select table checked_field unchecked_field].flat_map do |assertion|
-        [%W[assert_#{assertion} must_have_#{assertion}],
-         %W[refute_#{assertion} wont_have_#{assertion}]]
-      end + [%w[assert_all_of_selectors must_have_all_of_selectors],
-             %w[assert_none_of_selectors must_have_none_of_selectors],
-             %w[assert_any_of_selectors must_have_any_of_selectors],
-             %w[assert_matches_style must_match_style]] +
+      (%w[selector xpath css link button field select table checked_field unchecked_field
+          ancestor sibling].flat_map do |assertion|
+            [%W[assert_#{assertion} must_have_#{assertion}],
+             %W[refute_#{assertion} wont_have_#{assertion}]]
+          end + [%w[assert_all_of_selectors must_have_all_of_selectors],
+                 %w[assert_none_of_selectors must_have_none_of_selectors],
+                 %w[assert_any_of_selectors must_have_any_of_selectors],
+                 %w[assert_matches_style must_match_style]] +
       %w[selector xpath css].flat_map do |assertion|
         [%W[assert_matches_#{assertion} must_match_#{assertion}],
          %W[refute_matches_#{assertion} wont_match_#{assertion}]]
@@ -178,6 +179,18 @@ module Capybara
       #
       # @!method must_match_style
       #   see {Capybara::Node::Matchers#assert_matches_style}
+
+      ##
+      # Expectation that there is an ancestor
+      #
+      # @!method must_have_ancestor
+      #   see Capybara::Node::Matchers#has_ancestor?
+
+      ##
+      # Expectation that there is a sibling
+      #
+      # @!method must_have_sibling
+      #   see Capybara::Node::Matchers#has_sibling?
     end
   end
 end

data/lib/capybara/minitest.rb

@@ -86,9 +86,20 @@ module Capybara
       # @!method assert_matches_style
       #   see {Capybara::Node::Matchers#assert_matches_style}
 
+      ## Assert element has a matching sibling
+      #
+      # @!method assert_sibling
+      #   see {Capybara::Node::Matchers#assert_sibling}
+
+      ## Assert element has a matching ancestor
+      #
+      # @!method assert_ancestor
+      #   see {Capybara::Node::Matchers#assert_ancestor}
+
       %w[selector no_selector matches_style
          all_of_selectors none_of_selectors any_of_selectors
-         matches_selector not_matches_selector].each do |assertion_name|
+         matches_selector not_matches_selector
+         sibling no_sibling ancestor no_ancestor].each do |assertion_name|
         class_eval <<-ASSERTION, __FILE__, __LINE__ + 1
           def assert_#{assertion_name} *args, &optional_filter_block
             self.assertions +=1
@@ -102,6 +113,8 @@ module Capybara
 
       alias_method :refute_selector, :assert_no_selector
       alias_method :refute_matches_selector, :assert_not_matches_selector
+      alias_method :refute_ancestor, :assert_no_ancestor
+      alias_method :refute_sibling, :assert_no_sibling
 
       %w[xpath css link button field select table].each do |selector_type|
         define_method "assert_#{selector_type}" do |*args, &optional_filter_block|
@@ -150,27 +163,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?