org.openqa.selenium.interactions

Class Actions

java.lang.Object

org.openqa.selenium.interactions.Actions

Direct Known Subclasses:

TouchActions

public class Actions
extends java.lang.Object

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.

Field Summary

Fields

Modifier and Type	Field and Description
protected CompositeAction	action

Constructor Summary

Constructors

Constructor and Description
Actions(Keyboard keyboard) Deprecated. Use the new interactions API.
Actions(Keyboard keyboard, Mouse mouse) Deprecated. Use the new interactions APIs.
Actions(WebDriver driver)

Method Summary

Modifier and Type	Method and Description
Action	build() Generates a composite action containing all actions so far, ready to be performed (and resets the internal builder state, so subsequent calls to build() will contain fresh sequences).
Actions	click() Clicks at the current mouse location.
Actions	click(WebElement target) Clicks in the middle of the given element.
Actions	clickAndHold() Clicks (without releasing) at the current mouse location.
Actions	clickAndHold(WebElement target) Clicks (without releasing) in the middle of the given element.
Actions	contextClick() Performs a context-click at the current mouse location.
Actions	contextClick(WebElement target) Performs a context-click at middle of the given element.
Actions	doubleClick() Performs a double-click at the current mouse location.
Actions	doubleClick(WebElement target) Performs a double-click at middle of the given element.
Actions	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.
Actions	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.
Actions	keyDown(java.lang.CharSequence key) Performs a modifier key press.
Actions	keyDown(WebElement target, java.lang.CharSequence key) Performs a modifier key press after focusing on an element.
Actions	keyUp(java.lang.CharSequence key) Performs a modifier key release.
Actions	keyUp(WebElement target, java.lang.CharSequence key) Performs a modifier key release after focusing on an element.
Actions	moveByOffset(int xOffset, int yOffset) Moves the mouse from its current position (or 0,0) by the given offset.
Actions	moveToElement(WebElement target) Moves the mouse to the middle of the element.
Actions	moveToElement(WebElement target, int xOffset, int yOffset) Moves the mouse to an offset from the top-left corner of the element.
Actions	pause(java.time.Duration duration)
Actions	pause(long pause) Performs a pause.
void	perform() A convenience method for performing the actions without calling build() first.
Actions	release() Releases the depressed left mouse button at the current mouse location.
Actions	release(WebElement target) Releases the depressed left mouse button, in the middle of the given element.
Actions	sendKeys(java.lang.CharSequence... keys) Sends keys to the active element.
Actions	sendKeys(WebElement target, java.lang.CharSequence... keys) Equivalent to calling: Actions.click(element).sendKeys(keysToSend). This method is different from WebElement.sendKeys(CharSequence...) - see sendKeys(CharSequence...) for details how.
Actions	tick(Action action)
Actions	tick(Interaction... actions)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

action

protected CompositeAction action

Constructor Detail

Actions

public Actions(WebDriver driver)

Actions

@Deprecated
public Actions(Keyboard keyboard,
                           Mouse mouse)

Deprecated. Use the new interactions APIs.

A constructor that should only be used when the keyboard or mouse were extended to provide additional functionality (for example, dragging-and-dropping from the desktop).

Parameters:

keyboard - the Keyboard implementation to delegate to.

mouse - the Mouse implementation to delegate to.

Actions

@Deprecated
public Actions(Keyboard keyboard)

Deprecated. Use the new interactions API.

Only used by the TouchActions class.

Parameters:

keyboard - implementation to delegate to.

Method Detail

keyDown

public Actions keyDown(java.lang.CharSequence key)

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 - Either Keys.SHIFT, Keys.ALT or Keys.CONTROL. If the provided key is none of those, IllegalArgumentException is thrown.

Returns:

A self reference.

keyDown

public Actions keyDown(WebElement target,
                       java.lang.CharSequence key)

Performs a modifier key press after focusing on an element. Equivalent to: Actions.click(element).sendKeys(theKey);

Parameters:

key - Either Keys.SHIFT, Keys.ALT or Keys.CONTROL. If the provided key is none of those, IllegalArgumentException is thrown.

target - WebElement to perform the action

