Improve `Capybara::Node::Finders` API doc (#2204) [ci skip]

* Improve `Capybara::Node::Finders` API doc

- Fix plain-text or broken links (references).
- Remove duplicate descriptions about method options or parameters.
- Fix a bit broken formats of text at some places.
- Remove useless description about `Capybara::Result#matches_count?`
- Fix indentation of code block for Markdown style [ci skip]
This commit is contained in:
Masafumi Koba 2019-05-27 06:24:32 +09:00 committed by Thomas Walpole
parent 4d9a38805a
commit 1963073b70
1 changed files with 41 additions and 47 deletions

View File

@ -5,21 +5,25 @@ module Capybara
module Finders 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. # is not found.
# #
# page.find('#foo').find('.bar') # page.find('#foo').find('.bar')
# page.find(:xpath, './/div[contains(., "bar")]') # page.find(:xpath, './/div[contains(., "bar")]')
# page.find('li', text: 'Quox').click_link('Delete') # page.find('li', text: 'Quox').click_link('Delete')
# #
# @param (see Capybara::Node::Finders#all) # @param (see #all)
# #
# @macro waiting_behavior # @macro waiting_behavior
# #
# @!macro system_filters # @!macro system_filters
# @option options [String, Regexp] text Only find elements which contain this text or match this regexp # @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 [String, Boolean] exact_text
# @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 # 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: # @option options [Boolean, Symbol] visible Only find elements with the specified visibility:
# * true - only finds visible elements. # * true - only finds visible elements.
# * false - finds invisible _and_ 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. # * 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, 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. # @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 ! # * 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 !! # * 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'``` #
# 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 [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 [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. # @option options [Symbol] match The matching strategy to use. Defaults to {Capybara.configure match}.
# #
# @return [Capybara::Node::Element] The found element # @return [Capybara::Node::Element] The found element
# @raise [Capybara::ElementNotFound] If the element can't be found before time expires # @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 # Find an {Capybara::Node::Element} based on the given arguments that is also an ancestor of the element called on.
# is not found. # {#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('#foo').find('.bar')
# element.ancestor(:xpath, './/div[contains(., "bar")]') # element.ancestor(:xpath, './/div[contains(., "bar")]')
# element.ancestor('ul', text: 'Quox').click_link('Delete') # element.ancestor('ul', text: 'Quox').click_link('Delete')
# #
# @param (see Capybara::Node::Finders#find) # @param (see #find)
# #
# @macro waiting_behavior # @macro waiting_behavior
# #
# @option options [Symbol] match The matching strategy to use.
#
# @return [Capybara::Node::Element] The found element # @return [Capybara::Node::Element] The found element
# @raise [Capybara::ElementNotFound] If the element can't be found before time expires # @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 # Find an {Capybara::Node::Element} based on the given arguments that is also a sibling of the element called on.
# is not found. # {#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('#foo').find('.bar')
# element.sibling(:xpath, './/div[contains(., "bar")]') # element.sibling(:xpath, './/div[contains(., "bar")]')
# element.sibling('ul', text: 'Quox').click_link('Delete') # element.sibling('ul', text: 'Quox').click_link('Delete')
# #
# @param (see Capybara::Node::Finders#find) # @param (see #find)
# #
# @macro waiting_behavior # @macro waiting_behavior
# #
# @option options [Symbol] match The matching strategy to use.
#
# @return [Capybara::Node::Element] The found element # @return [Capybara::Node::Element] The found element
# @raise [Capybara::ElementNotFound] If the element can't be found before time expires # @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. # Find a form field on the page. The field can be found by its name, id or label text.
# #
# @overload find_field([locator], **options) # @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 # @macro waiting_behavior
# #
@ -123,7 +124,6 @@ module Capybara
# @option options [String, Array<String>, Regexp] class Match fields that match the class(es) passed # @option options [String, Array<String>, Regexp] class Match fields that match the class(es) passed
# @return [Capybara::Node::Element] The found element # @return [Capybara::Node::Element] The found element
# #
def find_field(locator = nil, **options, &optional_filter_block) def find_field(locator = nil, **options, &optional_filter_block)
find(:field, locator, options, &optional_filter_block) find(:field, locator, options, &optional_filter_block)
end end
@ -133,11 +133,11 @@ module Capybara
# Find a link on the page. The link can be found by its id or text. # Find a link on the page. The link can be found by its id or text.
# #
# @overload find_link([locator], **options) # @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 # @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,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] id Match links with the id provided
# @option options [String] title Match links with the title 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] alt Match links with a contained img element whose alt matches
@ -151,14 +151,12 @@ module Capybara
## ##
# #
# Find a button on the page. # Find a button on the page.
# This can be any \<input> element of type submit, reset, image, button or it can be a # 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 # `<button>` element. All buttons can be found by their id, name, {Capybara.configure test_id} attribute, value, or title.
# by their text content, and image \<input> elements by their alt attribute # `<button>` elements can also be found by their text content, and image `<input>` elements by their alt attribute.
# #
# @overload find_button([locator], **options) # @overload find_button([locator], **options)
# @param [String] locator id, name, Capybara.test_id attribute, value, title, text content, alt of image # @param [String] locator id, name, {Capybara.configure test_id} attribute, value, title, text content, alt of image
#
# @overload find_button(**options)
# #
# @macro waiting_behavior # @macro waiting_behavior
# #
@ -204,9 +202,8 @@ module Capybara
# page.all(:css, 'a#person_123') # page.all(:css, 'a#person_123')
# page.all(:xpath, './/a[@id="person_123"]') # page.all(:xpath, './/a[@id="person_123"]')
# #
#
# If the type of selector is left out, Capybara uses # 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") # page.all("a#person_123")
# #
@ -219,28 +216,25 @@ module Capybara
# page.all('a', text: 'Home') # page.all('a', text: 'Home')
# page.all('#menu li', visible: true) # 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 # 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 # 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 # 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', count: 4)
# page.assert_selector('p#foo', maximum: 10) # page.assert_selector('p#foo', maximum: 10)
# page.assert_selector('p#foo', minimum: 1) # page.assert_selector('p#foo', minimum: 1)
# page.assert_selector('p#foo', between: 1..10) # page.assert_selector('p#foo', between: 1..10)
# #
# See {Capybara::Helpers#matches_count?} for additional information about # @param [Symbol] kind Optional selector type (:css, :xpath, :field, etc.). Defaults to {Capybara.configure default_selector}.
# count matching.
#
# @param [Symbol] kind Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
# @param [String] locator The locator for the specified selector # @param [String] locator The locator for the specified selector
# @macro system_filters # @macro system_filters
# @macro waiting_behavior
# @option options [Integer] count Exact number of matches that are expected to be found # @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] 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 [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 [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)
# @overload all([kind = Capybara.default_selector], locator = nil, **options, &filter_block) # @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 # @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 # 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 # 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. # element is found, or `nil` if the provided count options allow for empty results.
# #