2016-03-08 00:52:19 +00:00
# frozen_string_literal: true
2018-01-08 20:23:54 +00:00
2010-07-10 00:20:32 +00:00
module Capybara
2010-11-21 13:37:36 +00:00
module Node
2010-07-10 00:20:32 +00:00
module Actions
2016-04-14 18:22:51 +00:00
# @!macro waiting_behavior
2018-10-28 19:02:13 +00:00
# If the driver is capable of executing JavaScript, this method will wait for a set amount of time
2016-04-14 18:22:51 +00:00
# and continuously retry finding the element until either the element is found or the time
# expires. The length of time +find+ will wait is controlled through {Capybara.default_max_wait_time}
2010-07-17 14:03:46 +00:00
#
2016-04-14 18:22:51 +00:00
# @option options [false, Numeric] wait (Capybara.default_max_wait_time) Maximum time to wait for matching element to appear.
2018-10-28 19:02:13 +00:00
##
2010-07-17 14:03:46 +00:00
#
2018-10-28 19:02:13 +00:00
# Finds a button or link and clicks it. See {Capybara::Node::Actions#click_button} and
# {Capybara::Node::Actions#click_link} for what locator will match against for each type of element
2016-04-14 18:22:51 +00:00
#
2018-10-28 19:02:13 +00:00
# @overload click_link_or_button([locator], **options)
# @macro waiting_behavior
2017-10-22 19:07:11 +00:00
# @param [String] locator See {Capybara::Node::Actions#click_button} and {Capybara::Node::Actions#click_link}
2016-04-14 18:22:51 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element clicked
#
2018-01-09 22:05:50 +00:00
def click_link_or_button ( locator = nil , ** options )
2013-02-24 15:28:48 +00:00
find ( :link_or_button , locator , options ) . click
2010-07-10 00:20:32 +00:00
end
2010-10-29 11:41:49 +00:00
alias_method :click_on , :click_link_or_button
2010-07-10 00:20:32 +00:00
2010-07-17 14:03:46 +00:00
##
#
2018-07-05 22:29:24 +00:00
# Finds a link by id, Capybara.test_id attribute, text or title and clicks it. Also looks at image
2010-07-17 14:03:46 +00:00
# alt text inside the link.
#
2018-10-28 19:02:13 +00:00
# @overload click_link([locator], **options)
# @macro waiting_behavior
2018-07-05 22:29:24 +00:00
# @param [String] locator text, id, Capybara.test_id attribute, title or nested image's alt attribute
2016-04-14 18:22:51 +00:00
# @param options See {Capybara::Node::Finders#find_link}
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element clicked
2018-01-09 22:05:50 +00:00
def click_link ( locator = nil , ** options )
2013-02-19 20:12:54 +00:00
find ( :link , locator , options ) . click
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
2015-08-25 21:50:44 +00:00
# Finds a button on the page and clicks it.
# This can be any \<input> element of type submit, reset, image, button or it can be a
2018-07-05 22:29:24 +00:00
# \<button> element. All buttons can be found by their id, Capybara.test_id attribute, value, or title. \<button> elements can also be found
2015-08-25 21:50:44 +00:00
# by their text content, and image \<input> elements by their alt attribute
2010-07-17 14:03:46 +00:00
#
2018-05-17 21:45:53 +00:00
# @overload click_button([locator], **options)
2018-10-28 19:02:13 +00:00
# @macro waiting_behavior
2016-04-14 18:22:51 +00:00
# @param [String] locator Which button to find
# @param options See {Capybara::Node::Finders#find_button}
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element clicked
2018-01-09 22:05:50 +00:00
def click_button ( locator = nil , ** options )
2013-02-24 15:36:08 +00:00
find ( :button , locator , options ) . click
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
# Locate a text field or text area and fill it in with the given text
2018-07-05 22:29:24 +00:00
# The field can be found via its name, id, Capybara.test_id attribute, or label text.
2018-08-31 17:01:40 +00:00
# If no locator is provided will operate on self or a descendant
2010-07-17 14:03:46 +00:00
#
2018-09-10 22:34:12 +00:00
# # will fill in a descendant fillable field with name, id, or label text matching 'Name'
2016-10-04 18:10:29 +00:00
# page.fill_in 'Name', with: 'Bob'
2010-07-17 14:03:46 +00:00
#
2018-09-10 22:34:12 +00:00
# # will fill in `el` if it's a fillable field
# el.fill_in with: 'Tom'
#
2016-04-14 18:22:51 +00:00
#
2018-05-17 21:45:53 +00:00
# @overload fill_in([locator], with:, **options)
2016-09-07 07:34:15 +00:00
# @param [String] locator Which field to fill in
# @param [Hash] options
2018-05-17 21:45:53 +00:00
# @param with: [String] The value to fill_in
2016-09-07 07:34:15 +00:00
# @macro waiting_behavior
2018-05-17 21:45:53 +00:00
# @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?
2018-10-28 19:00:34 +00:00
# @option options [String, Regexp] id Match fields that match the id attribute
2018-05-17 21:45:53 +00:00
# @option options [String] name Match fields that match the name attribute
# @option options [String] placeholder Match fields that match the placeholder attribute
2018-10-28 19:00:34 +00:00
# @option options [String, Array<String>, Regexp] class Match fields that match the class(es) provided
2018-05-18 17:29:53 +00:00
# @option options [Hash] fill_options Driver specific options regarding how to fill fields (Defaults come from Capybara.default_set_options)
2010-07-17 14:03:46 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element filled_in
2018-07-04 17:02:02 +00:00
def fill_in ( locator = nil , with : , currently_with : nil , fill_options : { } , ** find_options )
find_options [ :with ] = currently_with if currently_with
2018-08-31 17:01:40 +00:00
find_options [ :allow_self ] = true if locator . nil?
2018-07-04 17:02:02 +00:00
find ( :fillable_field , locator , find_options ) . set ( with , fill_options )
2010-07-10 00:20:32 +00:00
end
2016-08-01 21:14:10 +00:00
# @!macro label_click
2018-05-17 21:45:53 +00:00
# @option options [Boolean] allow_label_click (Capybara.automatic_label_click) Attempt to click the label to toggle state if element is non-visible.
2016-04-22 17:11:19 +00:00
2010-07-17 14:03:46 +00:00
##
#
2018-08-31 17:01:40 +00:00
# Find a descendant radio button and mark it as checked. The radio button can be found
# via name, id or label text. If no locator is provided this will match against self or
# a descendant.
2010-07-17 14:03:46 +00:00
#
2018-09-10 22:34:12 +00:00
# # will choose a descendant radio button with a name, id, or label text matching 'Male'
2010-07-17 14:03:46 +00:00
# page.choose('Male')
#
2018-09-10 22:34:12 +00:00
# # will choose `el` if it's a radio button element
# el.choose()
#
2018-05-17 21:45:53 +00:00
# @overload choose([locator], **options)
2016-04-14 18:22:51 +00:00
# @param [String] locator Which radio button to choose
#
2018-05-17 21:45:53 +00:00
# @option options [String] option Value of the radio_button to choose
2018-10-28 19:00:34 +00:00
# @option options [String, Regexp] id Match fields that match the id attribute
2018-05-17 21:45:53 +00:00
# @option options [String] name Match fields that match the name attribute
2018-10-28 19:00:34 +00:00
# @option options [String, Array<String>, Regexp] class Match fields that match the class(es) provided
2016-04-22 17:11:19 +00:00
# @macro waiting_behavior
2016-08-01 21:14:10 +00:00
# @macro label_click
2016-10-10 21:43:40 +00:00
#
# @return [Capybara::Node::Element] The element chosen or the label clicked
2018-01-09 22:05:50 +00:00
def choose ( locator = nil , ** options )
2018-05-14 20:51:06 +00:00
_check_with_label ( :radio_button , true , locator , options )
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
2018-08-31 17:01:40 +00:00
# Find a descendant check box and mark it as checked. The check box can be found
# via name, id or label text. If no locator is provided this will match against
# self or a descendant.
2010-07-17 14:03:46 +00:00
#
2018-09-10 22:34:12 +00:00
# # will check a descendant checkbox with a name, id, or label text matching 'German'
2010-07-17 14:03:46 +00:00
# page.check('German')
#
2018-09-10 22:34:12 +00:00
# # will check `el` if it's a checkbox element
# el.check()
#
2016-04-14 18:22:51 +00:00
#
2018-05-17 21:45:53 +00:00
# @overload check([locator], **options)
2016-04-14 18:22:51 +00:00
# @param [String] locator Which check box to check
#
2018-05-17 21:45:53 +00:00
# @option options [String] option Value of the checkbox to select
2018-10-28 19:00:34 +00:00
# @option options [String, Regexp] id Match fields that match the id attribute
2016-04-27 05:44:48 +00:00
# @option options [String] name Match fields that match the name attribute
2018-10-28 19:00:34 +00:00
# @option options [String, Array<String>, Regexp] class Match fields that match the class(es) provided
2016-08-01 21:14:10 +00:00
# @macro label_click
2016-04-22 17:11:19 +00:00
# @macro waiting_behavior
2010-07-17 14:03:46 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element checked or the label clicked
2018-04-27 16:39:34 +00:00
def check ( locator = nil , ** options )
2018-05-14 20:51:06 +00:00
_check_with_label ( :checkbox , true , locator , options )
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
2018-09-10 22:34:12 +00:00
# Find a descendant check box and uncheck it. The check box can be found
2018-08-31 17:01:40 +00:00
# via name, id or label text. If no locator is provided this will match against
# self or a descendant.
2010-07-17 14:03:46 +00:00
#
2018-09-10 22:34:12 +00:00
# # will uncheck a descendant checkbox with a name, id, or label text matching 'German'
2010-07-17 14:03:46 +00:00
# page.uncheck('German')
#
2018-09-10 22:34:12 +00:00
# # will uncheck `el` if it's a checkbox element
# el.uncheck()
#
2016-04-14 18:22:51 +00:00
#
2018-05-17 21:45:53 +00:00
# @overload uncheck([locator], **options)
2016-04-14 18:22:51 +00:00
# @param [String] locator Which check box to uncheck
#
2018-05-17 21:45:53 +00:00
# @option options [String] option Value of the checkbox to deselect
2018-10-28 19:00:34 +00:00
# @option options [String, Regexp] id Match fields that match the id attribute
2016-04-27 05:44:48 +00:00
# @option options [String] name Match fields that match the name attribute
2018-10-28 19:00:34 +00:00
# @option options [String, Array<String>, Regexp] class Match fields that match the class(es) provided
2016-08-01 21:14:10 +00:00
# @macro label_click
2016-04-22 17:11:19 +00:00
# @macro waiting_behavior
2010-07-17 14:03:46 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element unchecked or the label clicked
2018-01-09 22:05:50 +00:00
def uncheck ( locator = nil , ** options )
2018-05-14 20:51:06 +00:00
_check_with_label ( :checkbox , false , locator , options )
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
2018-05-09 18:30:36 +00:00
# If `:from` option is present, `select` finds a select box, or text input with associated datalist,
# on the page and selects a particular option from it.
2014-08-24 13:20:45 +00:00
# Otherwise it finds an option inside current scope and selects it.
# If the select box is a multiple select, +select+ can be called multiple times to select more than
# one option.
# The select box can be found via its name, id or label text. The option can be found by its text.
2010-07-17 14:03:46 +00:00
#
2016-10-04 18:10:29 +00:00
# page.select 'March', from: 'Month'
2010-07-17 14:03:46 +00:00
#
2018-10-31 05:24:53 +00:00
# @overload select(value = nil, from: nil, **options)
# @macro waiting_behavior
2016-04-14 18:22:51 +00:00
#
2018-10-31 05:24:53 +00:00
# @param value [String] Which option to select
# @param from [String] The id, Capybara.test_id atrtribute, name or label of the select box
2010-07-17 14:03:46 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The option element selected
2018-01-09 22:05:50 +00:00
def select ( value = nil , from : nil , ** options )
2018-05-15 16:17:09 +00:00
el = from ? find_select_or_datalist_input ( from , options ) : self
2018-04-26 10:04:31 +00:00
2018-07-10 21:18:39 +00:00
if el . respond_to? ( :tag_name ) && ( el . tag_name == 'input' )
2018-05-15 16:17:09 +00:00
select_datalist_option ( el , value )
2018-04-26 10:04:31 +00:00
else
2018-05-15 16:17:09 +00:00
el . find ( :option , value , options ) . select_option
2018-04-26 10:04:31 +00:00
end
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
2011-04-07 19:43:30 +00:00
# Find a select box on the page and unselect a particular option from it. If the select
# box is a multiple select, +unselect+ can be called multiple times to unselect more than
2010-07-17 14:03:46 +00:00
# one option. The select box can be found via its name, id or label text.
#
2016-10-04 18:10:29 +00:00
# page.unselect 'March', from: 'Month'
2010-07-17 14:03:46 +00:00
#
2018-10-31 05:24:53 +00:00
# @overload unselect(value = nil, from: nil, **options)
# @macro waiting_behavior
#
# @param value [String] Which option to unselect
# @param from [String] The id, Capybara.test_id attribute, name or label of the select box
2016-04-14 18:22:51 +00:00
#
2010-07-17 14:03:46 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The option element unselected
2018-01-09 22:05:50 +00:00
def unselect ( value = nil , from : nil , ** options )
2018-01-13 00:57:41 +00:00
scope = from ? find ( :select , from , options ) : self
scope . find ( :option , value , options ) . unselect_option
2010-07-10 00:20:32 +00:00
end
2010-07-17 14:03:46 +00:00
##
#
2018-08-31 17:01:40 +00:00
# Find a descendant file field on the page and attach a file given its path. The file field can
2018-07-12 16:26:51 +00:00
# be found via its name, id or label text. In the case of the file field being hidden for
# styling reasons the `make_visible` option can be used to temporarily change the CSS of
2018-08-31 17:01:40 +00:00
# the file field, attach the file, and then revert the CSS back to original. If no locator is
# passed this will match self or a descendant.
2010-07-17 14:03:46 +00:00
#
2018-09-10 22:34:12 +00:00
# # will attach file to a descendant file input element that has a name, id, or label_text matching 'My File'
# page.attach_file('My File', '/path/to/file.png')
#
# # will attach file to el if it's a file input element
# el.attach_file('/path/to/file.png')
2010-07-17 14:03:46 +00:00
#
2018-08-20 23:46:31 +00:00
# @overload attach_file([locator], paths, **options)
2018-05-17 21:45:53 +00:00
# @macro waiting_behavior
2016-04-14 18:22:51 +00:00
#
2018-08-17 20:57:12 +00:00
# @param [String] locator Which field to attach the file to
# @param [String, Array<String>] paths The path(s) of the file(s) that will be attached
2010-07-17 14:03:46 +00:00
#
2018-05-17 21:45:53 +00:00
# @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
2018-10-28 19:00:34 +00:00
# @option options [String, Regexp] id Match fields that match the id attribute
2018-05-17 21:45:53 +00:00
# @option options [String] name Match fields that match the name attribute
2018-10-28 19:00:34 +00:00
# @option options [String, Array<String>, Regexp] class Match fields that match the class(es) provided
2018-05-17 21:45:53 +00:00
# @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)
2016-02-26 19:33:32 +00:00
#
2018-05-17 21:45:53 +00:00
# @return [Capybara::Node::Element] The file field element
2018-08-20 23:46:31 +00:00
def attach_file ( locator = nil , paths , make_visible : nil , ** options ) # rubocop:disable Style/OptionalArguments
Array ( paths ) . each do | path |
raise Capybara :: FileNotFound , " cannot attach file, #{ path } does not exist " unless File . exist? ( path . to_s )
2012-09-17 12:48:13 +00:00
end
2018-08-31 17:01:40 +00:00
options [ :allow_self ] = true if locator . nil?
2016-12-30 20:33:57 +00:00
# Allow user to update the CSS style of the file input since they are so often hidden on a page
2017-05-02 01:39:08 +00:00
if make_visible
2018-01-09 22:05:50 +00:00
ff = find ( :file_field , locator , options . merge ( visible : :all ) )
2018-08-20 23:46:31 +00:00
while_visible ( ff , make_visible ) { | el | el . set ( paths ) }
2017-01-03 19:20:58 +00:00
else
2018-08-20 23:46:31 +00:00
find ( :file_field , locator , options ) . set ( paths )
2016-12-30 20:33:57 +00:00
end
2010-07-10 00:20:32 +00:00
end
2016-11-22 18:45:15 +00:00
private
2018-01-09 22:05:50 +00:00
2018-05-15 16:17:09 +00:00
def find_select_or_datalist_input ( from , options )
synchronize ( Capybara :: Queries :: BaseQuery . wait ( options , session_options . default_max_wait_time ) ) do
begin
find ( :select , from , options )
rescue Capybara :: ElementNotFound = > select_error
raise if % i [ selected with_selected multiple ] . any? { | option | options . key? ( option ) }
2018-09-24 16:43:46 +00:00
2018-05-15 16:17:09 +00:00
begin
find ( :datalist_input , from , options )
rescue Capybara :: ElementNotFound = > dlinput_error
raise Capybara :: ElementNotFound , " #{ select_error . message } and #{ dlinput_error . message } "
end
end
end
end
def select_datalist_option ( input , value )
2018-05-18 22:04:49 +00:00
datalist_options = input . evaluate_script ( DATALIST_OPTIONS_SCRIPT )
2018-08-20 23:46:31 +00:00
option = datalist_options . find { | opt | opt . values_at ( 'value' , 'label' ) . include? ( value ) }
2018-07-10 21:18:39 +00:00
raise :: Capybara :: ElementNotFound , %( Unable to find datalist option " #{ value } " ) unless option
2018-09-24 16:43:46 +00:00
2018-07-10 21:18:39 +00:00
input . set ( option [ 'value' ] )
2018-05-15 16:17:09 +00:00
rescue :: Capybara :: NotSupportedByDriverError
# Implement for drivers that don't support JS
datalist = find ( :xpath , XPath . descendant ( :datalist ) [ XPath . attr ( :id ) == input [ :list ] ] , visible : false )
option = datalist . find ( :datalist_option , value , disabled : false )
input . set ( option . value )
end
2018-01-12 00:45:50 +00:00
def while_visible ( element , visible_css )
visible_css = { opacity : 1 , display : 'block' , visibility : 'visible' } if visible_css == true
_update_style ( element , visible_css )
2018-07-10 21:18:39 +00:00
raise ExpectationNotMet , 'The style changes in :make_visible did not make the file input visible' unless element . visible?
2018-09-24 16:43:46 +00:00
2016-12-30 20:33:57 +00:00
begin
2018-01-12 00:45:50 +00:00
yield element
ensure
_reset_style ( element )
2016-12-30 20:33:57 +00:00
end
end
2016-11-22 18:45:15 +00:00
2018-01-12 00:45:50 +00:00
def _update_style ( element , style )
2018-05-18 22:04:49 +00:00
element . execute_script ( UPDATE_STYLE_SCRIPT , style )
2018-01-12 00:45:50 +00:00
rescue Capybara :: NotSupportedByDriverError
2018-07-10 21:18:39 +00:00
warn 'The :make_visible option is not supported by the current driver - ignoring'
2018-01-12 00:45:50 +00:00
end
2017-01-09 20:50:56 +00:00
def _reset_style ( element )
2018-05-18 22:04:49 +00:00
element . execute_script ( RESET_STYLE_SCRIPT )
2018-05-14 21:30:34 +00:00
rescue StandardError # rubocop:disable Lint/HandleExceptions swallow extra errors
2017-01-09 20:50:56 +00:00
end
2016-08-17 23:14:39 +00:00
def _check_with_label ( selector , checked , locator , allow_label_click : session_options . automatic_label_click , ** options )
2018-08-31 17:01:40 +00:00
options [ :allow_self ] = true if locator . nil?
2018-01-09 22:05:50 +00:00
synchronize ( Capybara :: Queries :: BaseQuery . wait ( options , session_options . default_max_wait_time ) ) do
2016-11-22 18:45:15 +00:00
begin
el = find ( selector , locator , options )
el . set ( checked )
2018-08-20 23:46:31 +00:00
rescue StandardError = > err
raise unless allow_label_click && catch_error? ( err )
2018-09-24 16:43:46 +00:00
2016-11-22 18:45:15 +00:00
begin
el || = find ( selector , locator , options . merge ( visible : :all ) )
2018-08-31 17:01:40 +00:00
el . session . find ( :label , for : el , visible : true ) . click unless el . checked? == checked
2018-05-14 21:30:34 +00:00
rescue StandardError # swallow extra errors - raise original
2018-08-20 23:46:31 +00:00
raise err
2016-11-22 18:45:15 +00:00
end
end
end
end
2018-01-12 00:45:50 +00:00
2018-05-16 19:47:08 +00:00
UPDATE_STYLE_SCRIPT = << ~ 'JS'
2018-05-18 22:04:49 +00:00
this . capybara_style_cache = this . style . cssText ;
var css = arguments [ 0 ] ;
2018-01-12 00:45:50 +00:00
for ( var prop in css ) {
if ( css . hasOwnProperty ( prop ) ) {
2018-08-28 17:29:09 +00:00
this . style . setProperty ( prop , css [ prop ] , " important " ) ;
2018-01-12 00:45:50 +00:00
}
}
JS
2018-05-16 19:47:08 +00:00
RESET_STYLE_SCRIPT = << ~ 'JS'
2018-05-18 22:04:49 +00:00
if ( this . hasOwnProperty ( 'capybara_style_cache' ) ) {
this . style . cssText = this . capybara_style_cache ;
delete this . capybara_style_cache ;
2018-01-12 00:45:50 +00:00
}
JS
2018-04-26 10:04:31 +00:00
2018-05-16 19:47:08 +00:00
DATALIST_OPTIONS_SCRIPT = << ~ 'JS'
2018-05-18 22:04:49 +00:00
Array . prototype . slice . call ( ( this . list || { } ) . options || [ ] ) .
2018-04-26 10:04:31 +00:00
filter ( function ( el ) { return ! el . disabled } ) .
map ( function ( el ) { return { " value " : el . value , " label " : el . label } } )
JS
2010-07-10 00:20:32 +00:00
end
end
end