class Selenium::WebDriver::ActionBuilder

The ActionBuilder provides the user a way to set up and perform complex user interactions.

This class should not be instantiated directly, but is created by Selenium::WebDriver::DriverExtensions::HasInputDevices#action, which is available on Driver instances that support the user interaction API.

@example

driver.action.key_down(:shift).
              click(element).
              click(second_element).
              key_up(:shift).
              drag_and_drop(element, third_element).
              perform

Public Class Methods

new(mouse, keyboard) click to toggle source

@api private

# File lib/selenium/webdriver/common/action_builder.rb, line 28
def initialize(mouse, keyboard)
  @devices    = {
    :mouse    => mouse,
    :keyboard => keyboard
  }

  @actions  = []
end

Public Instance Methods

click(element = nil) click to toggle source

Clicks in the middle of the given element. Equivalent to:

driver.action.move_to(element).click

When no element is passed, the current mouse position will be clicked.

@example Clicking on an element

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

@example Clicking at the current mouse position

driver.action.click.perform

@param [Selenium::WebDriver::Element] element An optional element to click. @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 186
def click(element = nil)
  @actions << [:mouse, :click, [element]]
  self
end
click_and_hold(element = nil) click to toggle source

Clicks (without releasing) in the middle of the given element. This is equivalent to:

driver.action.move_to(element).click_and_hold

@example Clicking and holding on some element

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

@param [Selenium::WebDriver::Element] element the element to move to and click. @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 145
def click_and_hold(element = nil)
  @actions << [:mouse, :down, [element]]
  self
end
context_click(element = nil) click to toggle source

Performs a context-click at middle of the given element. First performs a #move_to to the location of the element.

@example Context-click at middle of given element

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

@param [Selenium::WebDriver::Element] element An element to context click. @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 282
def context_click(element = nil)
  @actions << [:mouse, :context_click, [element]]
  self
end
double_click(element = nil) click to toggle source

Performs a double-click at middle of the given element. Equivalent to:

driver.action.move_to(element).double_click

@example Double click an element

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

@param [Selenium::WebDriver::Element] element An optional element to move to. @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 205
def double_click(element = nil)
  @actions << [:mouse, :double_click, [element]]
  self
end
drag_and_drop(source, target) click to toggle source

A convenience method that performs click-and-hold at the location of the source element, moves to the location of the target element, then releases the mouse.

@example Drag and drop one element onto another

el1 = driver.find_element(:id, "some_id1")
el2 = driver.find_element(:id, "some_id2")
driver.action.drag_and_drop(el1, el2).perform

@param [Selenium::WebDriver::Element] source element to emulate button down at. @param [Selenium::WebDriver::Element] target element to move to and release the

mouse at.

@return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 304
def drag_and_drop(source, target)
  click_and_hold source
  move_to        target
  release        target

  self
end
drag_and_drop_by(source, right_by, down_by) click to toggle source

A convenience method that performs click-and-hold at the location of the source element, moves by a given offset, then releases the mouse.

@example Drag and drop an element by offset

el = driver.find_element(:id, "some_id1")
driver.action.drag_and_drop_by(el, 100, 100).perform

@param [Selenium::WebDriver::Element] source Element to emulate button down at. @param [Integer] right_by horizontal move offset. @param [Integer] down_by vertical move offset. @param [Selenium::WebDriver::Element] target Element to move to and release the

mouse at.

@return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 329
def drag_and_drop_by(source, right_by, down_by)
  click_and_hold source
  move_by        right_by, down_by
  release

  self
end
key_down(*args) click to toggle source

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

Equivalent to:

driver.action.click(element).send_keys(key)
# or
driver.action.click.send_keys(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

@param [:shift, :alt, :control, :command, :meta] The key to press. @param [Selenium::WebDriver::Element] element An optional element @raise [ArgumentError] if the given key is not a modifier @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 63
def key_down(*args)
  if args.first.kind_of? Element
    @actions << [:mouse, :click, [args.shift]]
  end

  @actions << [:keyboard, :press, args]
  self
end
key_up(*args) click to toggle source

Performs a modifier key release. Releasing a non-depressed modifier 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

@param [:shift, :alt, :control, :command, :meta] The modifier key to release. @param [Selenium::WebDriver::Element] element An optional element @raise [ArgumentError] if the given key is not a modifier key @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 91
def key_up(*args)
  if args.first.kind_of? Element
    @actions << [:mouse, :click, [args.shift]]
  end

  @actions << [:keyboard, :release, args]
  self
end
move_by(right_by, down_by) click to toggle source

Moves the mouse from its current position (or 0,0) by the given offset. If the coordinates provided are outside the viewport (the mouse will end up outside the browser window) then the viewport is scrolled to match.

@example Move the mouse to a certain offset from its current position

driver.action.move_by(100, 100).perform

@param [Integer] right_by horizontal offset. A negative value means moving the

mouse left.

@param [Integer] down_by vertical offset. A negative value means moving the mouse

up.

@return [ActionBuilder] A self reference. @raise [MoveTargetOutOfBoundsError] if the provided offset is outside

the document's boundaries.
# File lib/selenium/webdriver/common/action_builder.rb, line 264
def move_by(right_by, down_by)
  @actions << [:mouse, :move_by, [right_by, down_by]]
  self
end
move_to(element, right_by = nil, down_by = nil) click to toggle source

Moves the mouse to the middle of the given element. The element is scrolled into view and its location is calculated using getBoundingClientRect. Then the mouse is moved to optional offset coordinates from the element.

Note that when using offsets, both coordinates need to be passed.

@example Scroll element into view and move the mouse to it

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

@example

el = driver.find_element(:id, "some_id")
driver.action.move_to(el, 100, 100).perform

@param [Selenium::WebDriver::Element] element to move to. @param [Integer] right_by Optional offset from the top-left corner. A negative value means

coordinates right from the element.

@param [Integer] down_by Optional offset from the top-left corner. A negative value means

coordinates above the element.

@return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 235
def move_to(element, right_by = nil, down_by = nil)
  if right_by && down_by
    @actions << [:mouse, :move_to, [element, right_by, down_by]]
  else
    @actions << [:mouse, :move_to, [element]]
  end

  self
end
perform() click to toggle source

Executes the actions added to the builder.

# File lib/selenium/webdriver/common/action_builder.rb, line 342
def perform
  @actions.each { |receiver, method, args|
    @devices.fetch(receiver).__send__(method, *args)
  }

  nil
end
release(element = nil) click to toggle source

Releases the depressed left mouse button at the current mouse location.

@example Releasing an element after clicking and holding it

el = driver.find_element(:id, "some_id")
driver.action.click_and_hold(el).release.perform

@return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 161
def release(element = nil)
  @actions << [:mouse, :up, [element]]
  self
end
send_keys(*args) click to toggle source

Sends keys to the active element. This differs from calling Selenium::WebDriver::Element#send_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

@param [Selenium::WebDriver::Element] element An optional element @param [String] keys The keys to be sent. @return [ActionBuilder] A self reference.

# File lib/selenium/webdriver/common/action_builder.rb, line 121
def send_keys(*args)
  if args.first.kind_of? Element
    @actions << [:mouse, :click, [args.shift]]
  end

  @actions << [:keyboard, :send_keys, args]
  self
end