2016-03-08 00:52:19 +00:00
# frozen_string_literal: true
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
##
#
# Finds a button or link by id, text or value and clicks it. Also looks at image
# alt text inside the link.
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)
#
# @param [String] locator Text, id or value of link or button
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element clicked
#
2016-04-14 18:22:51 +00:00
def click_link_or_button ( locator = nil , options = { } )
locator , options = nil , locator if locator . is_a? Hash
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
##
#
2014-08-24 13:20:45 +00:00
# Finds a link by id, 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)
# @param [String] locator text, id, title or nested image's alt attribute
# @param options See {Capybara::Node::Finders#find_link}
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element clicked
2016-04-14 18:22:51 +00:00
def click_link ( locator = nil , options = { } )
locator , options = nil , locator if locator . is_a? Hash
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
# \<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
2010-07-17 14:03:46 +00:00
#
2016-04-14 18:22:51 +00:00
# @macro waiting_behavior
#
# @overload click_button([locator], options)
# @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
2016-04-14 18:22:51 +00:00
def click_button ( locator = nil , options = { } )
locator , options = nil , locator if locator . is_a? Hash
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
# The field can be found via its name, id or label text.
#
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
#
2016-09-07 07:34:15 +00:00
# @overload fill_in([locator], options={})
# @param [String] locator Which field to fill in
# @param [Hash] options
# @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
2016-12-20 17:52:51 +00:00
# @option options [String] :currently_with The current value property of the field to fill in
2016-09-07 07:34:15 +00:00
# @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 links that match the class(es) provided
2010-07-17 14:03:46 +00:00
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The element filled_in
2010-07-10 00:20:32 +00:00
def fill_in ( locator , options = { } )
2016-04-27 05:44:48 +00:00
locator , options = nil , locator if locator . is_a? Hash
2010-07-10 00:20:32 +00:00
raise " Must pass a hash containing 'with' " if not options . is_a? ( Hash ) or not options . has_key? ( :with )
2013-02-24 15:41:20 +00:00
with = options . delete ( :with )
2014-06-18 23:36:11 +00:00
fill_options = options . delete ( :fill_options )
2016-12-20 17:52:51 +00:00
options [ :with ] = options . delete ( :currently_with ) if options . has_key? ( :currently_with )
2014-06-18 23:36:11 +00:00
find ( :fillable_field , locator , 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
# @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')
#
2016-04-14 18:22:51 +00:00
# @overload choose([locator], options)
# @param [String] locator Which radio button to choose
#
# @option options [String] :option Value of the radio_button to choose
2016-09-07 07:34:15 +00:00
# @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 links 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
2013-02-24 15:48:14 +00:00
def choose ( locator , options = { } )
2016-11-22 18:45:15 +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
#
# @overload check([locator], options)
# @param [String] locator Which check box to check
#
# @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
2016-09-07 07:34:15 +00:00
# @option options [String, Array<String>] :class Match links 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
2013-02-24 15:48:25 +00:00
def check ( locator , options = { } )
2016-11-22 18:45:15 +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
#
# @overload uncheck([locator], options)
# @param [String] locator Which check box to uncheck
#
# @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
2016-09-07 07:34:15 +00:00
# @option options [String, Array<String>] :class Match links 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
2013-02-24 15:48:33 +00:00
def uncheck ( locator , options = { } )
2016-11-22 18:45:15 +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
##
#
2014-08-24 13:20:45 +00:00
# If `:from` option is present, `select` finds a select box on the page
# and selects a particular option from it.
# 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
#
2013-03-29 02:15:07 +00:00
# @param [String] value Which option to select
2014-08-24 13:20:45 +00:00
# @option options [String] :from The id, 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
2010-07-10 00:20:32 +00:00
def select ( value , options = { } )
2010-10-03 17:15:40 +00:00
if options . has_key? ( :from )
2013-02-24 15:58:46 +00:00
from = options . delete ( :from )
find ( :select , from , options ) . find ( :option , value , options ) . select_option
2010-10-03 17:15:40 +00:00
else
2013-02-24 15:58:46 +00:00
find ( :option , value , options ) . select_option
2010-10-03 17:15:40 +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
#
2013-03-29 02:15:07 +00:00
# @param [String] value Which option to unselect
# @param [Hash{:from => String}] options The id, 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
2010-07-10 00:20:32 +00:00
def unselect ( value , options = { } )
2010-10-03 17:15:40 +00:00
if options . has_key? ( :from )
2013-02-24 16:03:12 +00:00
from = options . delete ( :from )
find ( :select , from , options ) . find ( :option , value , options ) . unselect_option
2010-10-03 17:15:40 +00:00
else
2013-02-24 16:03:12 +00:00
find ( :option , value , options ) . unselect_option
2010-10-03 17:15:40 +00:00
end
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')
#
2016-04-14 18:22:51 +00:00
# @macro waiting_behavior
#
2010-07-17 14:03:46 +00:00
# @param [String] locator Which field to attach the file to
2012-09-17 12:48:13 +00:00
# @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
#
2016-02-29 06:38:32 +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
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
2016-09-07 07:34:15 +00:00
# @option options [String, Array<String>] :class Match links that match the class(es) provided
2017-01-03 19:20:58 +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
#
2016-10-10 21:43:40 +00:00
# @return [Capybara::Node::Element] The file field element
2013-02-24 16:06:01 +00:00
def attach_file ( locator , path , options = { } )
2016-04-27 05:44:48 +00:00
locator , path , options = nil , locator , path if path . is_a? Hash
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-01-03 19:20:58 +00:00
if style = options . delete ( :make_visible )
style = { opacity : 1 , display : 'block' , visibility : 'visible' } if style == true
2016-12-30 20:33:57 +00:00
ff = find ( :file_field , locator , options . merge ( { visible : :all } ) )
_update_style ( ff , style )
2017-01-03 19:20:58 +00:00
if ff . visible?
2017-01-09 20:50:56 +00:00
begin
ff . set ( path )
ensure
_reset_style ( ff )
end
2017-01-03 19:20:58 +00:00
else
raise ExpectationNotMet , " The style changes in :make_visible did not make the file input visible "
end
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
2016-12-30 20:33:57 +00:00
def _update_style ( element , style )
script = <<-JS
var el = arguments [ 0 ] ;
2017-01-09 20:50:56 +00:00
el . capybara_style_cache = el . style . cssText ;
2016-12-30 20:33:57 +00:00
var css = arguments [ 1 ] ;
for ( var prop in css ) {
if ( css . hasOwnProperty ( prop ) ) {
el . style [ prop ] = css [ prop ]
}
}
JS
begin
session . execute_script ( script , element , style )
rescue Capybara :: NotSupportedByDriverError
2017-01-09 20:50:56 +00:00
warn " The :make_visible option is not supported by the current driver - ignoring "
2016-12-30 20:33:57 +00:00
end
end
2016-11-22 18:45:15 +00:00
2017-01-09 20:50:56 +00:00
def _reset_style ( element )
script = <<-JS
var el = arguments [ 0 ] ;
if ( el . hasOwnProperty ( 'capybara_style_cache' ) ) {
2017-01-09 23:19:12 +00:00
el . style . cssText = el . capybara_style_cache ;
2017-01-09 20:50:56 +00:00
delete el . capybara_style_cache ;
}
JS
begin
session . execute_script ( script , element )
rescue
end
end
2016-11-22 18:45:15 +00:00
def _check_with_label ( selector , checked , locator , options )
locator , options = nil , locator if locator . is_a? Hash
allow_label_click = options . delete ( :allow_label_click ) { Capybara . automatic_label_click }
synchronize ( Capybara :: Queries :: BaseQuery :: wait ( options ) ) do
begin
el = find ( selector , locator , options )
el . set ( checked )
rescue = > e
raise unless allow_label_click && catch_error? ( e )
begin
el || = find ( selector , locator , options . merge ( visible : :all ) )
label = find ( :label , for : el , visible : true )
label . click unless ( el . checked? == checked )
rescue
raise e
end
end
end
end
2010-07-10 00:20:32 +00:00
end
end
end