Skip to content

Commit

Permalink
Some documentation fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@twalpole
twalpole committed May 17, 2018
1 parent b1f4709 commit 85ebea1
Show file tree
Hide file tree
Showing 10 changed files with 76 additions and 76 deletions.
6 changes: 3 additions & 3 deletions lib/capybara/driver/node.rb
View file
Expand Up @@ -40,15 +40,15 @@ def unselect_option
raise NotImplementedError
end

def click(keys = [], options = {})
def click(keys = [], **options)
raise NotImplementedError
end

def right_click(keys = [], options = {})
def right_click(keys = [], **options)
raise NotImplementedError
end

def double_click(keys = [], options = {})
def double_click(keys = [], **options)
raise NotImplementedError
end

Expand Down
75 changes: 38 additions & 37 deletions lib/capybara/node/actions.rb
View file
Expand Up @@ -50,7 +50,7 @@ def click_link(locator = nil, **options)
#
# @macro waiting_behavior
#
# @overload click_button([locator], options)
# @overload click_button([locator], **options)
# @param [String] locator Which button to find
# @param options See {Capybara::Node::Finders#find_button}
# @return [Capybara::Node::Element] The element clicked
Expand All @@ -66,18 +66,18 @@ def click_button(locator = nil, **options)
# page.fill_in 'Name', with: 'Bob'
#
#
# @overload fill_in([locator], options={})
# @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
# @macro waiting_behavior
# @option options [String] :with The value to fill in - required
# @option options [Hash] :fill_options Driver specific options regarding how to fill fields
# @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?
# @option options [String] :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>] :class Match fields that match the class(es) provided
# @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?
# @option options [String] 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>] class Match fields that match the class(es) provided
# @option options [Hash] fill_options Driver specific options regarding how to fill fields
#
# @return [Capybara::Node::Element] The element filled_in
def fill_in(locator = nil, with:, fill_options: {}, **options)
Expand All @@ -86,7 +86,7 @@ def fill_in(locator = nil, with:, fill_options: {}, **options)
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 (Capybara.automatic_label_click) Attempt to click the label to toggle state if element is non-visible.

