capybara 3.21.0 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 260a1571a7fde6676b4d901b75e17035cd5c1b32b92f6c647e9d8ceadc78ae2a
-  data.tar.gz: d05339eac382154edea4059cf658c7cd828a75bd8b4570b9e85819f1641fad38
+  metadata.gz: 33bde7b48182b5c3dd5679c621882392d87bc8b9303cffabf963fe84186768b1
+  data.tar.gz: 4d9ccd2f5c45a87586f87f29f9df888af7102bf6e86042993c36ed858fc07537
 SHA512:
-  metadata.gz: ffb2ebe0f747c4519d50138f4575f07c4171b1d2bfaa978dab3f471cac9cf839e0e570b8c25b76185530960d6da42dcdb9a6f45c9ed50ebd605c5cf4da2a4da4
-  data.tar.gz: 24c034c08f20d051256444c46bb86e0ab8c8468c34e45e27bf95408074ffe1c305603d0034348582d6b719af36a08f3f88365ddcd0336ba14e8216de854034ef
+  metadata.gz: a128be647b867602954cc51cf603e020c3eceb938b5761766982a00e91fd0fccbc7aff02c49fc2c3064cdf489cc7a812c25818b5ca675ddf87c6a7a6822bd45a
+  data.tar.gz: 40d9831cc35bf0d1af71722718cea81ac2a075b5bbc067a89edb78e56572d8e0ad56455abd47b2b5ba3e0edd5b76ed4eb77de63255773e70cfd261bfa064092f

data/.yardopts

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

data/History.md

@@ -1,3 +1,17 @@
+# 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
 

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.21.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
@@ -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.rb

@@ -66,38 +66,44 @@ module Capybara
     #       config.app_host   = 'http://www.google.com'
     #     end
     #
-    # === Configurable options
-    #
-    # [app_host = String/nil]             The default host to use when giving a relative URL to visit, must be a valid URL e.g. http://www.example.com
-    # [always_include_port = Boolean]     Whether the Rack server's port should automatically be inserted into every visited URL unless another port is explicitly specified (Default: false)
-    # [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 {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 {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: :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 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
-    #
-    # when using capybara/dsl, the following options are also available:
-    #
-    # [default_driver = Symbol]           The name of the driver to use by default. (Default: :rack_test)
-    # [javascript_driver = Symbol]        The name of a driver to use for JavaScript enabled tests. (Default: :selenium)
+    # #### Configurable options
+    #
+    # - **allow_gumbo** (Boolean = `false`) - When `nokogumbo` is available, whether it will be used to parse HTML strings.
+    # - **always_include_port** (Boolean = `false`) - Whether the Rack server's port should automatically be inserted into every visited URL
+    #   unless another port is explicitly specified.
+    # - **app_host** (String, `nil`) - The default host to use when giving a relative URL to visit, must be a valid URL e.g. `http://www.example.com`.
+    # - **asset_host** (String = `nil`) - Where dynamic assets are hosted - will be prepended to relative asset locations if present.
+    # - **automatic_label_click** (Boolean = `false`) - 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.
+    # - **automatic_reload** (Boolean = `true`) - Whether to automatically reload elements as Capybara is waiting.
+    # - **default_max_wait_time** (Numeric = `2`) - The maximum number of seconds to wait for asynchronous processes to finish.
+    # - **default_normalize_ws** (Boolean = `false`) - Whether text predicates and matchers use normalize whitespace behavior.
+    # - **default_selector** (`:css`, `:xpath` = `:css`) - Methods which take a selector use the given type by default. See also {Capybara::Selector}.
+    # - **default_set_options** (Hash = `{}`) - The default options passed to {Capybara::Node::Element#set Element#set}.
+    # - **enable_aria_label** (Boolean = `false`) - Whether fields, links, and buttons will match against `aria-label` attribute.
+    # - **exact** (Boolean = `false`) - Whether locators are matched exactly or with substrings. Only affects selector conditions
+    #   written using the `XPath#is` method.
+    # - **exact_text** (Boolean = `false`) - Whether the text matchers and `:text` filter match exactly or on substrings.
+    # - **ignore_hidden_elements** (Boolean = `true`) - Whether to ignore hidden elements on the page.
+    # - **match** (`:one`, `:first`, `:prefer_exact`, `:smart` = `:smart`) - The matching strategy to find nodes.
+    # - **predicates_wait** (Boolean = `true`) - Whether Capybara's predicate matchers use waiting behavior by default.
+    # - **raise_server_errors** (Boolean = `true`) - Should errors raised in the server be raised in the tests?
+    # - **reuse_server** (Boolean = `true`) - Whether to reuse the server thread between multiple sessions using the same app object.
+    # - **run_server** (Boolean = `true`) - Whether to start a Rack server for the given Rack app.
+    # - **save_path** (String = `Dir.pwd`) - Where to put pages saved through {Capybara::Session#save_page save_page}, {Capybara::Session#save_screenshot save_screenshot},
+    #   {Capybara::Session#save_and_open_page save_and_open_page}, or {Capybara::Session#save_and_open_screenshot save_and_open_screenshot}.
+    # - **server** (Symbol = `:default` (which uses puma)) - The name of the registered server to use when running the app under test.
+    # - **server_errors** (Array\<Class> = `[Exception]`) - Error classes that should be raised in the tests if they are raised in the server
+    #   and {configure raise_server_errors} is `true`.
+    # - **test_id** (`Symbol`, `String`, `nil` = `nil`) - Optional attribute to match locator against with built-in selectors along with id.
+    # - **threadsafe** (Boolean = `false`) - Whether sessions can be configured individually.
+    #
+    # #### DSL Options
+    #
+    # When using `capybara/dsl`, the following options are also available:
+    #
+    # - **default_driver** (Symbol = `:rack_test`) - The name of the driver to use by default.
+    # - **javascript_driver** (Symbol = `:selenium`) - The name of a driver to use for JavaScript enabled tests.
     #
     def configure
       yield config

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

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|

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/node/finders.rb

@@ -5,21 +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.
       #
-      #  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 Capybara::Node::Finders#all)
+      # @param (see #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.
@@ -31,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
@@ -48,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
       #
@@ -73,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
       #
@@ -102,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
       #
@@ -117,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
@@ -133,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
@@ -151,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
       #
@@ -204,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")
       #
@@ -219,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
@@ -271,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.
       #