Reading the Compose Semantics Tree for Better Tests

By Michael Samuel Naeem · September 11, 2024 · 5 min read

Every Compose UI test you write runs against the semantics tree — a parallel, structured description of your screen that Compose maintains specifically for accessibility services and test tooling. It's not the render tree of boxes and pixels; it's the meaning: this node has text "Sign in," this one is a button, this one is toggled on. Once you understand that your tests and your accessibility are reading the same tree, two things click into place: why some finders fail mysteriously, and why writing testable Compose and writing accessible Compose are the same job.

I've onboarded engineers who fought the test framework for days because they were thinking in terms of composables rather than semantics nodes. Here's the mental model that fixes that.

The tree is meaning, not layout

When Compose renders, it also builds a semantics tree where each relevant node carries properties: text, contentDescription, role, stateDescription, onClick, and so on. TalkBack reads this tree to describe your app to a user who can't see it. The test framework reads the same tree to find and assert on elements. So onNodeWithText("Submit") isn't scanning pixels for the word "Submit" — it's querying the semantics tree for a node whose text property equals "Submit."

The immediate consequence: if an element has no semantics, your test can't find it and a screen reader can't announce it. A test that's hard to write is usually flagging a real accessibility gap.

Print the tree when a finder fails

The first thing I do when a test can't find a node is dump the tree. This turns guesswork into reading:

composeTestRule.onRoot().printToLog("SEMANTICS")

That logs the whole tree with every node's properties. Nine times out of ten the fix is obvious once you see it: the text is on a child that got merged away, the node has a contentDescription you forgot about, or the element genuinely has no semantics and needs a testTag. Reach for printToLog before you start adding tags speculatively.

Merged vs unmerged: the finder gotcha

Compose merges semantics by default so accessibility announces a coherent unit. A Button with an icon and a text label becomes one node reading "icon, Add to cart" — not three separate nodes — because that's what a screen reader user wants. This merged tree is what finders search by default.

The gotcha: sometimes you need to target a child that was merged into its parent. A finder for the child's text fails because, in the merged tree, that text belongs to the parent node. The fix is useUnmergedTree:

// Fails: the label was merged into the Button node
composeTestRule.onNodeWithText("Add to cart").assertExists()

// Works: search the unmerged tree for the specific Text child
composeTestRule
    .onNodeWithText("Add to cart", useUnmergedTree = true)
    .assertExists()

Understanding this one distinction resolves a huge fraction of "the element is clearly on screen but the test says it doesn't exist" confusion.

Match on user-visible properties first

The most robust tests assert on what a user perceives: visible text, content descriptions, roles, states. This is deliberate — it means the test breaks when the experience breaks, not when an implementation detail changes.

composeTestRule.onNodeWithText("Sign in").performClick()
composeTestRule.onNodeWithContentDescription("Profile photo").assertIsDisplayed()
composeTestRule.onNode(hasText("Loading") and hasRole(Role.Button)).assertDoesNotExist()

Matchers compose with and, or, and negation, and there are semantic assertions like assertIsEnabled, assertIsToggleable, assertIsSelected. Prefer these over positional or tag-based lookups because they double as accessibility assertions — a passing test is evidence the element is also reachable by TalkBack.

testTag: the escape hatch, used deliberately

Sometimes there's no stable, unique, user-visible handle: a decorative container, a list of items sharing the same label, text that's localized and would make an English-string matcher brittle. That's when testTag earns its place.

// In the composable
Box(Modifier.testTag("checkout_summary")) { /* ... */ }

// In the test
composeTestRule.onNodeWithTag("checkout_summary").assertIsDisplayed()

testTag adds a semantics property that never renders and never affects accessibility, so it's a safe, stable handle. My rule: reach for text/description/role first because they validate the real experience, and fall back to testTag only when matching on meaning is genuinely brittle or ambiguous. A codebase drowning in testTags is often one that skipped proper semantics — and shipped inaccessible UI as a result.

Custom semantics for custom components

When you build a component out of low-level primitives — a custom slider, a canvas-drawn rating — the framework can't infer its meaning, so you attach semantics yourself with Modifier.semantics:

Modifier.semantics {
    role = Role.Button
    stateDescription = if (on) "On" else "Off"
    contentDescription = "Notifications toggle"
}

Now both TalkBack announces it correctly and your test can assert assertIsOn() / match on stateDescription. Use mergeDescendants = true in the semantics block when you want a composite to present as a single node. This is the same discipline that keeps custom pointerInput gestures usable — a custom interaction needs custom semantics or it's invisible to both tests and assistive tech.

A quick reference

Synchronization, briefly

Compose tests auto-synchronize with the compose clock, so most of the time you don't manually wait. The exception is work driven off the compose idle signal — network calls, custom coroutine sources. When a finder runs before your state settles, use waitUntil { } with a semantics condition rather than sleeping:

composeTestRule.waitUntil(timeoutMillis = 5_000) {
    composeTestRule.onAllNodesWithTag("row").fetchSemanticsNodes().size == expected
}

This polls the semantics tree until the condition holds, which is deterministic where a fixed Thread.sleep is flaky.

What I'd take away

Compose testing is semantics-tree querying, and the same tree powers accessibility, so treat the two as one skill. When a finder fails, printToLog the tree before guessing. Learn the merged/unmerged distinction — it explains most "can't find a visible element" mysteries — and reach for useUnmergedTree to target merged children. Prefer matching on text, content description, role, and state so your tests validate the real experience, and fall back to testTag only when meaning-based matching is truly ambiguous. Add explicit semantics to custom components so they're visible to both tests and screen readers. Write tests this way and you get accessible apps almost for free.

Resources

• Test your Compose layout (Android developers)
• Compose semantics
• Testing cheat sheet
• Accessibility in Compose