Skip to content

Finding nodes

Selectors locate Compose nodes in the semantics tree. ComposeAutomator provides selectors for test tags, text, content descriptions, and roles.

All selectors are non-waiting

Each findBy…, findOneBy…, hasTag, or hasText call reads the current semantics state once. Use waitForNode(...) when a node may appear later.

By test tag

val nodes: List<AutomatorNode> = automator.findByTestTag("Submit")
val node: AutomatorNode? = automator.findOneByTestTag("Submit")

A test tag gives a test a stable selector when the composable defines Modifier.testTag("..."). Prefer it for elements the test will interact with.

@Composable
fun MyButton() {
    Button(
        onClick = { /* … */ },
        modifier = Modifier.testTag("Submit"),
    ) {
        Text("Submit")
    }
}

By visible text

val nodes = automator.findByText("Submit")            // exact, case-sensitive
val nodes = automator.findByText("Sub", exact = false) // substring, case-insensitive
val node  = automator.findOneByText("Submit")

Use TextQuery when a text match needs explicit options:

import dev.sebastiano.spectre.core.TextQuery

val nodes = automator.findByText(
    TextQuery.exact("Submit", ignoreCase = true)
)

TextQuery supports exact, substring, and case-insensitive matching. Text selectors can fail after copy or translation changes. Add test tags when the UI is under test control.

By content description

val nodes = automator.findByContentDescription("Send message")

This selector reads Modifier.semantics { contentDescription = "..." }. Use it for icon buttons that have no visible text and expose an accessibility description.

By role

import androidx.compose.ui.semantics.Role

val buttons = automator.findByRole(Role.Button)
val checkboxes = automator.findByRole(Role.Checkbox)

Roles come from Modifier.semantics { role = Role.Button } or standard Material and Compose components. A role query can check all buttons in a dialog. Use a test tag when a test needs one specific button.

Presence checks

Use the presence helpers when a test needs a Boolean result, such as a popup state:

import dev.sebastiano.spectre.core.TextQuery

val popupOpen: Boolean = automator.hasTag("popup.body")
val showsSubmit: Boolean = automator.hasText("Submit")
val showsPartial: Boolean = automator.hasText("Sub", exact = false)
val caseInsensitive: Boolean = automator.hasText(TextQuery.exact("submit", ignoreCase = true))

Presence helpers read one snapshot and do not call refreshWindows(). Call refreshWindows() or tree() after a popup window appears or closes. To wait for a popup to close, use waitUntilGone. It refreshes windows before every poll.

Working with the result

AutomatorNode exposes these properties:

Property Meaning
node.testTag The Modifier.testTag value, or null.
node.text First text on the node, or null.
node.texts All text strings on the node.
node.contentDescriptions All content-description strings.
node.contentDescription First content-description string, or null.
node.role The semantics role, or null.
node.isFocused Focused state.
node.isDisabled Disabled state.
node.isSelected Selected state (toggleable/radio).
node.isClickable true when the node has a click action.
node.toggleableState On, Off, or Indeterminate for a checkbox or switch; else null.
node.progressBarRangeInfo Value, range, and steps of a slider or progress bar; else null.
node.editableText Current text-field value.
node.boundsInWindow Layout bounds within the window's Compose surface.
node.boundsOnScreen Bounds in screen coordinates (HiDPI-corrected).
node.boundsInAwtWindow Bounds relative to the hosting AWT window's top-left corner (HiDPI-corrected).
node.centerOnScreen Centre point in screen coordinates — what input helpers click.
node.children Child nodes in the semantics tree.
node.parent Parent node in the semantics tree, or null at a root.

Use boundsOnScreen and centerOnScreen for screenshot regions or custom input.

The three bounds properties use different coordinate spaces:

  • boundsInWindow is a Compose Rect in physical pixels, relative to the Compose content. On a 2× display, a 24.dp offset is 48 here.
  • boundsOnScreen is an AWT Rectangle in logical screen units, the units that java.awt.Robot and Component.getLocationOnScreen() use.
  • boundsInAwtWindow is boundsOnScreen minus the hosting window's locationOnScreen. It is in the same logical units and includes window decorations such as the title bar, so it matches coordinates in that window's Swing hierarchy (for example, SwingUtilities.convertPoint(component, point, surface.window)). The hosting window is AutomatorWindow.window for the node's surface. The HiDpiMapper handles macOS Retina, Windows DPI scaling (100/125/150/200%), and mixed-DPI multi-monitor setups.

Walking the tree by hand

Call automator.tree() when a selector cannot express the query. Inspect the returned tree directly:

val secondWindow = automator.tree(windowIndex = 1)
val matching = secondWindow.allNodes()
    .filter { it.isFocused && it.role == Role.Button }

AutomatorWindow.allNodes() returns every window node in tree order. AutomatorWindow.roots() returns top-level nodes. Traverse node.children to inspect their descendants.

Debugging

Print the tree when a selector returns an unexpected result:

println(automator.printTree())

The output lists windows, nodes, tags, text, and roles. Check whether the expected node has composed and whether its actual semantics match the query.

If printTree() returns an empty string, the composition may have failed before registering a node. Check test JVM stderr for EDT or composition exceptions. Those exceptions may not reach the test method.