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

SemanticsNodeInteractionCollection

public final class SemanticsNodeInteractionCollection


Represents a collection of semantics nodes and the path to fetch them from the semantics tree. One can interact with these nodes by performing assertions such as assertCountEquals, or navigate to other nodes such as get.

An instance of SemanticsNodeInteractionCollection can be obtained from onAllNodes and convenience methods that use a specific filter, such as onAllNodesWithText.

For example, here is how you verify that there are exactly two clickable items:

import androidx.compose.ui.test.assertCountEquals
import androidx.compose.ui.test.hasClickAction

composeTestRule.onAllNodes(hasClickAction())
    .assertCountEquals(2)

Summary

Public constructors

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

Public methods

final @NonNull List<@NonNull SemanticsNode>
fetchSemanticsNodes(
    boolean atLeastOneRootRequired,
    String errorMessageOnFail
)

Returns the semantics nodes captured by this object.

final @NonNull SemanticsNodeInteraction
get(int index)

Retrieve node at the given index of this collection.

Extension functions

final @NonNull SemanticsNodeInteractionCollection

Asserts that all the nodes in this collection satisfy the given matcher.

final @NonNull SemanticsNodeInteractionCollection

Asserts that this collection contains at least one element that satisfies the given matcher.

final @NonNull SemanticsNodeInteractionCollection
AssertionsKt.assertCountEquals(
    @NonNull SemanticsNodeInteractionCollection receiver,
    int expectedSize
)

Asserts that this collection of nodes is equal to the given expectedSize.

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

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

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

Prints all the semantics nodes information it holds into string.

final @NonNull SemanticsNodeInteractionCollection

Returns all the nodes matching the given matcher.

final @NonNull SemanticsNodeInteraction

Expects to return exactly one node matching the given matcher.

final @NonNull SemanticsNodeInteraction

Returns the first node in this collection.

final @NonNull SemanticsNodeInteraction

Returns the last node in this collection.

Public constructors

SemanticsNodeInteractionCollection

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

SemanticsNodeInteractionCollection

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

Public methods

fetchSemanticsNodes

public final @NonNull List<@NonNull SemanticsNodefetchSemanticsNodes(
    boolean atLeastOneRootRequired,
    String errorMessageOnFail
)

Returns the semantics nodes 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.

Parameters
boolean atLeastOneRootRequired

Whether to throw an error in case there is no compose content in the current test app.

String errorMessageOnFail

Custom error message to append when this fails to retrieve the nodes.

get

public final @NonNull SemanticsNodeInteraction get(int index)

Retrieve node at the given index of this collection.

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.

Extension functions

AssertionsKt.assertAll

public final @NonNull SemanticsNodeInteractionCollection AssertionsKt.assertAll(
    @NonNull SemanticsNodeInteractionCollection receiver,
    @NonNull SemanticsMatcher matcher
)

Asserts that all the nodes in this collection satisfy the given matcher.

This passes also for empty collections.

Parameters
@NonNull SemanticsMatcher matcher

Matcher that has to be satisfied by all the nodes in the collection.

Throws
kotlin.AssertionError

if the collection contains at least one element that does not satisfy the given matcher.

AssertionsKt.assertAny

public final @NonNull SemanticsNodeInteractionCollection AssertionsKt.assertAny(
    @NonNull SemanticsNodeInteractionCollection receiver,
    @NonNull SemanticsMatcher matcher
)

Asserts that this collection contains at least one element that satisfies the given matcher.

Parameters
@NonNull SemanticsMatcher matcher

Matcher that has to be satisfied by at least one of the nodes in the collection.

Throws
kotlin.AssertionError

if not at least one matching node was node.

AssertionsKt.assertCountEquals

public final @NonNull SemanticsNodeInteractionCollection AssertionsKt.assertCountEquals(
    @NonNull SemanticsNodeInteractionCollection receiver,
    int expectedSize
)

Asserts that this collection of nodes is equal to the given expectedSize.

Provides a detailed error message on failure.

Throws
kotlin.AssertionError

if the size is not equal to expectedSize

OutputKt.printToLog

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

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

By default this does not print nodes sub-hierarchies. 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. Must not be negative.

int maxDepth

Max depth of the nodes in hierarchy to print. Zero will print nodes in this collection only.

OutputKt.printToString

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

Prints all the semantics nodes information it holds into string.

By default this does not print nodes sub-hierarchies. 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 nodes in this collection only. Must not be negative.

SelectorsKt.filter

public final @NonNull SemanticsNodeInteractionCollection SelectorsKt.filter(
    @NonNull SemanticsNodeInteractionCollection receiver,
    @NonNull SemanticsMatcher matcher
)

Returns all the nodes matching the given matcher.

Parameters
@NonNull SemanticsMatcher matcher

Matcher to use for the filtering.

SelectorsKt.filterToOne

public final @NonNull SemanticsNodeInteraction SelectorsKt.filterToOne(
    @NonNull SemanticsNodeInteractionCollection receiver,
    @NonNull SemanticsMatcher matcher
)

Expects to return exactly one node matching the given matcher.

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

Parameters
@NonNull SemanticsMatcher matcher

Matcher to use for the filtering.

SelectorsKt.onFirst

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

Returns the first node in this collection.

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

SelectorsKt.onLast

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

Returns the last node in this collection.

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