diff --git a/lib/capybara/driver/node.rb b/lib/capybara/driver/node.rb index 445d997f2..8f0acb80a 100644 --- a/lib/capybara/driver/node.rb +++ b/lib/capybara/driver/node.rb @@ -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 diff --git a/lib/capybara/node/actions.rb b/lib/capybara/node/actions.rb index 211e2c840..0e4085740 100644 --- a/lib/capybara/node/actions.rb +++ b/lib/capybara/node/actions.rb @@ -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 @@ -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] :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] 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) @@ -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. ## # @@ -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] :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] class Match fields that match the class(es) provided # @macro waiting_behavior # @macro label_click # @@ -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] :class Match fields that match the class(es) provided + # @option options [String, Array] class Match fields that match the class(es) provided # @macro label_click # @macro waiting_behavior # @@ -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] :class Match fields that match the class(es) provided + # @option options [String, Array] class Match fields that match the class(es) provided # @macro label_click # @macro waiting_behavior # @@ -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) @@ -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) @@ -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] :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] 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) diff --git a/lib/capybara/node/document_matchers.rb b/lib/capybara/node/document_matchers.rb index dbda90710..646a2ef7e 100644 --- a/lib/capybara/node/document_matchers.rb +++ b/lib/capybara/node/document_matchers.rb @@ -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 diff --git a/lib/capybara/node/element.rb b/lib/capybara/node/element.rb index dee38467d..c615ba1f0 100644 --- a/lib/capybara/node/element.rb +++ b/lib/capybara/node/element.rb @@ -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) @@ -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) } @@ -155,7 +157,7 @@ def double_click(*keys, **offset) # Send Keystrokes to the Element # # @overload send_keys(keys, ...) - # @param [String, Symbol, Array] keys + # @param keys [String, Symbol, Array] # # Examples: # diff --git a/lib/capybara/node/finders.rb b/lib/capybara/node/finders.rb index 33a765a6b..6a81e4250 100644 --- a/lib/capybara/node/finders.rb +++ b/lib/capybara/node/finders.rb @@ -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 @@ -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 @@ -142,10 +142,10 @@ def find_link(locator = nil, **options, &optional_filter_block) # \