##
#
Expand All @@ -95,13 +95,13 @@ def fill_in(locator = nil, with:, fill_options: {}, **options)
#
# page.choose('Male')
#
# @overload choose([locator], options)
# @overload choose([locator], **options)
# @param [String] locator Which radio button to choose
#
# @option options [String] :option Value of the radio_button to choose
# @option options [String] :id Match fields that match the id attribute
# @option options [String] :name Match fields that match the name attribute
# @option options [String, Array<String>] :class Match fields that match the class(es) provided
# @option options [String] option Value of the radio_button to choose
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
# @option options [String, Array<String>] class Match fields that match the class(es) provided
# @macro waiting_behavior
# @macro label_click
#
Expand All @@ -118,13 +118,13 @@ def choose(locator = nil, **options)
# page.check('German')
#
#
# @overload check([locator], options)
# @overload check([locator], **options)
# @param [String] locator Which check box to check
#
# @option options [String] :option Value of the checkbox to select
# @option options [String] option Value of the checkbox to select
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
# @option options [String, Array<String>] :class Match fields that match the class(es) provided
# @option options [String, Array<String>] class Match fields that match the class(es) provided
# @macro label_click
# @macro waiting_behavior
#
Expand All @@ -141,13 +141,13 @@ def check(locator = nil, **options)
# page.uncheck('German')
#
#
# @overload uncheck([locator], options)
# @overload uncheck([locator], **options)
# @param [String] locator Which check box to uncheck
#
# @option options [String] :option Value of the checkbox to deselect
# @option options [String] option Value of the checkbox to deselect
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
# @option options [String, Array<String>] :class Match fields that match the class(es) provided
# @option options [String, Array<String>] class Match fields that match the class(es) provided
# @macro label_click
# @macro waiting_behavior
#
Expand All @@ -169,8 +169,8 @@ def uncheck(locator = nil, **options)
#
# @macro waiting_behavior
#
# @param [String] value Which option to select
# @option options [String] :from The id, name or label of the select box
# @param value [String] Which option to select
# @param from: [String] The id, name or label of the select box
#
# @return [Capybara::Node::Element] The option element selected
def select(value = nil, from: nil, **options)
Expand All @@ -193,8 +193,8 @@ def select(value = nil, from: nil, **options)
#
# @macro waiting_behavior
#
# @param [String] value Which option to unselect
# @param [Hash{:from => String}] options The id, name or label of the select box
# @param value [String] Which option to unselect
# @param from: [String] The id, name or label of the select box
#
# @return [Capybara::Node::Element] The option element unselected
def unselect(value = nil, from: nil, **options)
Expand All @@ -209,20 +209,21 @@ def unselect(value = nil, from: nil, **options)
#
# page.attach_file(locator, '/path/to/file.png')
#
# @macro waiting_behavior
# @overload attach_file([locator], path, **options)
# @macro waiting_behavior
#
# @param [String] locator Which field to attach the file to
# @param [String] path The path of the file that will be attached, or an array of paths
# @param [String] locator Which field to attach the file to
# @param [String] path The path of the file that will be attached, or an array of paths
#
# @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 [Boolean] multiple Match field which allows multiple file selection
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
# @option options [String, Array<String>] :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 [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 [Boolean] multiple Match field which allows multiple file selection
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
# @option options [String, Array<String>] 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)
#
# @return [Capybara::Node::Element] The file field element
# @return [Capybara::Node::Element] The file field element
def attach_file(locator = nil, path, make_visible: nil, **options) # rubocop:disable Style/OptionalArguments
Array(path).each do |p|
raise Capybara::FileNotFound, "cannot attach file, #{p} does not exist" unless File.exist?(p.to_s)
Expand Down
4 changes: 2 additions & 2 deletions lib/capybara/node/document_matchers.rb
View file
Expand Up @@ -7,9 +7,9 @@ module DocumentMatchers
# Asserts that the page has the given title.
#
# @!macro title_query_params
# @overload $0(string, options = {})
# @overload $0(string, **options)
# @param string [String] The string that title should include
# @overload $0(regexp, options = {})
# @overload $0(regexp, **options)
# @param regexp [Regexp] The regexp that title should match to
# @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time that Capybara will wait for title to eq/match given string/regexp argument
# @option options [Boolean] :exact (false) When passed a string should the match be exact or just substring
Expand Down
12 changes: 7 additions & 5 deletions lib/capybara/node/element.rb
View file
Expand Up @@ -50,7 +50,7 @@ def native
# ignored. This behaviour can be overridden by passing `:all` to this
# method.
#
# @param [:all, :visible] type Whether to return only visible or all text
# @param type [:all, :visible] Whether to return only visible or all text
# @return [String] The text of the element
#
def text(type = nil)
Expand Down Expand Up @@ -119,9 +119,11 @@ def unselect_option
# Click the Element
#
# @!macro click_modifiers
# @overload $0(*key_modifiers=[], offset={x: nil, y: nil})
# @param [Array<:alt, :control, :meta, :shift>] *key_modifiers Keys to be held down when clicking
# @param [Hash] offset x and y coordinates to offset the click location from the top left corner of the element. If not specified will click the middle of the element.
# 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)
# @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
# @return [Capybara::Node::Element] The element
def click(*keys, **offset)
synchronize { base.click(keys, offset) }
Expand Down Expand Up @@ -155,7 +157,7 @@ def double_click(*keys, **offset)
# Send Keystrokes to the Element
#
# @overload send_keys(keys, ...)
# @param [String, Symbol, Array<String,Symbol>] keys
# @param keys [String, Symbol, Array<String,Symbol>]
#
# Examples:
#
Expand Down
14 changes: 7 additions & 7 deletions lib/capybara/node/finders.rb
View file
Expand Up @@ -88,7 +88,7 @@ def sibling(*args, **options, &optional_filter_block)
#
# 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, placeholder or text of associated label element
#
# @macro waiting_behavior
Expand Down Expand Up @@ -119,7 +119,7 @@ def find_field(locator = nil, **options, &optional_filter_block)
#
# 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, title, text, or alt of enclosed img element
#
# @macro waiting_behavior
Expand All @@ -142,10 +142,10 @@ def find_link(locator = nil, **options, &optional_filter_block)
# \<button> element. All buttons can be found by their id, 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={})
# @overload find_button([locator], **options)
# @param [String] locator id, value, title, text content, alt of image
#
# @overload find_button(options={})
# @overload find_button(**options)
#
# @macro waiting_behavior
#
Expand Down Expand Up @@ -178,7 +178,7 @@ def find_by_id(id, **options, &optional_filter_block)
end

