SemanticsNodeInteractionsProvider

Known direct subclasses
ComposeTestRule

A TestRule that allows you to test and control composables, either in isolation or in applications.
ComposeUiTest

A test environment that allows you to test and control composables, either in isolation or in applications.
Known indirect subclasses
AndroidComposeTestRule
AndroidComposeUiTest

Variant of ComposeUiTest for when you want to have access the current activity of type A.
ComposeContentTestRule

A ComposeTestRule that allows you to set content without the necessity to provide a host for the content.

Provides the main entry point into testing.

Typically implemented by a test rule.

Summary

Public functions
SemanticsNodeInteractionCollection
onAllNodes(matcher: SemanticsMatcher, useUnmergedTree: Boolean)

Finds all semantics nodes that match the given condition.
Cmn
SemanticsNodeInteraction
onNode(matcher: SemanticsMatcher, useUnmergedTree: Boolean)

Finds a semantics node that matches the given condition.
Cmn

Extension functions
Unit
SemanticsNodeInteractionsProvider.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis: IndirectPointerEventPrimaryDirectionalMotionAxis,
    inputDeviceSize: IntSize,
    block: IndirectPointerInjectionScope.() -> Unit
)

Executes an indirect pointer gesture globally, targeting the currently focused Compose UI (from root to the focused node).
Cmn
SemanticsNodeInteractionCollection
SemanticsNodeInteractionsProvider.onAllNodesWithContentDescription(
    label: String,
    substring: Boolean,
    ignoreCase: Boolean,
    useUnmergedTree: Boolean
)

Finds all semantics nodes with the given label as content description.
Cmn
SemanticsNodeInteractionCollection
SemanticsNodeInteractionsProvider.onAllNodesWithTag(
    testTag: String,
    useUnmergedTree: Boolean
)

Finds all semantics nodes identified by the given tag.
Cmn
SemanticsNodeInteractionCollection
SemanticsNodeInteractionsProvider.onAllNodesWithText(
    text: String,
    substring: Boolean,
    ignoreCase: Boolean,
    useUnmergedTree: Boolean
)

Finds all semantics nodes with the given text.
Cmn
SemanticsNodeInteraction
SemanticsNodeInteractionsProvider.onNodeWithContentDescription(
    label: String,
    substring: Boolean,
    ignoreCase: Boolean,
    useUnmergedTree: Boolean
)

Finds a semantics node with the given content description.
Cmn
SemanticsNodeInteraction
SemanticsNodeInteractionsProvider.onNodeWithTag(
    testTag: String,
    useUnmergedTree: Boolean
)

Finds a semantics node identified by the given tag.
Cmn
SemanticsNodeInteraction
SemanticsNodeInteractionsProvider.onNodeWithText(
    text: String,
    substring: Boolean,
    ignoreCase: Boolean,
    useUnmergedTree: Boolean
)

Finds a semantics node with the given text.
Cmn
SemanticsNodeInteraction

Finds the root semantics node of the Compose tree.
Cmn

Public functions

onAllNodes

Cmn
Added in 1.0.0
fun onAllNodes(matcher: SemanticsMatcher, useUnmergedTree: Boolean = false): SemanticsNodeInteractionCollection

Finds all semantics nodes that match the given condition.

If you are working with elements that are not supposed to occur multiple times use onNode instead.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
matcher: SemanticsMatcher

Matcher used for filtering.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree. This allows you to search for individual nodes that would otherwise be part of a larger semantic unit, for example a text and an image forming a Button together.
See also
onNode

onNode

Cmn
Added in 1.0.0
fun onNode(matcher: SemanticsMatcher, useUnmergedTree: Boolean = false): SemanticsNodeInteraction

Finds a semantics node that matches the given condition.

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

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
matcher: SemanticsMatcher

Matcher used for filtering
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree. This allows you to search for individual nodes that would otherwise be part of a larger semantic unit, for example a text and an image forming a Button together.
See also
onAllNodes

to work with multiple elements

Extension functions

SemanticsNodeInteractionsProvider.performIndirectPointerInput

