Asserting Node State And Text

Asserting Node State and Text — Verify Through the Framework, Not Through fetchSemanticsNode

Once a finder resolves to a SemanticsNodeInteraction, the next step is asserting it. Compose ships a typed assertion for almost every semantic property; the generic assert(matcher) covers the rest. This skill picks the right assertion, distinguishes "exists" from "displayed", and shows when boolean predicates belong inside waitUntil.

When to use this skill

• The developer wants to verify a Switch is on, a Checkbox is unchecked, a Button is enabled, a Text equals an expected string.
• The developer asks about assertIsDisplayed vs assertExists (one verifies on-screen, the other verifies presence in the tree).
• The developer needs a custom assertion via assert(matcher) for a property without a typed extension.
• The developer wants to verify a collection: "exactly 3 items", "at least one is selected", "all are enabled".
• A test compares node.config[...] directly instead of using a typed assertion.

When NOT to use this skill

• The right node cannot be located — see ../../finders/finding-nodes-by-tag-text-content/SKILL.md.
• The assertion is geometric (width, height, position) — see ./asserting-bounds-and-dimensions/SKILL.md.
• The check needs a custom SemanticsMatcher — see ../../finders/composing-semantics-matchers/SKILL.md.
• The state changes asynchronously and the assertion is timing-sensitive — see ../../synchronization/synchronizing-with-idle/SKILL.md.

Prerequisites

• A working ComposeTestRule / ComposeUiTest. See ../../setup/configuring-test-dependencies/SKILL.md.
• The node has been located through onNode* / onAllNodes* / a navigator.
• For assertIsDisplayed semantics, the node must be composed AND placed AND at least partially on-screen post-clip (Assertions.kt:30-39).

Workflow

• 1. Pick by question type. Map the developer's question to one assertion call. Every API listed is in commonMain/.../Assertions.kt unless noted.

  Question	API	File:line
  Is it in the tree?	assertExists(errorMessageOnFail)	SemanticsNodeInteraction.kt:124-127
  Is it gone?	assertDoesNotExist()	SemanticsNodeInteraction.kt:94-110
  Is it a SubcomposeLayout retained child?	assertIsDeactivated()	SemanticsNodeInteraction.kt:137-148
  Is it visible to the user?	assertIsDisplayed() / assertIsNotDisplayed()	Assertions.kt:32-53
  Is it interactive?	assertIsEnabled() / assertIsNotEnabled()	Assertions.kt:60-67
  Is the toggle on?	assertIsOn() / assertIsOff() / assertIsToggleable()	Assertions.kt:74-81, 103
  Is the radio/tab selected?	assertIsSelected() / assertIsNotSelected() / assertIsSelectable()	Assertions.kt:88-110
  Does it have focus?	assertIsFocused() / assertIsNotFocused()	Assertions.kt:117-124
  Does it equal these strings?	assertTextEquals(vararg, includeEditableText=true)	Assertions.kt:181-185
  Does it contain this string?	assertTextContains(value, substring=false, ignoreCase=false)	Assertions.kt:204-208
  Content description equals these?	assertContentDescriptionEquals(vararg)	Assertions.kt:139-141
  Content description contains this?	assertContentDescriptionContains(value, substring, ignoreCase)	Assertions.kt:158-163
  StateDescription equals X?	assertValueEquals(value)	Assertions.kt:216-217
  ProgressBar at this position?	assertRangeInfoEquals(rangeInfo)	Assertions.kt:225-227
  Has a click action?	assertHasClickAction() / assertHasNoClickAction()	Assertions.kt:234-243
  Anything else	assert(matcher, messagePrefixOnError = null)	Assertions.kt:254-267

• 2. assertIsDisplayed vs assertExists — pick deliberately. A node assertExists() if it is in the semantics tree (composed). A node assertIsDisplayed() if it is composed AND placed AND at least partially visible after clipping (Assertions.kt:30-39). For LazyColumn items not yet scrolled into view, assertExists() may fail (item not composed) or succeed (item composed but off-screen — depends on prefetch); assertIsDisplayed() is the right gate for "the user sees this".

• 3. Use the typed assertion, not fetchSemanticsNode().config[...]. Typed assertions delegate to the matcher library and produce framework-formatted errors that name the failed property and dump the node (Assertions.kt:254-267 — the generic assert builds buildGeneralErrorMessage(errorMessageOnFail, selector, node)). Direct config reads bypass that error reporting and miss the auto-attached node dump.

• 4. For collections, use the collection-typed assertions. assertCountEquals(expectedSize) for cardinality (Assertions.kt:276-292), assertAny(matcher) for "at least one matches" (fails on empty — Assertions.kt:300-312), assertAll(matcher) for "every node matches" (passes on empty — Assertions.kt:323-339).

• 5. For waitUntil predicates, use boolean APIs, not throwing assertions. isDisplayed() returns Boolean (Assertions.kt:351) — perfect for rule.waitUntil { node.isDisplayed() }. isNotDisplayed() is its inverse (Assertions.kt:361). Both throw if multiple nodes match the finder, but never on zero. Cross-reference: ../../synchronization/synchronizing-with-idle/SKILL.md.

• 6. For one-off properties without a typed assertion, use assert(matcher). Combine with prebuilt or composed matchers from ../../finders/composing-semantics-matchers/SKILL.md. The messagePrefixOnError lambda is for adding context when this assert is a precondition for a larger operation.

Patterns

Pattern: assertIsDisplayed over assertExists for user-facing checks

// WRONG
@Test
fun submit_isVisibleAfterError() {
    rule.setContent { CheckoutScreen(state = state) }
    rule.onNodeWithTag(SubmitTag).assertExists()
}
// WRONG because: assertExists passes for nodes that are composed but off-screen, behind a
// dialog, or measured to zero size. The test does not prove the user actually sees the button.

// RIGHT
@Test
fun submit_isVisibleAfterError() {
    rule.setContent { CheckoutScreen(state = state) }
    rule.onNodeWithTag(SubmitTag).assertIsDisplayed()
}