Google is committed to advancing racial equity for Black communities. See how.

SemanticsNodeInteraction

class SemanticsNodeInteraction
kotlin.Any
   ↳ androidx.ui.test.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.

This is usually obtained from methods like ComposeTestRule.onNode, onNode.

Example usage:

onNodeWithTag("myCheckbox")
   .performClick()
   .assertIsOn()

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

composeTestRule.setMaterialContent {
    // IconButton is a semantically merging composable.  All testTags of its children
    // are merged up into it in the default, "merged" semantics tree.
    IconButton(onClick = {}) {
        MyIcon(Modifier.testTag("icon"))
    }
}

// Assert that MyIcon is at the expected position inside the IconButton.
// Without useUnmergedTree, then the test would check the position of the IconButton (0, 0)
// instead of the position of the Icon (30, 30).
onNodeWithTag("icon", useUnmergedTree = true)
    .assertLeftPosition(30.dp)
    .assertTopPosition(30.dp)

Summary

Public methods
Unit

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

SemanticsNodeInteraction
assertExists(errorMessageOnFail: String? = null)

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

SemanticsNode
fetchSemanticsNode(errorMessageOnFail: String? = null)

Returns the semantics node captured by this object.

Extension functions
From androidx.ui.test
SemanticsNodeInteraction
SemanticsNodeInteraction.assert(matcher: SemanticsMatcher, messagePrefixOnError: () -> String = null)

Asserts that the provided matcher is satisfied for this node.

SemanticsNodeInteraction

Asserts that the current semantics node has a click action.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

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

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Asserts that the current semantics node is displayed on screen.

SemanticsNodeInteraction

Asserts that the current semantics node is enabled.

SemanticsNodeInteraction

Asserts that the current semantics node has hidden property set to true.

SemanticsNodeInteraction

Asserts the semantics node is in a mutually exclusive group.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Asserts that the current semantics node is not enabled.

SemanticsNodeInteraction

Asserts that the current semantics node has hidden property set to false.

SemanticsNodeInteraction

Asserts that the current semantics node is not selected.

SemanticsNodeInteraction

Asserts that the current semantics node is unchecked.

SemanticsNodeInteraction

Asserts that the current semantics node is checked.

SemanticsNodeInteraction

Asserts that the current semantics node is selectable.

SemanticsNodeInteraction

Asserts that the current semantics node is selected.

SemanticsNodeInteraction

Asserts that the current semantics node is toggleable.

SemanticsNodeInteraction

Asserts the node's label equals the given String.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

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

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Asserts the node's text equals the given String.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Asserts the node's value equals the given value.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

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

Bitmap

Captures the underlying semantics node's surface into bitmap.

Dp

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

Bounds

Returns the bounds of the layout of this node.

SemanticsNodeInteractionCollection

Returns all the ancestors of this node.

SemanticsNodeInteraction

Returns exactly one child of this node.

SemanticsNodeInteraction

Returns child of this node at the given index.

SemanticsNodeInteractionCollection

Returns children of this node.

SemanticsNodeInteraction

Returns a parent of this node.

SemanticsNodeInteraction

Returns exactly one sibling of this node.

SemanticsNodeInteractionCollection

Returns all siblings of this node.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Executes the (partial) gesture specified in the given block.

Unit

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

Boolean

Send the specified KeyEvent to the focused component.

SemanticsNodeInteraction

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

Unit

Provides support to call custom semantics actions on this node.

Unit

Provides support to call custom semantics actions on this node.

Unit

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

Unit
SemanticsNodeInteraction.performTextInput(text: String, alreadyHasFocus: Boolean = false)

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

Unit
SemanticsNodeInteraction.performTextReplacement(text: String, alreadyHasFocus: Boolean = false)

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

Unit
SemanticsNodeInteraction.printToLog(tag: String, @IntRange(0) maxDepth: Int = Int.MAX_VALUE)

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

String
SemanticsNodeInteraction.printToString(@IntRange(0) maxDepth: Int = Int.MAX_VALUE)

Prints all the semantics nodes information it holds into string.

Public methods

assertDoesNotExist

fun assertDoesNotExist(): Unit

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.

Exceptions
AssertionError if the assert fails.

assertExists

fun assertExists(errorMessageOnFail: String? = null): SemanticsNodeInteraction

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
errorMessageOnFail: String? = null 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.".
Exceptions
AssertionError if the assert fails.

fetchSemanticsNode

fun fetchSemanticsNode(errorMessageOnFail: String? = null): SemanticsNode

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.

Exceptions
AssertionError if 0 or multiple nodes found.