Cmn 
fun SemanticsNodeInteractionsProvider.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis: IndirectPointerEventPrimaryDirectionalMotionAxis,
    inputDeviceSize: IntSize,
    block: IndirectPointerInjectionScope.() -> Unit
): Unit

Executes an indirect pointer gesture globally, targeting the currently focused Compose UI (from root to the focused node).

This API requires an active focus state meaning developers need to request focus to the component or a child of the component via SemanticsNodeInteraction.requestFocus() before calling this function. If no component is currently focused, this will throw an AssertionError.

If there are multiple Compose roots present, this action will target the first focused root.

Indirect pointer input events are touch events that are from an external touchpad whose coordinates are not tied to the screen coordinates.

These events are dispatched through the focused tree, and components will only receive these events if they are focused, or an ancestor of a focused item.

The gesture doesn't need to be complete and can be resumed in a later invocation of performIndirectPointerInput { ... }. The event time is initialized to the current time of the MainTestClock.

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

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.

Example of performing a swipe:

import androidx.compose.ui.input.indirect.IndirectPointerEventPrimaryDirectionalMotionAxis
import androidx.compose.ui.test.inputDeviceLeft
import androidx.compose.ui.test.inputDeviceRight
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performIndirectPointerInput
import androidx.compose.ui.test.requestFocus
import androidx.compose.ui.test.swipeRight
import androidx.compose.ui.unit.IntSize

// Ensure your node is within the focus path (otherwise, you won't get the event).
composeTestRule.onNodeWithTag("myComponent").requestFocus()
composeTestRule.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis =
        IndirectPointerEventPrimaryDirectionalMotionAxis.X,
    // Horizontal trackpad
    inputDeviceSize = IntSize(width = 5000, height = 1000),
) {
    swipeRight(startX = inputDeviceLeft, endX = inputDeviceRight)
}

Examples of click:

import androidx.compose.ui.input.indirect.IndirectPointerEventPrimaryDirectionalMotionAxis
import androidx.compose.ui.test.click
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performIndirectPointerInput
import androidx.compose.ui.test.requestFocus
import androidx.compose.ui.unit.IntSize

// Ensure the node is within the focus path (otherwise, you won't get the event).
composeTestRule.onNodeWithTag("myComponent").requestFocus()
composeTestRule.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis =
        IndirectPointerEventPrimaryDirectionalMotionAxis.X,
    // Horizontal trackpad
    inputDeviceSize = IntSize(width = 5000, height = 1000),
) {
    click()
}
 
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.input.indirect.IndirectPointerEventPrimaryDirectionalMotionAxis
import androidx.compose.ui.test.inputDeviceCenterX
import androidx.compose.ui.test.inputDeviceCenterY
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performIndirectPointerInput
import androidx.compose.ui.test.requestFocus
import androidx.compose.ui.unit.IntSize

// Ensure the node is within the focus path (otherwise, you won't get the event).
composeTestRule.onNodeWithTag("myComponent").requestFocus()

composeTestRule.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis =
        IndirectPointerEventPrimaryDirectionalMotionAxis.X,
    // Horizontal trackpad
    inputDeviceSize = IntSize(width = 5000, height = 1000),
) {
    down(position = Offset(x = inputDeviceCenterX, y = inputDeviceCenterY))
}

// Assert some pressed state is visible

composeTestRule.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis =
        IndirectPointerEventPrimaryDirectionalMotionAxis.X,
    // Horizontal trackpad
    inputDeviceSize = IntSize(width = 5000, height = 1000),
) {
    up()
}

Example of performing a click-and-drag:

import androidx.compose.ui.input.indirect.IndirectPointerEventPrimaryDirectionalMotionAxis
import androidx.compose.ui.test.click
import androidx.compose.ui.test.inputDeviceLeft
import androidx.compose.ui.test.inputDeviceRight
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performIndirectPointerInput
import androidx.compose.ui.test.requestFocus
import androidx.compose.ui.test.swipeLeft
import androidx.compose.ui.unit.IntSize

