Package org.openqa.selenium.interactions

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

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

    • Constructor Detail

      • Actions

        public Actions​(WebDriver driver)

    • 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.META, Keys.COMMAND, 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.META, Keys.COMMAND, 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)

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

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

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

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

      • setActiveKeyboard

        public Actions setActiveKeyboard​(java.lang.String name)

      • setActiveWheel

        public Actions setActiveWheel​(java.lang.String name)

      • getActiveKeyboard

        public KeyInput getActiveKeyboard()

      • getActiveWheel

        public WheelInput getActiveWheel()

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