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
2010-07-17 14:03:46 +00:00
##
#
2017-10-22 19:07:11 +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
# @!macro waiting_behavior
# If the driver is capable of executing JavaScript, +$0+ will wait for a set amount of time
# 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.
2010-07-17 14:03:46 +00:00
#
2016-04-14 18:22:51 +00:00
# @overload click_link_or_button([locator], options)
#
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.
#
2016-04-14 18:22:51 +00:00
# @macro waiting_behavior
2010-07-17 14:03:46 +00:00
#
2016-04-14 18:22:51 +00:00
# @overload click_link([locator], options)
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
#
2016-04-14 18:22:51 +00:00
# @macro waiting_behavior
#
2018-05-17 21:45:53 +00:00
# @overload click_button([locator], **options)
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.
2010-07-17 14:03:46 +00:00
#
2016-10-04 18:10:29 +00:00
# page.fill_in 'Name', with: 'Bob'
2010-07-17 14:03:46 +00:00
#
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?
# @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
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
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
##
#
# Find a radio button and mark it as checked. The radio button can be found
# via name, id or label text.
#
# page.choose('Male')
#
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
# @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
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
##
#
# Find a check box and mark it as checked. The check box can be found
# via name, id or label text.
#
# page.check('German')
#
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
2016-04-27 05:44:48 +00:00
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
2018-05-17 21:45:53 +00:00
# @option options [String, Array<String>] 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
##
#
# Find a check box and mark uncheck it. The check box can be found
# via name, id or label text.
#
# page.uncheck('German')
#
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
2016-04-27 05:44:48 +00:00
# @option options [String] id Match fields that match the id attribute
# @option options [String] name Match fields that match the name attribute
2018-05-17 21:45:53 +00:00
# @option options [String, Array<String>] 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
#
2016-04-14 18:22:51 +00:00
# @macro waiting_behavior
#
2018-05-17 21:45:53 +00:00
# @param value [String] Which option to select
2018-07-05 22:29:24 +00:00
# @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-05-15 16:17:09 +00:00
if el . respond_to? ( :tag_name ) && ( el . tag_name == " input " )
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
#
2016-04-14 18:22:51 +00:00
# @macro waiting_behavior
#
2018-05-17 21:45:53 +00:00
# @param value [String] Which option to unselect
2018-07-05 22:29:24 +00:00
# @param from: [String] The id, Capybara.test_id attribute, 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 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
##
#
# Find a file field on the page and attach a file given its path. The file field can
# be found via its name, id or label text.
#
# page.attach_file(locator, '/path/to/file.png')
#
2018-05-17 21:45:53 +00:00
# @overload attach_file([locator], path, **options)
# @macro waiting_behavior
2016-04-14 18:22:51 +00:00
#
2018-05-17 21:45:53 +00:00
# @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
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
# @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)
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-01-09 22:05:50 +00:00
def attach_file ( locator = nil , path , make_visible : nil , ** options ) # rubocop:disable Style/OptionalArguments
2012-11-20 21:51:25 +00:00
Array ( path ) . each do | p |
2012-09-17 12:48:13 +00:00
raise Capybara :: FileNotFound , " cannot attach file, #{ p } does not exist " unless File . exist? ( p . to_s )
end
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-01-12 00:45:50 +00:00
while_visible ( ff , make_visible ) { | el | el . set ( path ) }
2017-01-03 19:20:58 +00:00
else
find ( :file_field , locator , options ) . set ( path )
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 ) }
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-05-15 16:17:09 +00:00
if ( option = datalist_options . find { | o | o [ 'value' ] == value || o [ 'label' ] == value } )
2018-05-16 19:47:08 +00:00
input . set ( option [ 'value' ] )
2018-05-15 16:17:09 +00:00
else
2018-05-16 19:47:08 +00:00
raise :: Capybara :: ElementNotFound , %( Unable to find datalist option " #{ value } " )
2018-05-15 16:17:09 +00:00
end
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 )
raise ExpectationNotMet , " The style changes in :make_visible did not make the file input visible " unless element . visible?
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
warn " The :make_visible option is not supported by the current driver - ignoring "
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-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-05-14 21:30:34 +00:00
rescue StandardError = > e
2016-11-22 18:45:15 +00:00
raise unless allow_label_click && catch_error? ( e )
begin
el || = find ( selector , locator , options . merge ( visible : :all ) )
2018-05-16 19:47:08 +00:00
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
2016-11-22 18:45:15 +00:00
raise e
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-05-18 22:04:49 +00:00
this . style [ prop ] = css [ prop ]
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