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(
    testContext: TestContext,
    useUnmergedTree: Boolean,
    matcher: SemanticsMatcher
)
Cmn
SemanticsNodeInteractionCollection(
    testContext: TestContext,
    useUnmergedTree: Boolean,
    selector: SemanticsSelector
)
Cmn

Public functions

List<SemanticsNode>
fetchSemanticsNodes(
    atLeastOneRootRequired: Boolean,
    errorMessageOnFail: String?
)

Returns the semantics nodes captured by this object.

Cmn
operator SemanticsNodeInteraction
get(index: Int)

Retrieve node at the given index of this collection.

Cmn

Extension functions

SemanticsNodeInteractionCollection

Tries to perform accessibility checks on the current screen.

Cmn
SemanticsNodeInteractionCollection

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

Cmn
SemanticsNodeInteractionCollection

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

Cmn
SemanticsNodeInteractionCollection

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

Cmn
SemanticsNodeInteractionCollection

Executes all of the assertions registered by addGlobalAssertion, each of which will receive the first node of this collection.

Cmn
Unit
SemanticsNodeInteractionCollection.printToLog(
    tag: String,
    maxDepth: Int
)

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

Cmn
String

Prints all the semantics nodes information it holds into string.

Cmn
SemanticsNodeInteractionCollection

Returns all the nodes matching the given matcher.

Cmn
SemanticsNodeInteraction

Expects to return exactly one node matching the given matcher.

Cmn
SemanticsNodeInteraction

Returns the first node in this collection.

Cmn
SemanticsNodeInteraction

Returns the last node in this collection.

Cmn

Public constructors

SemanticsNodeInteractionCollection

SemanticsNodeInteractionCollection(
    testContext: TestContext,
    useUnmergedTree: Boolean,
    matcher: SemanticsMatcher
)

SemanticsNodeInteractionCollection

SemanticsNodeInteractionCollection(
    testContext: TestContext,
    useUnmergedTree: Boolean,
    selector: SemanticsSelector
)

Public functions

fetchSemanticsNodes

fun fetchSemanticsNodes(
    atLeastOneRootRequired: Boolean = true,
    errorMessageOnFail: String? = null
): List<SemanticsNode>

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
atLeastOneRootRequired: Boolean = true

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

errorMessageOnFail: String? = null

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

get

operator fun get(index: Int): SemanticsNodeInteraction

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

tryPerformAccessibilityChecks

fun SemanticsNodeInteractionCollection.tryPerformAccessibilityChecks(): SemanticsNodeInteractionCollection

Tries to perform accessibility checks on the current screen. This will only actually do something if (1) accessibility checks are enabled and (2) accessibility checks are implemented for the platform on which the test runs.

Throws
kotlin.AssertionError

if accessibility problems are found

assertAll

fun SemanticsNodeInteractionCollection.assertAll(
    matcher: SemanticsMatcher
): SemanticsNodeInteractionCollection

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

This passes also for empty collections.

Parameters
matcher: SemanticsMatcher

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.

assertAny

fun SemanticsNodeInteractionCollection.assertAny(
    matcher: SemanticsMatcher
): SemanticsNodeInteractionCollection

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

Parameters
matcher: SemanticsMatcher

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.

assertCountEquals

fun SemanticsNodeInteractionCollection.assertCountEquals(
    expectedSize: Int
): SemanticsNodeInteractionCollection

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

invokeGlobalAssertions

@ExperimentalTestApi
fun SemanticsNodeInteractionCollection.invokeGlobalAssertions(): SemanticsNodeInteractionCollection

Executes all of the assertions registered by addGlobalAssertion, each of which will receive the first node of this collection. This may be useful in a custom test action.

Returns
SemanticsNodeInteractionCollection

the SemanticsNodeInteractionCollection that is the receiver of this method

printToLog

fun SemanticsNodeInteractionCollection.printToLog(
    tag: String,
    maxDepth: Int = 0
): Unit

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
tag: String

The tag to be used in the log messages. Must not be negative.

maxDepth: Int = 0

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

printToString

fun SemanticsNodeInteractionCollection.printToString(maxDepth: Int = 0): String

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
maxDepth: Int = 0

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

fun SemanticsNodeInteractionCollection.filter(matcher: SemanticsMatcher): SemanticsNodeInteractionCollection

Returns all the nodes matching the given matcher.

Parameters
matcher: SemanticsMatcher

Matcher to use for the filtering.

filterToOne

fun SemanticsNodeInteractionCollection.filterToOne(
    matcher: SemanticsMatcher
): SemanticsNodeInteraction

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
matcher: SemanticsMatcher

Matcher to use for the filtering.

fun SemanticsNodeInteractionCollection.onFirst(): SemanticsNodeInteraction

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.

fun SemanticsNodeInteractionCollection.onLast(): SemanticsNodeInteraction

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.