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¶
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:
boundsInWindowis a ComposeRectin physical pixels, relative to the Compose content. On a 2× display, a 24.dp offset is 48 here.boundsOnScreenis an AWTRectanglein logical screen units, the units thatjava.awt.RobotandComponent.getLocationOnScreen()use.boundsInAwtWindowisboundsOnScreenminus the hosting window'slocationOnScreen. 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 isAutomatorWindow.windowfor the node's surface. TheHiDpiMapperhandles 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:
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.