composing-semantics-matchers

Composing Semantics Matchers — One Matcher, One Error

A SemanticsMatcher is a description string plus a (SemanticsNode) -> Boolean predicate (SemanticsMatcher.kt:26). Compose ships with a rich filter library and three combinators (and, or, not) that produce a single matcher whose error message lists every clause. This skill picks the right factory, composes precise predicates, and replaces brittle assertion chains.

When to use this skill

• The developer wants to find "an enabled Button with text Submit" or any node matching multiple constraints.
• The developer asks how to combine hasText and hasClickAction, or how to negate a matcher with not.
• The developer needs to filter by a custom SemanticsPropertyKey (e.g. a domain-specific role) using expectValue/keyIsDefined.
• The developer asks about hierarchical matchers like hasParent, hasAnyAncestor, hasAnyChild, hasAnySibling, hasAnyDescendant.
• A test chains multiple assertIs* calls and the developer wants a single, declarative predicate.

When NOT to use this skill

• The query is "find by tag/text/content description only" — use ../finding-nodes-by-tag-text-content/SKILL.md.
• The right node exists but only as a relative — use ../traversing-the-semantics-tree/SKILL.md.
• The matcher is fine; only the assertions need rework — see ../../assertions/asserting-node-state-and-text/SKILL.md.

Prerequisites

• androidx.compose.ui:ui-test on the test classpath. See ../../setup/configuring-test-dependencies/SKILL.md if unresolved.
• Comfort with Modifier.semantics { … } in production code. Custom keys must be set via Modifier.semantics { customKey = value } to be matchable from tests.

Workflow

• 1. Build matchers from the prebuilt filter library. Every prebuilt matcher lives in commonMain/.../Filters.kt. Group by signal:

  Signal	Matchers	File:line
  Enabled / disabled	isEnabled(), isNotEnabled()	Filters.kt:38-47
  Toggle (Switch, Checkbox)	isToggleable(), isOn(), isOff()	Filters.kt:54-70
  Selection (Tab, RadioButton)	isSelectable(), isSelected(), isNotSelected()	Filters.kt:77-93
  Focus	isFocusable(), isNotFocusable(), isFocused(), isNotFocused()	Filters.kt:100-122
  Click action	hasClickAction(), hasNoClickAction()	Filters.kt:129-136
  Scroll action	hasScrollAction(), hasNoScrollAction(), hasScrollToIndexAction(), hasScrollToKeyAction(), hasScrollToNodeAction()	Filters.kt:143-425
  Text actions (TextField)	hasSetTextAction(), hasInsertTextAtCursorAction(), hasPerformImeAction(), hasImeAction(ImeAction)	Filters.kt:365-392
  Focus action	hasRequestFocusAction()	Filters.kt:399
  Content description	hasContentDescription(value, substring, ignoreCase), hasContentDescriptionExactly(vararg)	Filters.kt:165-212
  Text	hasText(text, substring, ignoreCase), hasTextExactly(vararg, includeEditableText=true)	Filters.kt:229-293
  A11y / state metadata	hasStateDescription, hasProgressBarRangeInfo, isHeading, isDialog, isPopup, isHiddenFromAccessibility, isEditable, isRoot	Filters.kt:301-439
  Test tag	hasTestTag(testTag)	Filters.kt:326-327
  Hierarchical	hasParent(matcher), hasAnyChild(matcher), hasAnySibling(matcher), hasAnyAncestor(matcher), hasAnyDescendant(matcher)	Filters.kt:446-530