---
title: "SemanticsNodeInteraction"
description: "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][SemanticsNodeInteractionsProvider.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:


[useUnmergedTree] is for tests with a special need to inspect implementation detail within
children. For example:"
type: "class"
---

<div class='type'>Class</div>


<a id='references'></a>

<div class='sourceset sourceset-common'>Common</div>


```kotlin
class SemanticsNodeInteraction
constructor(
    internal val testContext: TestContext,
    internal val useUnmergedTree: Boolean,
    internal val selector: SemanticsSelector,
)
```


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:


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


## Secondary Constructors

```kotlin
constructor(
    testContext: TestContext,
    useUnmergedTree: Boolean,
    matcher: SemanticsMatcher,
) : this(testContext, useUnmergedTree, SemanticsSelector(matcher))
```

## Functions

```kotlin
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.


```kotlin
fun 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.


```kotlin
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 | 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.". |



```kotlin
fun assertIsDeactivated(errorMessageOnFail: String? = null)
```


Asserts that the component was found and it is deactivated.

For example, the children of `androidx.compose.ui.layout.SubcomposeLayout` which are retained
to be reused in future are considered deactivated.



## Code Examples

### clickAndVerifyCheckbox
```kotlin
fun clickAndVerifyCheckbox() {
    composeTestRule.onNode(isToggleable()).performClick().assertIsOn()
}
```

### useUnmergedTree
```kotlin
fun useUnmergedTree() {
    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)
}
```