##
# @!method all([kind = Capybara.default_selector], locator = nil, options = {})
# @!method all([kind = Capybara.default_selector], locator = nil, **options)
#
# Find all elements on the page matching the given selector
# and options.
Expand Down Expand Up @@ -235,8 +235,8 @@ def find_by_id(id, **options, &optional_filter_block)
# @option options [Range] between Number of matches found must be within the given range
# @option options [Boolean] exact Control whether `is` expressions in the given XPath match exactly or partially
# @option options [Integer, false] wait (Capybara.default_max_wait_time) The time to wait for matching elements to become available
# @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)
# @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
# @yieldreturn [Boolean] Should the element be considered in the results?
# @return [Capybara::Result] A collection of found elements
Expand Down
8 changes: 4 additions & 4 deletions lib/capybara/node/matchers.rb
View file
Expand Up @@ -110,7 +110,7 @@ def assert_selector(*args, &optional_filter_block)
# The :wait option applies to all of the selectors as a group, so all of the locators must be present
# within :wait (Defaults to Capybara.default_max_wait_time) seconds.
#
# @overload assert_all_of_selectors([kind = Capybara.default_selector], *locators, options = {})
# @overload assert_all_of_selectors([kind = Capybara.default_selector], *locators, **options)
#
def assert_all_of_selectors(*args, wait: nil, **options, &optional_filter_block)
wait = session_options.default_max_wait_time if wait.nil?
Expand All @@ -135,7 +135,7 @@ def assert_all_of_selectors(*args, wait: nil, **options, &optional_filter_block)
# The :wait option applies to all of the selectors as a group, so none of the locators must be present
# within :wait (Defaults to Capybara.default_max_wait_time) seconds.
#
# @overload assert_none_of_selectors([kind = Capybara.default_selector], *locators, options = {})
# @overload assert_none_of_selectors([kind = Capybara.default_selector], *locators, **options)
#
def assert_none_of_selectors(*args, wait: nil, **options, &optional_filter_block)
wait = session_options.default_max_wait_time if wait.nil?
Expand Down Expand Up @@ -574,7 +574,7 @@ def not_matches_css?(css, **options, &optional_filter_block)
# ignoring any HTML tags.
#
# @!macro text_query_params
# @overload $0(type, text, options = {})
# @overload $0(type, text, **options)
# @param [:all, :visible] type Whether to check for only visible or all text. If this parameter is missing or nil then we use the value of `Capybara.ignore_hidden_elements`, which defaults to `true`, corresponding to `:visible`.
# @param [String, Regexp] text The string/regexp to check for. If it's a string, text is expected to include it. If it's a regexp, text is expected to match it.
# @option options [Integer] :count (nil) Number of times the text is expected to occur
Expand All @@ -583,7 +583,7 @@ def not_matches_css?(css, **options, &optional_filter_block)
# @option options [Range] :between (nil) Range of times that is expected to contain number of times text occurs
# @option options [Numeric] :wait (Capybara.default_max_wait_time) Maximum time that Capybara will wait for text to eq/match given string/regexp argument
# @option options [Boolean] :exact (Capybara.exact_text) Whether text must be an exact match or just substring
# @overload $0(text, options = {})
# @overload $0(text, **options)
# @param [String, Regexp] text The string/regexp to check for. If it's a string, text is expected to include it. If it's a regexp, text is expected to match it.
# @option options [Integer] :count (nil) Number of times the text is expected to occur
# @option options [Integer] :minimum (nil) Minimum number of times the text is expected to occur
Expand Down
3 changes: 1 addition & 2 deletions lib/capybara/rack_test/node.rb
View file
Expand Up @@ -55,7 +55,7 @@ def unselect_option
native.remove_attribute('selected')
end

def click(keys = [], offset = {})
def click(keys = [], **offset)
raise ArgumentError, "The RackTest driver does not support click options" unless keys.empty? && offset.empty?

if link?
Expand Down Expand Up @@ -250,5 +250,4 @@ def input_field?
def textarea?
tag_name == "textarea"
end

end

0 comments on commit 85ebea1

Please sign in to comment.