Printing The Semantics Tree

Printing the Semantics Tree — When a Finder Fails, Dump the Tree

onNodeWithTag failures are structural — the tag is wrong, the matcher is on the merged tree but the tag is on a leaf, or the node is genuinely not composed yet. None of those are timing problems, so Thread.sleep does nothing. This skill teaches the agent to diagnose finder failures by dumping the semantics tree with printToLog / printToString and reading the framework's built-in "found in the unmerged tree" hint.

When to use this skill

• The test fails with "Failed: assertExists. Reason: Expected exactly '1' node but could not find any node that satisfies: …".
• The test fails with "Reason: Expected exactly '1' node but found 'N' nodes that satisfy: …".
• The error message ends with "…were found in the unmerged tree. If you really wanted to match against merged tree, use useUnmergedTree = true." and the developer is confused.
• The developer is writing a custom matcher and needs direct access to a SemanticsNode.
• A test was fixed by adding Thread.sleep — the underlying problem is a wrong tag, not a timing issue. Replace with this skill's pattern. See skydoves directive #7.

When NOT to use this skill

• The symptom is timing (animation has not finished, an idling resource is busy). Use ../../synchronization/synchronizing-with-idle/SKILL.md or ../../synchronization/testing-animations-deterministically/SKILL.md.
• The finder is wrong because the test searches by text instead of by tag. Fix with ../../finders/finding-nodes-by-tag-text-content/SKILL.md (skydoves directive #1).
• The diagnosis involves accessibility violations rather than node lookup. Use ../enabling-accessibility-checks/SKILL.md.

Prerequisites

• androidx.compose.ui:ui-test on androidTestImplementation or testImplementation (the API lives in commonMain so it is available in both source sets).
• An active ComposeTestRule or ComposeUiTest (no extra setup beyond the standard skeleton).

Workflow

• 1. When a finder fails, dump the merged tree first. Add the line right after rule.setContent { … } (or right before the failing finder).

rule.onRoot().printToLog("DEBUG")

The signature is fun SemanticsNodeInteraction.printToLog(tag: String, maxDepth: Int = Int.MAX_VALUE) — full subtree by default for a single-node receiver. Cited at compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/Output.kt:62-69. View the output via adb logcat -s DEBUG.

• 2. If the merged dump does not show the expected node, dump the unmerged tree.

rule.onRoot(useUnmergedTree = true).printToLog("DEBUG")

Inner descendants of merging composables (e.g. an Icon inside a Button) only appear in the unmerged tree.

• 3. Read the output grammar. The format is fixed by Output.kt:135-296:

Node #<id> at (l=<L>, t=<T>, r=<R>, b=<B>)px, Tag: '<tag>'
  <Sorted ConfigKey> = '<value>'
  ...
  [<FlagKey1>, <FlagKey2>]            // keys whose value is Unit
  Actions = [<ActionKey1>, ...]        // AccessibilityActions and Function values
  MergeDescendants = 'true'            // when isMergingSemanticsOfDescendants
  ClearAndSetSemantics = 'true'        // when isClearingSemantics
   |-Node #<childId> at (...)px        // children indented with " |-"

• Top line: Node # + id + bounds + (optionally) Tag: '<testTag>'.

• Config entries are alphabetically sorted by key name.

• AccessibilityAction and Function<*> values are summarized as Actions = [keyName, …].

• Unit values (e.g. Disabled, IsTraversalGroup) are summarized as [Disabled, IsTraversalGroup, …].

• MergeDescendants = 'true' and ClearAndSetSemantics = 'true' flags appear at the bottom of a node's block.

• 4. Read the framework's built-in hint. When onNode(...) finds zero matches in the merged tree but the same matcher would have matched in the unmerged tree, the error message embeds a "These nodes were found in the unmerged tree" block. Cited at compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/SemanticsNodeInteraction.kt:184-194. When the developer sees that, the fix is to flip useUnmergedTree = true on the failing finder. See ../../finders/finding-nodes-by-tag-text-content/SKILL.md for the merged/unmerged decision.

• 5. For custom matchers, use fetchSemanticsNode / fetchSemanticsNodes directly. These return the underlying SemanticsNode(s) for direct introspection.

val node = rule.onNodeWithTag("title").fetchSemanticsNode()
assertThat(node.config[SemanticsProperties.Text]).isNotEmpty()

val all = rule.onAllNodesWithTag("row").fetchSemanticsNodes(
    atLeastOneRootRequired = true,
    errorMessageOnFail = "expected at least one row",
)

Single-node signature: fun fetchSemanticsNode(errorMessageOnFail: String? = null): SemanticsNode. Collection signature: fun fetchSemanticsNodes(atLeastOneRootRequired: Boolean = true, errorMessageOnFail: String? = null): List<SemanticsNode>.

• 6. For collection finders, default maxDepth is 0 (no children). Override when the developer wants the full subtree per match.

rule.onAllNodesWithTag("row").printToLog("DEBUG", maxDepth = Int.MAX_VALUE)

Cited at Output.kt:83-116.

• 7. Capture the dump as a String for assertion-based debugging. Useful in CI logs.

val tree = rule.onRoot(useUnmergedTree = true).printToString()
println(tree) // or attach to a test report