org.openqa.selenium.interactions

Class Actions

java.lang.Object

org.openqa.selenium.interactions.Actions

Direct Known Subclasses:

TouchActions

public class Actions
extends 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
protected Keyboard	keyboard
protected Mouse	mouse

Constructor Summary

Constructors

Constructor and Description
Actions(Keyboard keyboard) Only used by the TouchActions class.
Actions(Keyboard keyboard, Mouse mouse) 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).
Actions(WebDriver driver) Default constructor - uses the default keyboard, mouse implemented by the driver.

Method Summary

Methods

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 onElement) Clicks in the middle of the given element.
Actions	clickAndHold() Clicks (without releasing) at the current mouse location.
Actions	clickAndHold(WebElement onElement) Clicks (without releasing) in the middle of the given element.
Actions	contextClick() Performs a context-click at the current mouse location.
Actions	contextClick(WebElement onElement) Performs a context-click at middle of the given element.
Actions	doubleClick() Performs a double-click at the current mouse location.
Actions	doubleClick(WebElement onElement) 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(Keys theKey) Performs a modifier key press.
Actions	keyDown(WebElement element, Keys theKey) Performs a modifier key press after focusing on an element.
Actions	keyUp(Keys theKey) Performs a modifier key release.
Actions	keyUp(WebElement element, Keys theKey) 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 toElement) Moves the mouse to the middle of the element.
Actions	moveToElement(WebElement toElement, int xOffset, int yOffset) Moves the mouse to an offset from the top-left corner of the element.
Actions	pause(long pause) Deprecated. 'Pause' is considered to be a bad design practice.
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 onElement) Releases the depressed left mouse button, in the middle of the given element.
Actions	sendKeys(CharSequence... keysToSend) Sends keys to the active element.
Actions	sendKeys(WebElement element, CharSequence... keysToSend) Equivalent to calling: Actions.click(element).sendKeys(keysToSend). This method is different from WebElement.sendKeys(CharSequence...) - see sendKeys(CharSequence...) for details how.

Methods inherited from class java.lang.Object

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

Field Detail

mouse

protected Mouse mouse

keyboard

protected Keyboard keyboard

action

protected CompositeAction action

Constructor Detail

Actions

public Actions(WebDriver driver)

Default constructor - uses the default keyboard, mouse implemented by the driver.

Parameters:

driver - the driver providing the implementations to use.

Actions

public Actions(Keyboard keyboard,
       Mouse mouse)

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

public Actions(Keyboard keyboard)

Only used by the TouchActions class.

Parameters:

keyboard - implementation to delegate to.

Method Detail

keyDown

public Actions keyDown(Keys theKey)

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:

theKey - 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 element,
              Keys theKey)

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

Parameters:

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

Returns:

A self reference.

See Also:

keyDown(org.openqa.selenium.Keys)

keyUp

public Actions keyUp(Keys theKey)

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

Parameters:

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

Returns:

A self reference.

keyUp

public Actions keyUp(WebElement element,
            Keys theKey)

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

Parameters:

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

Returns:

A self reference.

See Also:

on behaviour regarding non-depressed modifier keys.

sendKeys

public Actions sendKeys(CharSequence... keysToSend)

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:

keysToSend - The keys.

Returns:

A self reference.

See Also:

WebElement.sendKeys(CharSequence...)

sendKeys

public Actions sendKeys(WebElement element,
               CharSequence... keysToSend)

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

Parameters:

element - element to focus on.

keysToSend - The keys.

Returns:

A self reference.

See Also:

sendKeys(java.lang.CharSequence[])

clickAndHold

public Actions clickAndHold(WebElement onElement)

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

Parameters:

onElement - 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 onElement)

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:

onElement - 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 onElement)

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

Parameters:

onElement - 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 onElement)

Performs a double-click at middle of the given element. Equivalent to: Actions.moveToElement(element).doubleClick()

Parameters:

onElement - 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 toElement)

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

Parameters:

toElement - element to move to.

Returns:

A self reference.

moveToElement

public Actions moveToElement(WebElement toElement,
                    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:

toElement - 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 onElement)

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

Parameters:

onElement - 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

@Deprecated
public Actions pause(long pause)

Deprecated. 'Pause' is considered to be a bad design practice.

Performs a pause.

Parameters:

pause - pause duration, in milliseconds.

Returns:

A self reference.

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.