{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ActionsKt

public final class ActionsKt


Summary

Public methods

static final @NonNull SemanticsNodeInteraction

Performs a click action on the element represented by the given semantics node.

static final @NonNull SemanticsNodeInteraction

This method is deprecated. Replaced by performTouchInput

static final @NonNull SemanticsNodeInteraction

Executes the key input gesture specified in the given block.

static final @NonNull SemanticsNodeInteraction

Executes the mouse gesture specified in the given block.

static final @NonNull SemanticsNodeInteraction

Executes the multi-modal gesture specified in the given block.

static final @NonNull SemanticsNodeInteraction

Send the specified RotaryScrollEvent to the focused component.

static final @NonNull SemanticsNodeInteraction

Scrolls the closest enclosing scroll parent by the smallest amount such that this node is fully visible in its viewport.

static final @NonNull SemanticsNodeInteraction
performScrollToIndex(
    @NonNull SemanticsNodeInteraction receiver,
    int index
)

Scrolls a scrollable container with items to the item with the given index.

static final @NonNull SemanticsNodeInteraction

Scrolls a scrollable container with keyed items to the item with the given key, such as LazyColumn or LazyRow.

static final @NonNull SemanticsNodeInteraction

Scrolls a scrollable container to the content that matches the given matcher.

static final @NonNull SemanticsNodeInteraction

Provides support to call custom semantics actions on this node.

static final @NonNull SemanticsNodeInteraction
<T extends Function<@NonNull Boolean>> performSemanticsAction(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull SemanticsPropertyKey<@NonNull AccessibilityAction<@NonNull T>> key,
    @NonNull Function1<@NonNull T, Unit> invocation
)

Provides support to call custom semantics actions on this node.

static final @NonNull SemanticsNodeInteraction

Executes the touch gesture specified in the given block.

Public methods

performClick

public static final @NonNull SemanticsNodeInteraction performClick(@NonNull SemanticsNodeInteraction receiver)

Performs a click action on the element represented by the given semantics node. Depending on the platform this may be implemented by a touch click (tap), a mouse click, or another more appropriate method for that platform.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performGesture

public static final @NonNull SemanticsNodeInteraction performGesture(
    @NonNull SemanticsNodeInteraction receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull GestureScopeUnit> block
)

Executes the (partial) gesture specified in the given block. The gesture doesn't need to be complete and can be resumed in a later invocation of performGesture. The event time is initialized to the current time of the MainTestClock.

Be aware that if you split a gesture over multiple invocations of performGesture, everything that happens in between will run as if the gesture is still ongoing (imagine a finger still touching the screen).

All events that are injected from the block are batched together and sent after block is complete. This method blocks while the events are injected. If an error occurs during execution of block or injection of the events, all (subsequent) events are dropped and the error is thrown here.

Due to the batching of events, all events in a block are sent together and no recomposition will take place in between events. Additionally all events will be generated before any of the events take effect. This means that the screen coordinates of all events are resolved before any of the events can cause the position of the node being injected into to change. This has certain advantages, for example, in the cases of nested scrolling or dragging an element around, it prevents the injection of events into a moving target since all events are enqueued before any of them has taken effect.

Example of performing a click:

import androidx.compose.ui.test.click
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performGesture

composeTestRule.onNodeWithTag("myComponent")
    .performGesture { click() }
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull GestureScopeUnit> block

A lambda with GestureScope as receiver that describes the gesture by sending all touch events.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performKeyInput

@ExperimentalTestApi
public static final @NonNull SemanticsNodeInteraction performKeyInput(
    @NonNull SemanticsNodeInteraction receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block
)

Executes the key input gesture specified in the given block. The gesture doesn't need to be complete and can be resumed in a later invocation of one of the perform.*Input methods. The event time is initialized to the current time of the MainTestClock.

All events that are injected from the block are batched together and sent after block is complete. This method blocks while the events are injected. If an error occurs during execution of block or injection of the events, all (subsequent) events are dropped and the error is thrown here.

Due to the batching of events, all events in a block are sent together and no recomposition will take place in between events. Additionally all events will be generated before any of the events take effect. This means that the screen coordinates of all events are resolved before any of the events can cause the position of the node being injected into to change. This has certain advantages, for example, in the cases of nested scrolling or dragging an element around, it prevents the injection of events into a moving target since all events are enqueued before any of them has taken effect.

Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block

A lambda with KeyInjectionScope as receiver that describes the gesture by sending all key press events.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performMouseInput

@ExperimentalTestApi
public static final @NonNull SemanticsNodeInteraction performMouseInput(
    @NonNull SemanticsNodeInteraction receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull MouseInjectionScopeUnit> block
)

Executes the mouse gesture specified in the given block. The gesture doesn't need to be complete and can be resumed in a later invocation of one of the perform.*Input methods. The event time is initialized to the current time of the MainTestClock.

Be aware that if you split a gesture over multiple invocations of perform.*Input, everything that happens in between will run as if the gesture is still ongoing (imagine a mouse button still being pressed).

All events that are injected from the block are batched together and sent after block is complete. This method blocks while the events are injected. If an error occurs during execution of block or injection of the events, all (subsequent) events are dropped and the error is thrown here.

Due to the batching of events, all events in a block are sent together and no recomposition will take place in between events. Additionally all events will be generated before any of the events take effect. This means that the screen coordinates of all events are resolved before any of the events can cause the position of the node being injected into to change. This has certain advantages, for example, in the cases of nested scrolling or dragging an element around, it prevents the injection of events into a moving target since all events are enqueued before any of them has taken effect.

Example of performing a mouse click:

import androidx.compose.ui.test.click
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule.onNodeWithTag("myComponent")
    .performMouseInput {
        click(center)
    }

Example of scrolling the mouse wheel while the mouse button is pressed:

import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule.onNodeWithTag("myComponent")
    .performMouseInput {
        press()
        repeat(6) {
            advanceEventTime()
            scroll(-1f)
        }
        advanceEventTime()
        release()
    }
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull MouseInjectionScopeUnit> block

A lambda with MouseInjectionScope as receiver that describes the gesture by sending all mouse events.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performMultiModalInput

public static final @NonNull SemanticsNodeInteraction performMultiModalInput(
    @NonNull SemanticsNodeInteraction receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull MultiModalInjectionScopeUnit> block
)

Executes the multi-modal gesture specified in the given block. The gesture doesn't need to be complete and can be resumed in a later invocation of one of the perform.*Input methods. The event time is initialized to the current time of the MainTestClock. If only a single modality is needed (e.g. touch, mouse, stylus, keyboard, etc), you should use the perform.*Input of that modality instead.

Functions for each modality can be called by invoking that modality's function, like touch to inject touch events. This allows you to inject events for each modality.

Be aware that if you split a gesture over multiple invocations of perform.*Input, everything that happens in between will run as if the gesture is still ongoing (imagine a finger still touching the screen).

All events that are injected from the block are batched together and sent after block is complete. This method blocks while the events are injected. If an error occurs during execution of block or injection of the events, all (subsequent) events are dropped and the error is thrown here.

Due to the batching of events, all events in a block are sent together and no recomposition will take place in between events. Additionally all events will be generated before any of the events take effect. This means that the screen coordinates of all events are resolved before any of the events can cause the position of the node being injected into to change. This has certain advantages, for example, in the cases of nested scrolling or dragging an element around, it prevents the injection of events into a moving target since all events are enqueued before any of them has taken effect.

Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull MultiModalInjectionScopeUnit> block

A lambda with MultiModalInjectionScope as receiver that describes the gesture by sending all multi modal events.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performRotaryScrollInput

@ExperimentalTestApi
public static final @NonNull SemanticsNodeInteraction performRotaryScrollInput(
    @NonNull SemanticsNodeInteraction receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull RotaryInjectionScopeUnit> block
)

Send the specified RotaryScrollEvent to the focused component.

Returns
@NonNull SemanticsNodeInteraction

true if the event was consumed. False otherwise.

performScrollTo

public static final @NonNull SemanticsNodeInteraction performScrollTo(@NonNull SemanticsNodeInteraction receiver)

Scrolls the closest enclosing scroll parent by the smallest amount such that this node is fully visible in its viewport. If this node is larger than the viewport, scrolls the scroll parent by the smallest amount such that this node fills the entire viewport. A scroll parent is a parent node that has the semantics action SemanticsActions.ScrollBy (usually implemented by defining scrollBy).

This action should be performed on the node that is part of the scrollable content, not on the scrollable container.

Throws an AssertionError if there is no scroll parent.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performScrollToIndex

public static final @NonNull SemanticsNodeInteraction performScrollToIndex(
    @NonNull SemanticsNodeInteraction receiver,
    int index
)

Scrolls a scrollable container with items to the item with the given index.

Note that not all scrollable containers have item indices. For example, a scrollable doesn't have items with an index, while LazyColumn does.

This action should be performed on a node that is a scrollable container, not on a node that is part of the content of that container.

Throws an AssertionError if the node doesn't have ScrollToIndex defined.

Parameters
int index

The index of the item to scroll to

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performScrollToKey

public static final @NonNull SemanticsNodeInteraction performScrollToKey(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Object key
)

Scrolls a scrollable container with keyed items to the item with the given key, such as LazyColumn or LazyRow.

This action should be performed on a node that is a scrollable container, not on a node that is part of the content of that container.

Throws an AssertionError if the node doesn't have IndexForKey or ScrollToIndex defined.

Parameters
@NonNull Object key

The key of the item to scroll to

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

performScrollToNode

public static final @NonNull SemanticsNodeInteraction performScrollToNode(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull SemanticsMatcher matcher
)

Scrolls a scrollable container to the content that matches the given matcher. If the content isn't yet visible, the scrollable container will be scrolled from the start till the end till it finds the content we're looking for. It is not defined where in the viewport the content will be on success of this function, but it will be either fully within the viewport if it is smaller than the viewport, or it will cover the whole viewport if it is larger than the viewport. If it doesn't find the content, the scrollable will be left at the end of the content and an AssertionError is thrown.

This action should be performed on a node that is a scrollable container, not on a node that is part of the content of that container. If the container is a lazy container, it must support the semantics actions ScrollToIndex, ScrollBy, and either HorizontalScrollAxisRange or VerticalScrollAxisRange, for example LazyColumn and LazyRow. If the container is not lazy, it must support the semantics action ScrollBy, for example, Row or Column.

Throws an AssertionError if the scrollable node doesn't support the necessary semantics actions.

Parameters
@NonNull SemanticsMatcher matcher

A matcher that identifies the content where the scrollable container needs to scroll to

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method. Note that this is not an interaction for the node that is identified by the matcher.

performSemanticsAction

public static final @NonNull SemanticsNodeInteraction performSemanticsAction(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull SemanticsPropertyKey<@NonNull AccessibilityAction<@NonNull Function0<@NonNull Boolean>>> key
)

Provides support to call custom semantics actions on this node.

This method is for calling actions that have no parameters.

This will properly verify that the actions exists and provide clear error message in case it does not. It also handle synchronization and performing the action on the UI thread. This call is blocking until the action is performed

Parameters
@NonNull SemanticsPropertyKey<@NonNull AccessibilityAction<@NonNull Function0<@NonNull Boolean>>> key

Key of the action to be performed.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

Throws
kotlin.AssertionError

If the semantics action is not defined on this node.

performSemanticsAction

public static final @NonNull SemanticsNodeInteraction <T extends Function<@NonNull Boolean>> performSemanticsAction(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull SemanticsPropertyKey<@NonNull AccessibilityAction<@NonNull T>> key,
    @NonNull Function1<@NonNull T, Unit> invocation
)

Provides support to call custom semantics actions on this node.

This method is supposed to be used for actions with parameters.

This will properly verify that the actions exists and provide clear error message in case it does not. It also handle synchronization and performing the action on the UI thread. This call is blocking until the action is performed

Parameters
@NonNull SemanticsPropertyKey<@NonNull AccessibilityAction<@NonNull T>> key

Key of the action to be performed.

@NonNull Function1<@NonNull T, Unit> invocation

Place where you call your action. In the argument is provided the underlying action from the given Semantics action.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method

Throws
kotlin.AssertionError

If the semantics action is not defined on this node.

performTouchInput

public static final @NonNull SemanticsNodeInteraction performTouchInput(
    @NonNull SemanticsNodeInteraction receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull TouchInjectionScopeUnit> block
)

Executes the touch gesture specified in the given block. The gesture doesn't need to be complete and can be resumed in a later invocation of one of the perform.*Input methods. The event time is initialized to the current time of the MainTestClock.

Be aware that if you split a gesture over multiple invocations of perform.*Input, everything that happens in between will run as if the gesture is still ongoing (imagine a finger still touching the screen).

All events that are injected from the block are batched together and sent after block is complete. This method blocks while the events are injected. If an error occurs during execution of block or injection of the events, all (subsequent) events are dropped and the error is thrown here.

Due to the batching of events, all events in a block are sent together and no recomposition will take place in between events. Additionally all events will be generated before any of the events take effect. This means that the screen coordinates of all events are resolved before any of the events can cause the position of the node being injected into to change. This has certain advantages, for example, in the cases of nested scrolling or dragging an element around, it prevents the injection of events into a moving target since all events are enqueued before any of them has taken effect.

Example of performing a swipe up:

import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTouchInput
import androidx.compose.ui.test.swipeUp

composeTestRule.onNodeWithTag("myComponent")
    .performTouchInput { swipeUp() }

Example of performing an off-center click:

import androidx.compose.ui.test.click
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTouchInput

composeTestRule.onNodeWithTag("myComponent")
    .performTouchInput { click(percentOffset(.2f, .5f)) }

Example of doing an assertion during a click:

import androidx.compose.ui.test.assertHasClickAction
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTouchInput

composeTestRule.onNodeWithTag("myComponent")
    .performTouchInput { down(topLeft) }
    .assertHasClickAction()
    .performTouchInput { up() }

Example of performing a click-and-drag:

import androidx.compose.ui.test.click
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTouchInput
import androidx.compose.ui.test.swipeUp

composeTestRule.onNodeWithTag("myComponent").performTouchInput {
    click()
    advanceEventTime(100)
    swipeUp()
}
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull TouchInjectionScopeUnit> block

A lambda with TouchInjectionScope as receiver that describes the gesture by sending all touch events.

Returns
@NonNull SemanticsNodeInteraction

The SemanticsNodeInteraction that is the receiver of this method