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

SemanticsNodeInteraction

public final class SemanticsNodeInteraction


Represents a semantics node and the path to fetch it from the semantics tree. One can interact with this node by performing actions such as performClick, assertions such as assertHasClickAction, or navigate to other nodes such as onChildren.

An instance of SemanticsNodeInteraction can be obtained from onNode and convenience methods that use a specific filter, such as onNodeWithText.

Here you can see how you can locate a checkbox, click it and verify that it's checked:

import androidx.compose.ui.test.assertIsOn
import androidx.compose.ui.test.isToggleable
import androidx.compose.ui.test.performClick

composeTestRule.onNode(isToggleable())
    .performClick()
    .assertIsOn()

useUnmergedTree is for tests with a special need to inspect implementation detail within children. For example:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.testTag
import androidx.compose.ui.test.assertLeftPositionInRootIsEqualTo
import androidx.compose.ui.test.assertTopPositionInRootIsEqualTo
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.unit.dp

composeTestRule.setContent {
    // Box is a semantically merging composable. All testTags of its
    // children are merged up into it in the merged semantics tree.
    Box(Modifier.testTag("box").padding(16.dp)) {
        Box(Modifier.testTag("icon").size(48.dp))
    }
}

// Verify the position of the inner box. Without `useUnmergedTree`, the
// test would check the position of the outer box (which is `(0, 0)`)
// instead of the position of the inner box (which is `(16, 16)`).
composeTestRule.onNodeWithTag("icon", useUnmergedTree = true)
    .assertLeftPositionInRootIsEqualTo(16.dp)
    .assertTopPositionInRootIsEqualTo(16.dp)

Summary

Public constructors

SemanticsNodeInteraction(
    @NonNull TestContext testContext,
    boolean useUnmergedTree,
    @NonNull SemanticsMatcher matcher
)
SemanticsNodeInteraction(
    @NonNull TestContext testContext,
    boolean useUnmergedTree,
    @NonNull SemanticsSelector selector
)

Public methods

final void

Asserts that no item was found or that the item is no longer in the hierarchy.

final @NonNull SemanticsNodeInteraction
assertExists(String errorMessageOnFail)

Asserts that the component was found and is part of the component tree.

final @NonNull SemanticsNode
fetchSemanticsNode(String errorMessageOnFail)

Returns the semantics node captured by this object.

Extension functions

final @NonNull SemanticsNodeInteraction

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

final @NonNull SemanticsNodeInteraction

This method is deprecated. Replaced by performTouchInput

final @NonNull SemanticsNodeInteraction

Executes the key input gesture specified in the given block.

final @NonNull SemanticsNodeInteraction

Executes the mouse gesture specified in the given block.

final @NonNull SemanticsNodeInteraction

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

final @NonNull SemanticsNodeInteraction

Send the specified RotaryScrollEvent to the focused component.

final @NonNull SemanticsNodeInteraction

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

final @NonNull SemanticsNodeInteraction
ActionsKt.performScrollToIndex(
    @NonNull SemanticsNodeInteraction receiver,
    int index
)

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

final @NonNull SemanticsNodeInteraction

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

final @NonNull SemanticsNodeInteraction

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

final @NonNull SemanticsNodeInteraction

Provides support to call custom semantics actions on this node.

final @NonNull SemanticsNodeInteraction

Provides support to call custom semantics actions on this node.

final @NonNull SemanticsNodeInteraction

Executes the touch gesture specified in the given block.

final @NonNull ImageBitmap

Captures the underlying semantics node's surface into bitmap.

final @NonNull SemanticsNodeInteraction
AssertionsKt.assert(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull SemanticsMatcher matcher,
    Function0<@NonNull String> messagePrefixOnError
)

Asserts that the provided matcher is satisfied for this node.

final @NonNull SemanticsNodeInteraction
AssertionsKt.assertContentDescriptionContains(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String value,
    boolean substring,
    boolean ignoreCase
)

Asserts that the node's content description contains the given value.

final @NonNull SemanticsNodeInteraction