// Ensure the node is within the focus path (otherwise, you won't get the event).
composeTestRule.onNodeWithTag("myComponent").requestFocus()
composeTestRule.performIndirectPointerInput(
    indirectPointerEventPrimaryDirectionalMotionAxis =
        IndirectPointerEventPrimaryDirectionalMotionAxis.X,
    // Horizontal trackpad
    inputDeviceSize = IntSize(width = 5000, height = 1000),
) {
    click()
    advanceEventTime(durationMillis = 100)
    swipeLeft(startX = inputDeviceRight, endX = inputDeviceLeft)
}
Parameters
indirectPointerEventPrimaryDirectionalMotionAxis: IndirectPointerEventPrimaryDirectionalMotionAxis

The main movement axis (horizontal or vertical) for single-directional scrolling when using the touchpad inputDeviceSize. For instance, if the primary axis is set to X, a display prioritizes scrolling its content (both horizontal and vertical containers) based on the device's X-axis movement. Note that this input axis may not correspond directly to the resulting scrolling axis on the display (e.g., X-axis movement causing vertical scrolling).
inputDeviceSize: IntSize

The dimensions of the external indirect pointer input device that provide the boundaries for indirect input. If you go outside these dimensions, the tests will throw an exception. Note: This is not related to the screen coordinates.
block: IndirectPointerInjectionScope.() -> Unit

Block of code/events to execute in indirect scope.

SemanticsNodeInteractionsProvider.onAllNodesWithContentDescription

Cmn 
fun SemanticsNodeInteractionsProvider.onAllNodesWithContentDescription(
    label: String,
    substring: Boolean = false,
    ignoreCase: Boolean = false,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteractionCollection

Finds all semantics nodes with the given label as content description.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
label: String

The text to search for.
substring: Boolean = false

If true, allows matches where the label is a substring of the content description.
ignoreCase: Boolean = false

If true, does a case-insensitive search.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.
See also
onAllNodes

for more information.

SemanticsNodeInteractionsProvider.onAllNodesWithTag

Cmn 
fun SemanticsNodeInteractionsProvider.onAllNodesWithTag(
    testTag: String,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteractionCollection

Finds all semantics nodes identified by the given tag.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
testTag: String

The tag to search for. Looks for exact matches only.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.
See also
onAllNodes

for more information.

SemanticsNodeInteractionsProvider.onAllNodesWithText

Cmn 
fun SemanticsNodeInteractionsProvider.onAllNodesWithText(
    text: String,
    substring: Boolean = false,
    ignoreCase: Boolean = false,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteractionCollection

Finds all semantics nodes with the given text.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
text: String

The text to search for.
substring: Boolean = false

If true, allows matches where the label is a substring of the content description.
ignoreCase: Boolean = false

If true, does a case-insensitive search.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.
See also
onAllNodes

for more information.

SemanticsNodeInteractionsProvider.onNodeWithContentDescription

Cmn 
fun SemanticsNodeInteractionsProvider.onNodeWithContentDescription(
    label: String,
    substring: Boolean = false,
    ignoreCase: Boolean = false,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Finds a semantics node with the given content description.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
label: String

The text to search for.
substring: Boolean = false

If true, allows matches where the label is a substring of the content description.
ignoreCase: Boolean = false

If true, does a case-insensitive search.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.
See also
onNode

for more information.

SemanticsNodeInteractionsProvider.onNodeWithTag

Cmn 
fun SemanticsNodeInteractionsProvider.onNodeWithTag(
    testTag: String,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Finds a semantics node identified by the given tag.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
testTag: String

The tag to search for. Looks for an exact match only.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.
See also
onNode

for more information.

SemanticsNodeInteractionsProvider.onNodeWithText

Cmn 
fun SemanticsNodeInteractionsProvider.onNodeWithText(
    text: String,
    substring: Boolean = false,
    ignoreCase: Boolean = false,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Finds a semantics node with the given text.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
text: String

The text to search for.
substring: Boolean = false

If true, allows matches where the label is a substring of the content description.
ignoreCase: Boolean = false

If true, does a case-insensitive search.
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.
See also
onNode

for more information.

SemanticsNodeInteractionsProvider.onRoot

Cmn 
fun SemanticsNodeInteractionsProvider.onRoot(
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Finds the root semantics node of the Compose tree.

Useful for example for screenshot tests of the entire scene.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false

If true, searches the unmerged semantics tree instead of the merged semantics tree.