Returns:

A self reference.

See Also:

keyDown(CharSequence)

keyUp

public Actions keyUp(java.lang.CharSequence key)

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

Parameters:

key - Either Keys.SHIFT, Keys.ALT or Keys.CONTROL.

Returns:

A self reference.

keyUp

public Actions keyUp(WebElement target,
                     java.lang.CharSequence key)

Performs a modifier key release after focusing on an element. Equivalent to: Actions.click(element).sendKeys(theKey);

Parameters:

key - Either Keys.SHIFT, Keys.ALT or Keys.CONTROL.

target - WebElement to perform the action on

Returns:

A self reference.

See Also:

on behaviour regarding non-depressed modifier keys.

sendKeys

public Actions sendKeys(java.lang.CharSequence... keys)

Sends keys to the active element. This differs from calling WebElement.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:

java.lang.IllegalArgumentException - if keys is null

See Also:

WebElement.sendKeys(CharSequence...)

sendKeys

public Actions sendKeys(WebElement target,
                        java.lang.CharSequence... keys)

Equivalent to calling: Actions.click(element).sendKeys(keysToSend). This method is different from WebElement.sendKeys(CharSequence...) - see sendKeys(CharSequence...) for details how.

Parameters:

target - element to focus on.

keys - The keys.

Returns:

A self reference.

Throws:

java.lang.IllegalArgumentException - if keys is null

See Also:

sendKeys(java.lang.CharSequence[])

clickAndHold

public Actions clickAndHold(WebElement target)

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

public Actions clickAndHold()

Clicks (without releasing) at the current mouse location.

Returns:

A self reference.

release

public Actions release(WebElement target)

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.

release

public Actions release()

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

Returns:

A self reference.

See Also:

release(org.openqa.selenium.WebElement)

click

public Actions click(WebElement target)

Clicks in the middle of the given element. Equivalent to: Actions.moveToElement(onElement).click()

Parameters:

target - Element to click.

Returns:

A self reference.

click

public Actions click()

Clicks at the current mouse location. Useful when combined with moveToElement(org.openqa.selenium.WebElement, int, int) or moveByOffset(int, int).

Returns:

A self reference.

doubleClick

public Actions doubleClick(WebElement target)

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

public Actions doubleClick()

Performs a double-click at the current mouse location.

Returns:

A self reference.

moveToElement

public Actions moveToElement(WebElement target)

Moves the mouse to the middle of the element. The element is scrolled into view and its location is calculated using getBoundingClientRect.

Parameters:

target - element to move to.

Returns:

A self reference.

moveToElement

public Actions moveToElement(WebElement target,
                             int xOffset,
                             int yOffset)

Moves the mouse to an offset from the top-left corner of the element. The element is scrolled into view and its location is calculated using getBoundingClientRect.

Parameters:

target - element to move to.

xOffset - Offset from the top-left corner. A negative value means coordinates left from the element.

yOffset - Offset from the top-left corner. A negative value means coordinates above the element.

Returns:

A self reference.

moveByOffset

public Actions moveByOffset(int xOffset,
                            int yOffset)

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.

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.

contextClick

public Actions contextClick(WebElement target)

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

public Actions contextClick()

Performs a context-click at the current mouse location.

Returns:

A self reference.

dragAndDrop

public Actions 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.

Parameters:

source - element to emulate button down at.

target - element to move to and release the mouse at.

Returns:

A self reference.

dragAndDropBy

public Actions 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.

Parameters:

source - element to emulate button down at.

xOffset - horizontal move offset.

yOffset - vertical move offset.

Returns:

A self reference.

pause

public Actions pause(long pause)

Performs a pause.

Parameters:

pause - pause duration, in milliseconds.

Returns:

A self reference.

pause

public Actions pause(java.time.Duration duration)

tick

public Actions tick(Interaction... actions)

tick

public Actions tick(Action action)

build

public Action build()

Generates a composite action containing all actions so far, ready to be performed (and resets the internal builder state, so subsequent calls to build() will contain fresh sequences).

Returns:

the composite action

perform

public void perform()

A convenience method for performing the actions without calling build() first.