Class: Selenium::WebDriver::ActionBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/selenium/webdriver/common/action_builder.rb

Overview

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 Driver#action

Examples:


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

Direct Known Subclasses

TouchActionBuilder

Instance Method Summary collapse

Constructor Details

#initialize(mouse, keyboard) ⇒ ActionBuilder

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of ActionBuilder.



43
44
45
46
47
48
49
50
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 43

def initialize(mouse, keyboard)
  @devices = {
    mouse: mouse,
    keyboard: keyboard
  }

  @actions = []
end

Instance Method Details

#click(element = nil) ⇒ ActionBuilder

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.

Examples:

Clicking on an element


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

Clicking at the current mouse position


driver.action.click.perform

Parameters:

Returns:



203
204
205
206
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 203

def click(element = nil)
  @actions << [:mouse, :click, [element]]
  self
end

#click_and_hold(element = nil) ⇒ ActionBuilder

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

driver.action.move_to(element).click_and_hold

Examples:

Clicking and holding on some element


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

Parameters:

  • element (Element) (defaults to: nil) —

    the element to move to and click.

Returns:



162
163
164
165
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 162

def click_and_hold(element = nil)
  @actions << [:mouse, :down, [element]]
  self
end

#context_click(element = nil) ⇒ ActionBuilder

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

Examples:

Context-click at middle of given element


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

Parameters:

Returns:



299
300
301
302
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 299

def context_click(element = nil)
  @actions << [:mouse, :context_click, [element]]
  self
end

#double_click(element = nil) ⇒ ActionBuilder

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

driver.action.move_to(element).double_click

Examples:

Double click an element


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

Parameters:

Returns:



222
223
224
225
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 222

def double_click(element = nil)
  @actions << [:mouse, :double_click, [element]]
  self
end

#drag_and_drop(source, target) ⇒ ActionBuilder

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.

Examples:

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

Parameters:

Returns:



321
322
323
324
325
326
327
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 321

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) ⇒ ActionBuilder

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

Examples:

Drag and drop an element by offset


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

Parameters:

  • source (Selenium::WebDriver::Element) —

    Element to emulate button down at.

  • right_by (Integer) —

    horizontal move offset.

  • down_by (Integer) —

    vertical move offset.

Returns:



344
345
346
347
348
349
350
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 344

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(key) ⇒ ActionBuilder #key_down(element, key) ⇒ ActionBuilder

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)

Examples:

Press a key


driver.action.key_down(:control).perform

Press a key on an element


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

Overloads:

  • #key_down(key) ⇒ ActionBuilder

    Parameters:

    • key (:shift, :alt, :control, :command, :meta) —

      The modifier key to press

  • #key_down(element, key) ⇒ ActionBuilder

    Parameters:

    • element (Element) —

      An optional element to move to first

    • key (:shift, :alt, :control, :command, :meta) —

      The modifier key to press

Returns:

Raises:

  • (ArgumentError) —

    if the given key is not a modifier



80
81
82
83
84
85
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 80

def key_down(*args)
  @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element

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

#key_up(key) ⇒ ActionBuilder #key_up(element, key) ⇒ ActionBuilder

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

Examples:

Release a key


driver.action.key_up(:shift).perform

Release a key from an element


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

Overloads:

  • #key_up(key) ⇒ ActionBuilder

    Parameters:

    • key (:shift, :alt, :control, :command, :meta) —

      The modifier key to release

  • #key_up(element, key) ⇒ ActionBuilder

    Parameters:

    • element (Element) —

      An optional element to move to first

    • key (:shift, :alt, :control, :command, :meta) —

      The modifier key to release

Returns:

Raises:

  • (ArgumentError) —

    if the given key is not a modifier



109
110
111
112
113
114
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 109

def key_up(*args)
  @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element

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

#move_by(right_by, down_by) ⇒ ActionBuilder

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.

Examples:

Move the mouse to a certain offset from its current position


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

Parameters:

  • right_by (Integer) —

    horizontal offset. A negative value means moving the mouse left.

  • down_by (Integer) —

    vertical offset. A negative value means moving the mouse up.

Returns:

Raises:

  • (MoveTargetOutOfBoundsError) —

    if the provided offset is outside the document’s boundaries.



281
282
283
284
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 281

def move_by(right_by, down_by)
  @actions << [:mouse, :move_by, [Integer(right_by), Integer(down_by)]]
  self
end

#move_to(element, right_by = nil, down_by = nil) ⇒ ActionBuilder

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.

Examples:

Scroll element into view and move the mouse to it


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

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

Parameters:

  • element (Selenium::WebDriver::Element) —

    to move to.

  • right_by (Integer) (defaults to: nil) —

    Optional offset from the top-left corner. A negative value means coordinates right from the element.

  • down_by (Integer) (defaults to: nil) —

    Optional offset from the top-left corner. A negative value means coordinates above the element.

Returns:



252
253
254
255
256
257
258
259
260
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 252

def move_to(element, right_by = nil, down_by = nil)
  @actions << if right_by && down_by
                [:mouse, :move_to, [element, Integer(right_by), Integer(down_by)]]
              else
                [:mouse, :move_to, [element]]
              end

  self
end

#perform ⇒ Object

Executes the actions added to the builder.



356
357
358
359
360
361
362
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 356

def perform
  @actions.each do |receiver, method, args|
    @devices.fetch(receiver).__send__(method, *args)
  end

  nil
end

#release(element = nil) ⇒ ActionBuilder

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

Examples:

Releasing an element after clicking and holding it


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

Returns:



178
179
180
181
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 178

def release(element = nil)
  @actions << [:mouse, :up, [element]]
  self
end

#send_keys(keys) ⇒ ActionBuilder #send_keys(element, keys) ⇒ ActionBuilder

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.

Examples:

Send the text “help” to an element


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

Send the text “help” to the currently focused element


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

Overloads:

  • #send_keys(keys) ⇒ ActionBuilder

    Parameters:

    • keys (Array, Symbol, String) —

      The key(s) to press and release

  • #send_keys(element, keys) ⇒ ActionBuilder

    Parameters:

    • element (Element) —

      An optional element to move to first

    • keys (Array, Symbol, String) —

      The key(s) to press and release

Returns:



140
141
142
143
144
145
 
# File 'lib/selenium/webdriver/common/action_builder.rb', line 140

def send_keys(*args)
  @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element

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