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
Thomas Walpole
parent
4d9a38805a
commit
1963073b70
|
|
@ -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.
|
||||
#
|
||||
|
|
|
|||
Loading…
Reference in New Issue