Module: Selenium::WebDriver::PointerActions

Included in:
ActionBuilder
Defined in:
lib/selenium/webdriver/common/interactions/pointer_actions.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#default_move_duration ⇒ Object

By default this is set to 250ms in the ActionBuilder constructor It can be overridden with default_move_duration=



30
31
32
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 30

def default_move_duration
  @default_move_duration ||= @duration / 1000.0 # convert ms to seconds
end

Instance Method Details

#click(element = nil, button: nil, device: 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:

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

    An optional element to click.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device with the button that will be clicked

Returns:



226
227
228
229
230
231
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 226

def click(element = nil, button: nil, device: nil)
  move_to(element, device: device) if element
  pointer_down(button || :left, device: device)
  pointer_up(button || :left, device: device)
  self
end

#click_and_hold(element = nil, button: nil, device: 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 (Selenium::WebDriver::Element) (defaults to: nil) —

    the element to move to and click.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device to click with

Returns:



180
181
182
183
184
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 180

def click_and_hold(element = nil, button: nil, device: nil)
  move_to(element, device: device) if element
  pointer_down(button || :left, device: device)
  self
end

#context_click(element = nil, device: nil) ⇒ ActionBuilder

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

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

Examples:

Context-click at middle of given element


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

Context-clicking at the current mouse position


driver.action.context_click.perform

Parameters:

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

    An element to context click.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device with the button that will be context-clicked

Returns:



283
284
285
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 283

def context_click(element = nil, device: nil)
  click(element, button: :right, device: device)
end

#double_click(element = nil, device: nil) ⇒ ActionBuilder

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

driver.action.move_to(element).double_click

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

Examples:

Double-click an element


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

Double-clicking at the current mouse position


driver.action.double_click.perform

Parameters:

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

    An optional element to move to.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device with the button that will be double-clicked

Returns:



255
256
257
258
259
260
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 255

def double_click(element = nil, device: nil)
  move_to(element, device: device) if element
  click(device: device)
  click(device: device)
  self
end

#drag_and_drop(source, target, device: nil) ⇒ 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:

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

    element to emulate button down at.

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

    element to move to and release the mouse at.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device with the button that will perform the drag and drop

Returns:



306
307
308
309
310
311
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 306

def drag_and_drop(source, target, device: nil)
  click_and_hold(source, device: device)
  move_to(target, device: device)
  release(device: device)
  self
end

#drag_and_drop_by(source, right_by, down_by, device: nil) ⇒ 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.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device with the button that will perform the drag and drop

Returns:



330
331
332
333
334
335
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 330

def drag_and_drop_by(source, right_by, down_by, device: nil)
  click_and_hold(source, device: device)
  move_by(right_by, down_by, device: device)
  release(device: device)
  self
end

#move_by(right_by, down_by, device: nil, duration: default_move_duration, **opts) ⇒ ActionBuilder

Moves the pointer from its current position by the given offset.

The viewport is not scrolled if the coordinates provided are outside the viewport. MoveTargetOutOfBoundsError will be raised if the offsets are outside the viewport

Examples:

Move the pointer 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 pointer left.

  • down_by (Integer) —

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

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device to move

Returns:

Raises:

  • (MoveTargetOutOfBoundsError) —

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



125
126
127
128
129
130
131
132
133
134
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 125

def move_by(right_by, down_by, device: nil, duration: default_move_duration, **opts)
  pointer = pointer_input(device)
  pointer.create_pointer_move(duration: duration,
                              x: Integer(right_by),
                              y: Integer(down_by),
                              origin: Interactions::PointerMove::POINTER,
                              **opts)
  tick(pointer)
  self
end

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

Moves the pointer to the in-view center point of the given element. Then the pointer is moved to optional offset coordinates.

The element is not scrolled into view. MoveTargetOutOfBoundsError will be raised if element with offset is outside the viewport

When using offsets, both coordinates need to be passed.

Examples:

Move the pointer to element


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 in-view center of the element. A negative value means coordinates to the left of the center.

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

    Optional offset from the in-view center of the element. A negative value means coordinates to the top of the center.

Returns:



97
98
99
100
101
102
103
104
105
106
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 97

def move_to(element, right_by = nil, down_by = nil, **opts)
  pointer = pointer_input(opts.delete(:device))
  pointer.create_pointer_move(duration: opts.delete(:duration) || default_move_duration,
                              x: right_by || 0,
                              y: down_by || 0,
                              origin: element,
                              **opts)
  tick(pointer)
  self
end

#move_to_location(x, y, device: nil, duration: default_move_duration, **opts) ⇒ ActionBuilder

Moves the pointer to a given location in the viewport.

The viewport is not scrolled if the coordinates provided are outside the viewport. MoveTargetOutOfBoundsError will be raised if the offsets are outside the viewport

Examples:

Move the pointer to a certain position in the viewport


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

Parameters:

  • x (Integer) —

    horizontal position. Equivalent to a css ‘left’ value.

  • y (Integer) —

    vertical position. Equivalent to a css ‘top’ value.

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device to move

Returns:

Raises:

  • (MoveTargetOutOfBoundsError) —

    if the provided x or y value is outside the document’s boundaries.



153
154
155
156
157
158
159
160
161
162
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 153

def move_to_location(x, y, device: nil, duration: default_move_duration, **opts)
  pointer = pointer_input(device)
  pointer.create_pointer_move(duration: duration,
                              x: Integer(x),
                              y: Integer(y),
                              origin: Interactions::PointerMove::VIEWPORT,
                              **opts)
  tick(pointer)
  self
end

#pointer_down(button = :left, device: nil, **opts) ⇒ ActionBuilder

Presses (without releasing) at the current location of the PointerInput device. This is equivalent to:

driver.action.click_and_hold(nil)

Examples:

Clicking and holding at the current location


driver.action.pointer_down(:left).perform

Parameters:

Returns:



49
50
51
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 49

def pointer_down(button = :left, device: nil, **opts)
  button_action(button, :create_pointer_down, device: device, **opts)
end

#pointer_up(button = :left, device: nil, **opts) ⇒ ActionBuilder

Releases the pressed mouse button at the current mouse location of the PointerInput device.

Examples:

Releasing a button after clicking and holding


driver.action.pointer_down(:left).pointer_up(:left).perform

Parameters:

Returns:



66
67
68
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 66

def pointer_up(button = :left, device: nil, **opts)
  button_action(button, :create_pointer_up, device: device, **opts)
end

#release(button: nil, device: 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

Parameters:

  • device (Symbol || String) (defaults to: nil) —

    optional name of the PointerInput device with the button that will be released

Returns:



199
200
201
202
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 199

def release(button: nil, device: nil)
  pointer_up(button || :left, device: device)
  self
end