Package org.openqa.selenium.interactions

Class Actions

java.lang.Object
org.openqa.selenium.interactions.Actions
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.

Call perform() at the end of the method chain to actually perform the actions.

  • Constructor Details

  • Method Details

    • keyDown

      public Actions keyDown(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 -
      Returns:
      A self reference.

    • keyDown

      public Actions keyDown(WebElement target, CharSequence key)
      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

      public Actions keyUp(CharSequence key)
      Performs a modifier key release. Releasing a non-depressed modifier key will yield undefined behaviour.
      Parameters:
      key -
      Returns:
      A self reference.

    • keyUp

      public Actions keyUp(WebElement target, CharSequence key)
      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

      public Actions sendKeys(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:
      IllegalArgumentException - if keys is null
      See Also:

    • sendKeys

      public Actions sendKeys(WebElement target, 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:
      IllegalArgumentException - if keys is null
      See Also:

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

    • scrollToElement

      public Actions scrollToElement(WebElement element)
      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

      public Actions scrollByAmount(int deltaX, int deltaY)
      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

      public Actions scrollFromOrigin(WheelInput.ScrollOrigin scrollOrigin, int deltaX, int deltaY)
      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

      public Actions release()
      Releases the depressed left mouse button at the current mouse location.
      Returns:
      A self reference.
      See Also:

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

      public Actions moveByOffset(int xOffset, int yOffset)
      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

      public Actions moveToLocation(int xCoordinate, int yCoordinate)
      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

      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(Duration duration)

    • tick

      public Actions tick(Interaction... actions)

    • setActiveKeyboard

      public Actions setActiveKeyboard(String name)

    • setActivePointer

      public Actions setActivePointer(PointerInput.Kind kind, String name)

    • setActiveWheel

      public Actions setActiveWheel(String name)

    • getActiveKeyboard

      public KeyInput getActiveKeyboard()

    • getActivePointer

      public PointerInput getActivePointer()

    • getActiveWheel

      public WheelInput getActiveWheel()

    • getActionDuration

      public Duration getActionDuration()

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

      public Collection<Sequence> getSequences()