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