module Selenium::WebDriver::KeyActions

Public Instance Methods

key_down(*args, device: nil) click to toggle source

Performs a key press. Does not release the key - subsequent interactions may assume it's kept pressed. Note that the key is never released implicitly - either ActionBuilder#key_up(key) or ActionBuilder#release_actions must be called to release the key.

@example Press a key

driver.action.key_down(:control).perform

@example Press a key on an element

el = driver.find_element(id: "some_id")
driver.action.key_down(el, :shift).perform

@overload key_down(key, device: nil)

@param [Symbol, String] key The key to press
@param [Symbol, String] device Optional name of the KeyInput device to press the key on

@overload key_down(element, key, device: nil)

@param [Element] element An optional element to move to first
@param [Symbol, String] key The key to press
@param [Symbol, String] device Optional name of the KeyInput device to press the key on

@return [ActionBuilder] A self reference

# File lib/selenium/webdriver/common/interactions/key_actions.rb, line 47
def key_down(*args, device: nil)
  key_action(*args, action: :create_key_down, device: device)
end
key_up(*args, device: nil) click to toggle source

Performs a key release. Releasing a non-depressed key will yield undefined behaviour.

@example Release a key

driver.action.key_up(:shift).perform

@example Release a key from an element

el = driver.find_element(id: "some_id")
driver.action.key_up(el, :alt).perform

@overload key_up(key, device: nil)

@param [Symbol, String] key The key to press
@param [Symbol, String] device Optional name of the KeyInput device to press the key on

@overload key_up(element, key, device: nil)

@param [Element] element An optional element to move to first
@param [Symbol, String] key The key to release
@param [Symbol, String] device Optional name of the KeyInput device to release the key on

@return [ActionBuilder] A self reference

# File lib/selenium/webdriver/common/interactions/key_actions.rb, line 74
def key_up(*args, device: nil)
  key_action(*args, action: :create_key_up, device: device)
end
send_keys(*args, device: nil) click to toggle source

Sends keys to the active element. This differs from calling Element#send_keys(keys) on the active element in two ways:

  • The modifier keys included in this call are not released.

  • There is no attempt to re-focus the element - so send_keys(:tab) for switching elements should work.

@example Send the text “help” to an element

el = driver.find_element(id: "some_id")
driver.action.send_keys(el, "help").perform

@example Send the text “help” to the currently focused element

driver.action.send_keys("help").perform

@overload send_keys(keys, device: nil)

@param [Array, Symbol, String] keys The key(s) to press and release
@param [Symbol, String] device Optional name of the KeyInput device to press and release the keys on

@overload send_keys(element, keys, device: nil)

@param [Element] element An optional element to move to first
@param [Array, Symbol, String] keys The key(s) to press and release
@param [Symbol, String] device Optional name of the KeyInput device to press and release the keys on

@return [ActionBuilder] A self reference

# File lib/selenium/webdriver/common/interactions/key_actions.rb, line 104
def send_keys(*args, device: nil)
  click(args.shift) if args.first.is_a? Element
  args.map { |x| x.is_a?(String) ? x.chars : x }.flatten.each do |arg|
    key_down(arg, device: device)
    key_up(arg, device: device)
  end
  self
end

Private Instance Methods

key_action(*args, action: nil, device: nil) click to toggle source

@api private

@overload key_down(key, action: nil, device: nil)

@param [Symbol, String] key The key to press
@param [Symbol] action The name of the key action to perform
@param [Symbol, String] device Optional name of the KeyInput device to press the key on

@overload key_down(element, key, action: nil, device: nil)

@param [Element] element An optional element to move to first
@param [Symbol, String] key The key to press
@param [Symbol] action The name of the key action to perform
@param [Symbol, String] device Optional name of the KeyInput device to press the key on

@param [Array] args @option args [Element] element An optional element to move to first @option args [Symbol, String] key The key to perform the action with @param [Symbol] action The name of the key action to perform @param [Symbol, String] device optional name of the KeyInput device to press the key on @return [ActionBuilder] A self reference

# File lib/selenium/webdriver/common/interactions/key_actions.rb, line 136
def key_action(*args, action: nil, device: nil)
  key_input = key_input(device)
  click(args.shift) if args.first.is_a? Element
  key_input.send(action, args.last)
  tick(key_input)
  self
end
key_input(name = nil) click to toggle source
# File lib/selenium/webdriver/common/interactions/key_actions.rb, line 144
def key_input(name = nil)
  device(name: name, type: Interactions::KEY) || add_key_input('keyboard')
end