Package org.openqa.selenium.interactions
Class Actions
java.lang.Object
org.openqa.selenium.interactions.Actions
The user-facing API for emulating complex user gestures. Use this class rather than using the
Keyboard or Mouse directly.
Implements the builder pattern: Builds a CompositeAction containing all actions specified by the method calls.
Call perform()
at the end of the method chain to actually perform the actions.
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionbuild()
Generates a composite action containing all actions so far, ready to be performed (and resets the internal builder state, so subsequent calls to this method will contain fresh sequences).click()
Clicks at the current mouse location.click
(WebElement target) Clicks in the middle of the given element.Clicks (without releasing) at the current mouse location.clickAndHold
(WebElement target) Clicks (without releasing) in the middle of the given element.Performs a context-click at the current mouse location.contextClick
(WebElement target) Performs a context-click at middle of the given element.Performs a double-click at the current mouse location.doubleClick
(WebElement target) Performs a double-click at middle of the given element.dragAndDrop
(WebElement source, WebElement target) 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.dragAndDropBy
(WebElement source, int xOffset, int yOffset) A convenience method that performs click-and-hold at the location of the source element, moves by a given offset, then releases the mouse.keyDown
(CharSequence key) Performs a modifier key press.keyDown
(WebElement target, CharSequence key) Performs a modifier key press after focusing on an element.keyUp
(CharSequence key) Performs a modifier key release.keyUp
(WebElement target, CharSequence key) Performs a modifier key release after focusing on an element.moveByOffset
(int xOffset, int yOffset) Moves the mouse from its current position (or 0,0) by the given offset.moveToElement
(WebElement target) Moves the mouse to the middle of the element.moveToElement
(WebElement target, int xOffset, int yOffset) Moves the mouse to an offset from the element's in-view center point.moveToLocation
(int xCoordinate, int yCoordinate) Moves the mouse to provided coordinates on screen regardless of starting position of the mouse.pause
(long pause) Performs a pause.void
perform()
A convenience method for performing the actions without calling build() first.release()
Releases the depressed left mouse button at the current mouse location.release
(WebElement target) Releases the depressed left mouse button, in the middle of the given element.scrollByAmount
(int deltaX, int deltaY) Scrolls by provided amounts with the origin in the top left corner of the viewport.scrollFromOrigin
(WheelInput.ScrollOrigin scrollOrigin, int deltaX, int deltaY) Scrolls by provided amount based on a provided origin.scrollToElement
(WebElement element) If the element is outside the viewport, scrolls the bottom of the element to the bottom of the viewport.sendKeys
(CharSequence... keys) Sends keys to the active element.sendKeys
(WebElement target, CharSequence... keys) Equivalent to calling: Actions.click(element).sendKeys(keysToSend). This method is different fromWebElement.sendKeys(CharSequence...)
- seesendKeys(CharSequence...)
for details how.setActiveKeyboard
(String name) setActivePointer
(PointerInput.Kind kind, String name) setActiveWheel
(String name) tick
(Interaction... actions)
-
Constructor Details
-
Actions
-
Actions
-
-
Method Details
-
keyDown
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 keyUp(theKey) or sendKeys(Keys.NULL) must be called to release the modifier.- Parameters:
key
-- Returns:
- A self reference.
-
keyDown
Performs a modifier key press after focusing on an element. Equivalent to: Actions.click(element).sendKeys(theKey);- Parameters:
key
-target
- WebElement to perform the action- Returns:
- A self reference.
- See Also:
-
keyUp
Performs a modifier key release. Releasing a non-depressed modifier key will yield undefined behaviour.- Parameters:
key
-- Returns:
- A self reference.
-
keyUp
Performs a modifier key release after focusing on an element. Equivalent to: Actions.click(element).sendKeys(theKey);- Parameters:
key
-target
- WebElement to perform the action on- Returns:
- A self reference.
- See Also:
-
sendKeys
Sends keys to the active element. This differs from callingWebElement.sendKeys(CharSequence...)
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 sendKeys(Keys.TAB) for switching elements should work.
- Parameters:
keys
- The keys.- Returns:
- A self reference.
- Throws:
IllegalArgumentException
- if keys is null- See Also:
-
sendKeys
Equivalent to calling: Actions.click(element).sendKeys(keysToSend). This method is different fromWebElement.sendKeys(CharSequence...)
- seesendKeys(CharSequence...)
for details how.- Parameters:
target
- element to focus on.keys
- The keys.- Returns:
- A self reference.
- Throws:
IllegalArgumentException
- if keys is null- See Also:
-
clickAndHold
Clicks (without releasing) in the middle of the given element. This is equivalent to: Actions.moveToElement(onElement).clickAndHold()- Parameters:
target
- Element to move to and click.- Returns:
- A self reference.
-
clickAndHold
Clicks (without releasing) at the current mouse location.- Returns:
- A self reference.
-
release
Releases the depressed left mouse button, in the middle of the given element. This is equivalent to: Actions.moveToElement(onElement).release()Invoking this action without invoking
clickAndHold()
first will result in undefined behaviour.- Parameters:
target
- Element to release the mouse button above.- Returns:
- A self reference.
-
scrollToElement
If the element is outside the viewport, scrolls the bottom of the element to the bottom of the viewport.- Parameters:
element
- Which element to scroll into the viewport.- Returns:
- A self reference.
-
scrollByAmount
Scrolls by provided amounts with the origin in the top left corner of the viewport.- Parameters:
deltaX
- The distance along X axis to scroll using the wheel. A negative value scrolls left.deltaY
- The distance along Y axis to scroll using the wheel. A negative value scrolls up.- Returns:
- A self reference.
-
scrollFromOrigin
Scrolls by provided amount based on a provided origin. The scroll origin is either the center of an element or the upper left of the viewport plus any offsets. If the origin is an element, and the element is not in the viewport, the bottom of the element will first be scrolled to the bottom of the viewport.- Parameters:
scrollOrigin
- Where scroll originates (viewport or element center) plus provided offsets.deltaX
- The distance along X axis to scroll using the wheel. A negative value scrolls left.deltaY
- The distance along Y axis to scroll using the wheel. A negative value scrolls up.- Returns:
- A self reference.
- Throws:
MoveTargetOutOfBoundsException
- If the origin with offset is outside the viewport.
-
release
Releases the depressed left mouse button at the current mouse location.- Returns:
- A self reference.
- See Also:
-
click
Clicks in the middle of the given element. Equivalent to: Actions.moveToElement(onElement).click()- Parameters:
target
- Element to click.- Returns:
- A self reference.
-
click
Clicks at the current mouse location. Useful when combined withmoveToElement(org.openqa.selenium.WebElement, int, int)
ormoveByOffset(int, int)
.- Returns:
- A self reference.
-
doubleClick
Performs a double-click at middle of the given element. Equivalent to: Actions.moveToElement(element).doubleClick()- Parameters:
target
- Element to move to.- Returns:
- A self reference.
-
doubleClick
Performs a double-click at the current mouse location.- Returns:
- A self reference.
-
moveToElement
Moves the mouse to the middle of the element. The element is scrolled into view and its location is calculated using getClientRects.- Parameters:
target
- element to move to.- Returns:
- A self reference.
-
moveToElement
Moves the mouse to an offset from the element's in-view center point.- Parameters:
target
- element to move to.xOffset
- Offset from the element's in-view center point. A negative value means an offset left of the point.yOffset
- Offset from the element's in-view center point. A negative value means an offset above the point.- Returns:
- A self reference.
-
moveByOffset
Moves the mouse from its current position (or 0,0) by the given offset. If the final coordinates of the move are outside the viewport (the mouse will end up outside the browser window), an exception is raised.- Parameters:
xOffset
- horizontal offset. A negative value means moving the mouse left.yOffset
- vertical offset. A negative value means moving the mouse up.- Returns:
- A self reference.
- Throws:
MoveTargetOutOfBoundsException
- if the provided offset is outside the document's boundaries.
-
moveToLocation
Moves the mouse to provided coordinates on screen regardless of starting position of the mouse. If the coordinates provided are outside the viewport (the mouse will end up outside the browser window), an exception is raised.- Parameters:
xCoordinate
- positive pixel value along horizontal axis in viewport. Numbers increase going right.yCoordinate
- positive pixel value along vertical axis in viewport. Numbers increase going down.- Returns:
- A self reference.
- Throws:
MoveTargetOutOfBoundsException
- if the provided offset is outside the document's boundaries.
-
contextClick
Performs a context-click at middle of the given element. First performs a mouseMove to the location of the element.- Parameters:
target
- Element to move to.- Returns:
- A self reference.
-
contextClick
Performs a context-click at the current mouse location.- Returns:
- A self reference.
-
dragAndDrop
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.- Parameters:
source
- element to emulate button down at.target
- element to move to and release the mouse at.- Returns:
- A self reference.
-
dragAndDropBy
A convenience method that performs click-and-hold at the location of the source element, moves by a given offset, then releases the mouse.- Parameters:
source
- element to emulate button down at.xOffset
- horizontal move offset.yOffset
- vertical move offset.- Returns:
- A self reference.
-
pause
Performs a pause.- Parameters:
pause
- pause duration, in milliseconds.- Returns:
- A self reference.
-
pause
-
tick
-
setActiveKeyboard
-
setActivePointer
-
setActiveWheel
-
getActiveKeyboard
-
getActivePointer
-
getActiveWheel
-
getActionDuration
-
build
Generates a composite action containing all actions so far, ready to be performed (and resets the internal builder state, so subsequent calls to this method will contain fresh sequences).Warning: you may want to call
perform()
instead to actually perform the actions.- Returns:
- the composite action
-
perform
public void perform()A convenience method for performing the actions without calling build() first. -
getSequences
-