Asserts that the node's content description contains exactly the given values and nothing else.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node has a click action.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node has doesn't have a click action.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is displayed on screen.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is enabled.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node has a focus.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is not displayed on screen.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is not enabled.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node does not have a focus.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is not selected.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is unchecked.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is checked.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is selectable.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is selected.

final @NonNull SemanticsNodeInteraction

Asserts that the current semantics node is toggleable.

final @NonNull SemanticsNodeInteraction

Asserts the node's range info equals the given value.

final @NonNull SemanticsNodeInteraction
AssertionsKt.assertTextContains(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String value,
    boolean substring,
    boolean ignoreCase
)

Asserts that the node's text contains the given value.

final @NonNull SemanticsNodeInteraction
AssertionsKt.assertTextEquals(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String values,
    boolean includeEditableText
)

Asserts that the node's text contains exactly the given values and nothing else.

final @NonNull SemanticsNodeInteraction

Asserts the node's value equals the given value.

final @NonNull SemanticsNodeInteraction
BoundsAssertionsKt.assertHeightIsAtLeast(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedMinHeight
)

Asserts that the layout of this node has height that is greater than or equal to expectedMinHeight.

final @NonNull SemanticsNodeInteraction

Asserts that the layout of this node has height equal to expectedHeight.

final @NonNull SemanticsNodeInteraction

Asserts that the layout of this node has the left position in the root composable that is equal to the given position.

final @NonNull SemanticsNodeInteraction
BoundsAssertionsKt.assertPositionInRootIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedLeft,
    @NonNull Dp expectedTop
)

Asserts that the layout of this node has position in the root composable that is equal to the given position.

final @NonNull SemanticsNodeInteraction

Asserts that the layout of this node has the top position in the root composable that is equal to the given position.

final @NonNull SemanticsNodeInteraction

Asserts that the touch bounds of this node has height equal to expectedHeight.

final @NonNull SemanticsNodeInteraction

Asserts that the touch bounds of this node has width equal to expectedWidth.

final @NonNull SemanticsNodeInteraction
BoundsAssertionsKt.assertWidthIsAtLeast(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedMinWidth
)

Asserts that the layout of this node has width that is greater than or equal to expectedMinWidth.

final @NonNull SemanticsNodeInteraction

Asserts that the layout of this node has width equal to expectedWidth.

final @NonNull Dp

Returns the position of an alignment line, or Dp.Unspecified if the line is not provided.

final @NonNull DpRect

Returns the bounds of the layout of this node as clipped to the root.

final @NonNull DpRect

Returns the bounds of the layout of this node.

final boolean

Send the specified KeyEvent to the focused component.

final void
OutputKt.printToLog(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String tag,
    int maxDepth
)

Prints all the semantics nodes information into logs (as debug level).

final @NonNull String
OutputKt.printToString(
    @NonNull SemanticsNodeInteraction receiver,
    int maxDepth
)

Prints all the semantics nodes information it holds into string.

final @NonNull SemanticsNodeInteractionCollection

Returns all the ancestors of this node.

final @NonNull SemanticsNodeInteraction

Returns exactly one child of this node.

final @NonNull SemanticsNodeInteraction
SelectorsKt.onChildAt(
    @NonNull SemanticsNodeInteraction receiver,
    int index
)

Returns child of this node at the given index.

final @NonNull SemanticsNodeInteractionCollection

Returns children of this node.

final @NonNull SemanticsNodeInteraction

Returns a parent of this node.

final @NonNull SemanticsNodeInteraction

Returns exactly one sibling of this node.

final @NonNull SemanticsNodeInteractionCollection

Returns all siblings of this node.

final void

Sends to this node the IME action associated with it in a similar way to the IME.

final void

Clears the text in this node in similar way to IME.

final void

Sends the given text to this node in similar way to IME.

final void

Sends the given selection to this node in similar way to IME.

final void

Replaces existing text with the given text in this node in similar way to IME.

Public constructors

SemanticsNodeInteraction

public SemanticsNodeInteraction(
    @NonNull TestContext testContext,
    boolean useUnmergedTree,
    @NonNull SemanticsMatcher matcher
)

SemanticsNodeInteraction

public SemanticsNodeInteraction(
    @NonNull TestContext testContext,
    boolean useUnmergedTree,
    @NonNull SemanticsSelector selector
)

