Traversing The Semantics Tree

Traversing the Semantics Tree — When a Single Finder Won't Reach the Node

The single-finder shortcuts (onNodeWithTag, etc.) cover ~95% of test queries. The remainder need tree navigation: "the parent of this Text", "the third child of this Row", "any sibling that is enabled". This skill maps those navigation operators, calls out the LazyColumn snapshot caveat, and shows when traversal is the wrong tool.

When to use this skill

• The target node has no stable testTag and one cannot be added to production (third-party composable, dynamically generated children).
• The test verifies structural relationships ("the second child of the row is the icon").
• The developer chains .onChildren()[i].onChildAt(j) and wants to know whether that is the right shape.
• The developer mentions onChildren, onChild, onParent, onSibling, onSiblings, onAncestors, filterToOne, onFirst, onLast, or [index].
• A LazyColumn test misses items because they are off-screen.

When NOT to use this skill

• A Modifier.testTag(...) could be added to the target node — adding a tag is almost always cleaner than a traversal chain. See ../finding-nodes-by-tag-text-content/SKILL.md.
• The relationship is "anywhere above" / "anywhere below" — prefer the matcher-based hasAnyAncestor / hasAnyDescendant (see ../composing-semantics-matchers/SKILL.md).
• The query is about a LazyColumn item by key — use performScrollToKey instead (see ../../actions/clicking-and-scrolling/SKILL.md, ../../patterns/testing-lazy-lists/SKILL.md).

Prerequisites

• A working ComposeTestRule / ComposeUiTest. See ../../setup/configuring-test-dependencies/SKILL.md.
• Familiarity with the merged vs unmerged tree distinction. See ../finding-nodes-by-tag-text-content/SKILL.md.

Workflow

• 1. Pick the navigator by relationship type. Each operator returns either a SemanticsNodeInteraction (single — fails on 0 or >1) or a SemanticsNodeInteractionCollection (plural — never fails on 0).

  From a single node, go to …	API	Returns	File:line
  parent	onParent()	single	Selectors.kt:36-42
  exactly one child	onChild()	single	Selectors.kt:71-77
  child at an index	onChildAt(index)	single	Selectors.kt:85
  all currently-composed children	onChildren()	collection	Selectors.kt:53-59
  exactly one sibling	onSibling()	single	Selectors.kt:119-125
  all siblings	onSiblings()	collection	Selectors.kt:101-107
  every ancestor up to root	onAncestors()	collection	Selectors.kt:140-146

  From a collection, narrow to …	API	Returns	File:line
  first	onFirst() (= [0])	single	Selectors.kt:156-158
  last	onLast()	single	Selectors.kt:168-170
  nth	[index]	single	SemanticsNodeInteraction.kt:261-267
  filter to a sub-collection	filter(matcher)	collection	Selectors.kt:178-186
  filter to exactly one	filterToOne(matcher)	single	Selectors.kt:198-206

• 2. Do not look for onAncestor (singular) — it does not exist. The API surface ships only onAncestors() plural (Selectors.kt:140-146). It returns [parent, grandparent, …, root] in that order. To assert "the immediate parent satisfies X", use onParent().assert(matcherX) or the hasParent(matcherX) predicate.

• 3. Remember the useUnmergedTree flag is sticky. Every navigator carries the same useUnmergedTree value as the source SemanticsNodeInteraction (SemanticsNodeInteraction.kt:42-49; each Selectors.kt constructor passes useUnmergedTree through unchanged). A finder created with onNodeWithTag(tag, useUnmergedTree = true) keeps the flag on across onChild/onParent/filter. Skydoves hot take #2: default merged, flip to unmerged only when targeting composition detail.

• 4. onChildren() is a snapshot at invocation time. It returns nodes "currently present in the semantic tree" (Selectors.kt:46-52). For a LazyColumn or LazyRow only the on-screen items appear. To reach an off-screen item, scroll first with performScrollToIndex / performScrollToKey / performScrollToNode (see ../../actions/clicking-and-scrolling/SKILL.md).

• 5. Re-finding by tag usually beats navigating. If the tree shape might change between Compose versions or under translation rotation, a stable tag on the target node is more durable than a [2].onChildAt(0) chain. Add the tag in production. Skydoves hot take #1.

• 6. Use filterToOne(matcher) when the count assertion is implicit. filterToOne throws on 0 or >1 matches at fetch time, the same way onNode(matcher) does (Selectors.kt:198-206). It is the collection-narrowing analogue of onNode(matcher).

Patterns

Pattern: prefer a tag over a deep [index] chain

// WRONG
@Test
fun second_avatar_isVisible() {
    rule.setContent { ProfileGrid(profiles = profiles) }
    rule.onNodeWithTag("ProfileGrid")
        .onChildren()[2]
        .onChildren()[0]
        .assertIsDisplayed()
}
// WRONG because: layout shuffling (a header inserted, an extra wrapper, a Spacer added)
// silently changes which node is being asserted. The test passes for the wrong reason.

// RIGHT
// production:
@Composable
fun ProfileGrid(profiles: List<Profile>) {
    LazyColumn(modifier = Modifier.testTag(ProfileGridTag)) {
        itemsIndexed(profiles) { index, profile ->
            Row(modifier = Modifier.testTag("$AvatarTagPrefix$index")) {
                Avatar(profile, modifier = Modifier.testTag("$AvatarImageTagPrefix$index"))
            }
        }
    }
}

// test:
rule.onNodeWithTag("$AvatarImageTagPrefix${1}").assertIsDisplayed()