Module: Selenium::WebDriver::PointerActions

Included in:
W3CActionBuilder
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

The overridable duration for movement used by methods in this module



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

def default_move_duration
  @default_move_duration ||= 0.25 # 250 milliseconds
end

Instance Method Details

#click(element = nil, device: nil) ⇒ W3CActionBuilder

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:



235
236
237
238
239
240
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 235

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

#click_and_hold(element = nil, device: nil) ⇒ W3CActionBuilder

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:



189
190
191
192
193
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 189

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

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

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:



292
293
294
295
296
297
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 292

def context_click(element = nil, device: nil)
  move_to(element, device: device) if element
  pointer_down(:right, device: device)
  pointer_up(:right, device: device)
  self
end

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

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:



264
265
266
267
268
269
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 264

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

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:



318
319
320
321
322
323
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 318

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

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:



342
343
344
345
346
347
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 342

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

Moves the mouse from its current position 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.

  • 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.



136
137
138
139
140
141
142
143
144
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 136

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

#move_to(element, right_by = nil, down_by = nil, device: nil) ⇒ W3CActionBuilder

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.

This is adapted to be backward compatible from non-W3C actions. W3C calculates offset from the center point of 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 to the left of the element.

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

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

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

    optional name of the PointerInput device to move.

Returns:



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 98

def move_to(element, right_by = nil, down_by = nil, device: nil)
  pointer = get_pointer(device)
  # New actions offset is from center of element
  if right_by || down_by
    size = element.size
    left_offset = (size[:width] / 2).to_i
    top_offset = (size[:height] / 2).to_i
    left = -left_offset + (right_by || 0)
    top = -top_offset + (down_by || 0)
  else
    left = 0
    top = 0
  end
  pointer.create_pointer_move(duration: default_move_duration,
                              x: left,
                              y: top,
                              element: element)
  tick(pointer)
  self
end

#move_to_location(x, y, device: nil) ⇒ W3CActionBuilder

Moves the mouse to a given location in the viewport. 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 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.



163
164
165
166
167
168
169
170
171
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 163

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

#pointer_down(button, device: nil) ⇒ W3CActionBuilder

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:



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

def pointer_down(button, device: nil)
  button_action(button, action: :create_pointer_down, device: device)
end

#pointer_up(button, device: nil) ⇒ W3CActionBuilder

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:



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

def pointer_up(button, device: nil)
  button_action(button, action: :create_pointer_up, device: device)
end

#release(device: nil) ⇒ W3CActionBuilder

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:



208
209
210
211
 
# File 'lib/selenium/webdriver/common/interactions/pointer_actions.rb', line 208

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