Public methods

assertDoesNotExist

public final void assertDoesNotExist()

Asserts that no item was found or that the item is no longer in the hierarchy.

This will synchronize with the UI and fetch all the nodes again to ensure it has latest data.

Throws
kotlin.AssertionError

if the assert fails.

assertExists

public final @NonNull SemanticsNodeInteraction assertExists(String errorMessageOnFail)

Asserts that the component was found and is part of the component tree.

This will synchronize with the UI and fetch all the nodes again to ensure it has latest data. If you are using fetchSemanticsNode you don't need to call this. In fact you would just introduce additional overhead.

Parameters
String errorMessageOnFail

Error message prefix to be added to the message in case this asserts fails. This is typically used by operations that rely on this assert. Example prefix could be: "Failed to perform doOnClick.".

Throws
kotlin.AssertionError

if the assert fails.

fetchSemanticsNode

public final @NonNull SemanticsNode fetchSemanticsNode(String errorMessageOnFail)

Returns the semantics node captured by this object.

Note: Accessing this object involves synchronization with your UI. If you are accessing this multiple times in one atomic operation, it is better to cache the result instead of calling this API multiple times.

This will fail if there is 0 or multiple nodes matching.

Throws
kotlin.AssertionError

if 0 or multiple nodes found.

Extension functions

ActionsKt.performClick

public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performGesture

public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performKeyInput

@ExperimentalTestApi
public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performMouseInput

@ExperimentalTestApi
public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performMultiModalInput

public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performRotaryScrollInput

@ExperimentalTestApi
public final @NonNull SemanticsNodeInteraction ActionsKt.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.

ActionsKt.performScrollTo

public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performScrollToIndex

public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performScrollToKey

public final @NonNull SemanticsNodeInteraction ActionsKt.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

ActionsKt.performScrollToNode

public final @NonNull SemanticsNodeInteraction ActionsKt.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.

ActionsKt.performSemanticsAction

public final @NonNull SemanticsNodeInteraction ActionsKt.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.

ActionsKt.performSemanticsAction

public final @NonNull SemanticsNodeInteraction <T extends Function<@NonNull Boolean>> ActionsKt.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.

ActionsKt.performTouchInput

public final @NonNull SemanticsNodeInteraction ActionsKt.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

AndroidImageHelpersKt.captureToImage

@RequiresApi
public final @NonNull ImageBitmap AndroidImageHelpersKt.captureToImage(
    @NonNull SemanticsNodeInteraction receiver
)

Captures the underlying semantics node's surface into bitmap. This can be used to capture nodes in a normal composable, a dialog if API >=28 and in a Popup. Note that the mechanism used to capture the bitmap from a Popup is not the same as from a normal composable, since a PopUp is in a different window.

Throws
kotlin.IllegalArgumentException

if we attempt to capture a bitmap of a dialog before API 28.

AssertionsKt.assert

public final @NonNull SemanticsNodeInteraction AssertionsKt.assert(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull SemanticsMatcher matcher,
    Function0<@NonNull String> messagePrefixOnError
)

Asserts that the provided matcher is satisfied for this node.

Parameters
@NonNull SemanticsMatcher matcher

Matcher to verify.

Function0<@NonNull String> messagePrefixOnError

Prefix to be put in front of an error that gets thrown in case this assert fails. This can be helpful in situations where this assert fails as part of a bigger operation that used this assert as a precondition check.

Throws
kotlin.AssertionError

if the matcher does not match or the node can no longer be found.

AssertionsKt.assertContentDescriptionContains

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertContentDescriptionContains(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String value,
    boolean substring,
    boolean ignoreCase
)

Asserts that the node's content description contains the given value.

Note that in merged semantics tree there can be a list of content descriptions that got merged from the child nodes. Typically an accessibility tooling will decide based on its heuristics which ones to announce.

Throws AssertionError if the node's value does not contain value, or if the node has no value

Parameters
@NonNull String value

Value to match as one of the items in the list of content descriptions.

boolean substring

Whether this can be satisfied as a substring match of an item in the list of descriptions.

boolean ignoreCase

Whether case should be ignored.

AssertionsKt.assertContentDescriptionEquals

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertContentDescriptionEquals(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String values
)

Asserts that the node's content description contains exactly the given values and nothing else.

Note that in merged semantics tree there can be a list of content descriptions that got merged from the child nodes. Typically an accessibility tooling will decide based on its heuristics which ones to announce.

Throws AssertionError if the node's descriptions don't contain all items from values, or if the descriptions contain extra items that are not in values.

Parameters
@NonNull String values

List of values to match (the order does not matter)

AssertionsKt.assertHasClickAction

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertHasClickAction(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node has a click action.

Throws AssertionError if the node is doesn't have a click action.

AssertionsKt.assertHasNoClickAction

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertHasNoClickAction(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node has doesn't have a click action.

Throws AssertionError if the node has a click action.

AssertionsKt.assertIsDisplayed

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsDisplayed(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is displayed on screen.

Throws AssertionError if the node is not displayed.

AssertionsKt.assertIsEnabled

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsEnabled(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is enabled.

Throws AssertionError if the node is not enabled or does not define the property at all.

AssertionsKt.assertIsFocused

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsFocused(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node has a focus.

Throws AssertionError if the node is not in the focus or does not defined the property at all.

AssertionsKt.assertIsNotDisplayed

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsNotDisplayed(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is not displayed on screen.

Throws AssertionError if the node is displayed.

AssertionsKt.assertIsNotEnabled

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsNotEnabled(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is not enabled.

Throws AssertionError if the node is enabled or does not defined the property at all.

AssertionsKt.assertIsNotFocused

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsNotFocused(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node does not have a focus.

Throws AssertionError if the node is in the focus or does not defined the property at all.

AssertionsKt.assertIsNotSelected

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsNotSelected(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is not selected.

Throws AssertionError if the node is selected or not selectable.

AssertionsKt.assertIsOff

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsOff(@NonNull SemanticsNodeInteraction receiver)

Asserts that the current semantics node is unchecked.

Throws AssertionError if the node is checked, indeterminate, or not toggleable.

AssertionsKt.assertIsOn

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsOn(@NonNull SemanticsNodeInteraction receiver)

Asserts that the current semantics node is checked.

Throws AssertionError if the node is not unchecked, indeterminate, or not toggleable.

AssertionsKt.assertIsSelectable

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsSelectable(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is selectable.

Throws AssertionError if the node is not selectable.

AssertionsKt.assertIsSelected

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsSelected(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is selected.

Throws AssertionError if the node is unselected or not selectable.

AssertionsKt.assertIsToggleable

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertIsToggleable(
    @NonNull SemanticsNodeInteraction receiver
)

Asserts that the current semantics node is toggleable.

Throws AssertionError if the node is not toggleable.

AssertionsKt.assertRangeInfoEquals

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertRangeInfoEquals(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull ProgressBarRangeInfo value
)

Asserts the node's range info equals the given value.

For further details please check SemanticsProperties.ProgressBarRangeInfo. Throws AssertionError if the node's value is not equal to value, or if the node has no value

AssertionsKt.assertTextContains

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertTextContains(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String value,
    boolean substring,
    boolean ignoreCase
)

Asserts that the node's text contains the given value.

This will also search in SemanticsProperties.EditableText.

Note that in merged semantics tree there can be a list of text items that got merged from the child nodes. Typically an accessibility tooling will decide based on its heuristics which ones to use.

Throws AssertionError if the node's value does not contain value, or if the node has no value

Parameters
@NonNull String value

Value to match as one of the items in the list of text values.

boolean substring

Whether this can be satisfied as a substring match of an item in the list of text.

boolean ignoreCase

Whether case should be ignored.

See also
Text

AssertionsKt.assertTextEquals

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertTextEquals(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String values,
    boolean includeEditableText
)

Asserts that the node's text contains exactly the given values and nothing else.

This will also search in SemanticsProperties.EditableText by default.

Note that in merged semantics tree there can be a list of text items that got merged from the child nodes. Typically an accessibility tooling will decide based on its heuristics which ones to use.

Throws AssertionError if the node's text values don't contain all items from values, or if the text values contain extra items that are not in values.

Parameters
@NonNull String values

List of values to match (the order does not matter)

boolean includeEditableText

Whether to also assert against the editable text.

AssertionsKt.assertValueEquals

public final @NonNull SemanticsNodeInteraction AssertionsKt.assertValueEquals(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String value
)

Asserts the node's value equals the given value.

For further details please check SemanticsProperties.StateDescription. Throws AssertionError if the node's value is not equal to value, or if the node has no value

BoundsAssertionsKt.assertHeightIsAtLeast

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertHeightIsAtLeast(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedMinHeight
)

Asserts that the layout of this node has height that is greater than or equal to expectedMinHeight.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertHeightIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertHeightIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedHeight
)

Asserts that the layout of this node has height equal to expectedHeight.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertLeftPositionInRootIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertLeftPositionInRootIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedLeft
)

Asserts that the layout of this node has the left position in the root composable that is equal to the given position.

Parameters
@NonNull Dp expectedLeft

The left (x) position to assert.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertPositionInRootIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertPositionInRootIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedLeft,
    @NonNull Dp expectedTop
)

Asserts that the layout of this node has position in the root composable that is equal to the given position.

Parameters
@NonNull Dp expectedLeft

The left (x) position to assert.

@NonNull Dp expectedTop

The top (y) position to assert.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertTopPositionInRootIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertTopPositionInRootIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedTop
)

Asserts that the layout of this node has the top position in the root composable that is equal to the given position.

Parameters
@NonNull Dp expectedTop

The top (y) position to assert.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertTouchHeightIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertTouchHeightIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedHeight
)

Asserts that the touch bounds of this node has height equal to expectedHeight.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertTouchWidthIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertTouchWidthIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedWidth
)

Asserts that the touch bounds of this node has width equal to expectedWidth.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertWidthIsAtLeast

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertWidthIsAtLeast(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedMinWidth
)

Asserts that the layout of this node has width that is greater than or equal to expectedMinWidth.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.assertWidthIsEqualTo

public final @NonNull SemanticsNodeInteraction BoundsAssertionsKt.assertWidthIsEqualTo(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull Dp expectedWidth
)

Asserts that the layout of this node has width equal to expectedWidth.

Throws
kotlin.AssertionError

if comparison fails.

BoundsAssertionsKt.getAlignmentLinePosition

public final @NonNull Dp BoundsAssertionsKt.getAlignmentLinePosition(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull AlignmentLine alignmentLine
)

Returns the position of an alignment line, or Dp.Unspecified if the line is not provided.

BoundsAssertionsKt.getBoundsInRoot

public final @NonNull DpRect BoundsAssertionsKt.getBoundsInRoot(
    @NonNull SemanticsNodeInteraction receiver
)

Returns the bounds of the layout of this node as clipped to the root. The bounds are relative to the root composable.

BoundsAssertionsKt.getUnclippedBoundsInRoot

public final @NonNull DpRect BoundsAssertionsKt.getUnclippedBoundsInRoot(
    @NonNull SemanticsNodeInteraction receiver
)

Returns the bounds of the layout of this node. The bounds are relative to the root composable.

KeyInputHelpersKt.performKeyPress

public final boolean KeyInputHelpersKt.performKeyPress(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull KeyEvent keyEvent
)

Send the specified KeyEvent to the focused component.

Returns
boolean

true if the event was consumed. False otherwise.

OutputKt.printToLog

public final void OutputKt.printToLog(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String tag,
    int maxDepth
)

Prints all the semantics nodes information into logs (as debug level).

By default this also prints all the sub-hierarchy. This can be changed by setting a custom max depth in maxDepth.

Note that this will fetch the latest snapshot of nodes it sees in the hierarchy for the IDs it collected before. So the output can change over time if the tree changes.

Parameters
@NonNull String tag

The tag to be used in the log messages.

int maxDepth

Max depth of the nodes in hierarchy to print. Zero will print just this node. Must not be negative.

OutputKt.printToString

public final @NonNull String OutputKt.printToString(
    @NonNull SemanticsNodeInteraction receiver,
    int maxDepth
)

Prints all the semantics nodes information it holds into string.

By default this also prints all the sub-hierarchy. This can be changed by setting a custom max depth in maxDepth.

Note that this will fetch the latest snapshot of nodes it sees in the hierarchy for the IDs it collected before. So the output can change over time if the tree changes.

Parameters
int maxDepth

Max depth of the nodes in hierarchy to print. Zero will print just this node. Must not be negative.

SelectorsKt.onAncestors

public final @NonNull SemanticsNodeInteractionCollection SelectorsKt.onAncestors(@NonNull SemanticsNodeInteraction receiver)

Returns all the ancestors of this node.

Example: For the following tree

|-A
|-B
|-C <- this node
Returns B, A

SelectorsKt.onChild

public final @NonNull SemanticsNodeInteraction SelectorsKt.onChild(@NonNull SemanticsNodeInteraction receiver)

Returns exactly one child of this node.

Use this only if this node has exactly one child.

Any subsequent operation on its result will expect exactly one element found (unless SemanticsNodeInteraction.assertDoesNotExist is used) and will throw AssertionError if none or more than one element is found.

SelectorsKt.onChildAt

public final @NonNull SemanticsNodeInteraction SelectorsKt.onChildAt(
    @NonNull SemanticsNodeInteraction receiver,
    int index
)

Returns child of this node at the given index.

This is just a shortcut for "childrenindex".

SelectorsKt.onChildren

public final @NonNull SemanticsNodeInteractionCollection SelectorsKt.onChildren(@NonNull SemanticsNodeInteraction receiver)

Returns children of this node.

SelectorsKt.onParent

public final @NonNull SemanticsNodeInteraction SelectorsKt.onParent(@NonNull SemanticsNodeInteraction receiver)

Returns a parent of this node.

Any subsequent operation on its result will expect exactly one element found (unless SemanticsNodeInteraction.assertDoesNotExist is used) and will throw AssertionError if none or more than one element is found.

SelectorsKt.onSibling

public final @NonNull SemanticsNodeInteraction SelectorsKt.onSibling(@NonNull SemanticsNodeInteraction receiver)

Returns exactly one sibling of this node.

Use this only if this node has exactly one sibling.

Any subsequent operation on its result will expect exactly one element found (unless SemanticsNodeInteraction.assertDoesNotExist is used) and will throw AssertionError if none or more than one element is found.

SelectorsKt.onSiblings

public final @NonNull SemanticsNodeInteractionCollection SelectorsKt.onSiblings(@NonNull SemanticsNodeInteraction receiver)

Returns all siblings of this node.

Example: For the following tree

|-A
|-B1
|-B2 <- this node
|-B3
Returns B1, B3

TextActionsKt.performImeAction

public final void TextActionsKt.performImeAction(
    @NonNull SemanticsNodeInteraction receiver
)

Sends to this node the IME action associated with it in a similar way to the IME.

The node needs to define its IME action in semantics via SemanticsPropertyReceiver.performImeAction.

Throws
kotlin.AssertionError

if the node does not support input or does not define IME action.

kotlin.IllegalStateException

if the node did is not an editor or would not be able to establish an input connection (e.g. does not define ImeAction or PerformImeAction or is not focused).

TextActionsKt.performTextClearance

public final void TextActionsKt.performTextClearance(
    @NonNull SemanticsNodeInteraction receiver
)

Clears the text in this node in similar way to IME.

TextActionsKt.performTextInput

public final void TextActionsKt.performTextInput(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String text
)

Sends the given text to this node in similar way to IME.

Parameters
@NonNull String text

Text to send.

TextActionsKt.performTextInputSelection

@ExperimentalTestApi
public final void TextActionsKt.performTextInputSelection(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull TextRange selection
)

Sends the given selection to this node in similar way to IME.

Parameters
@NonNull TextRange selection

selection to send

TextActionsKt.performTextReplacement

public final void TextActionsKt.performTextReplacement(
    @NonNull SemanticsNodeInteraction receiver,
    @NonNull String text
)

Replaces existing text with the given text in this node in similar way to IME.

This does not reflect text selection. All the text gets cleared out and new inserted.

Parameters
@NonNull String text

Text to send.