Constructing Java Element Locators
Java App Steps use CSS selectors to form element locators.
These locators are used in different steps to verify elements are in the application UI or to interact with elements in different ways.
# Verify an element exists in the UI
And I see object "cssSelector:button[text = 'Confirm']" in java app
# Click an element
And I click object "cssSelector:popup-menu > menu-item[text = 'Edit']" in java app
Cycle Java App Steps use locators in this format:
"cssSelector:<css selector expression>"
Please note that Cycle only supports a subset of CSS selector syntax, and only supports element types and attributes specific to Java UIs. The full range of CSS selectors that could be used in a web application is not supported.
Constructing CSS selector expressions
Basic CSS selectors
Basic CSS selectors allow you to locate elements by their type and attributes.
# Find an element by its type
element
# Find an element of a specific type by an attribute
element[attribute = 'value']
# Find any element by an attribute
*[attribute = 'value']
# Find an element of a specific type by a partial match of an attribute
element[attribute *= 'value']
Combining selectors
Basic CSS selectors can be combined together to locate elements based on their relationship to other elements. This allows you to find an element that is an immediate child of another element, a sibling of another element, an element immediately following another element, or an element contained somewhere within an ancestor.
# Find an element by its parent
parent_selector > child_selector
# Find an element by an ancestor
ancestor_selector descendant_selector
# Find an element immediately following another element
element_1 + element_2
# Find an element that shares the same parent with another element
element_1 ~ element_2
Pseudo elements
Some components support pseudo element selectors.
Pseudo elements represent UI elements that are only accessible as part of another UI element. For example, you can only locate cells of a table by locating the table and referencing the cells within the context of that table.
Tables, Lists, Tabbed Panes, Combo Boxes commonly make use of pseudo elements.
The wildcard selector *
is not supported in the pseudo element position. A selector like element::*[text = 'Hello']
will not find any elements.
element::pseudo_element
# Some pseudo elements accept parameters, such as choosing a specific item in a list or table
element::pseudo_element(parameters)
Common locator usage
Find an element by its type
Some UI components may occur only once in an application. In those situations, using the element type is enough to uniquely identify the element.
Syntax
element
Examples
And I see object "cssSelector:table" in java app
And I see object "cssSelector:tabbed-pane" in java app
Find an element by its tool tip content
Many UI elements have unique tooltip text which is shown when hovering the mouse over the element. You can locate these elements without knowing the element type or any other element attributes.
Syntax
element[toolTipText = 'expected tooltip text']
Examples
# Use the '*' in place of an element type to match any element type
And I see object "cssSelector:*[toolTipText = 'Enter username']" in java app
# Use the '*=' operator to partial match an attribute value. This will find a button whose toolTipText contains 'user'
And I see object "cssSelector:button[toolTipText *= 'user']" in java app
Find an element by its text content
Some elements, such as buttons, menu items, and text fields, can be found by their visible text.
Syntax
element[text = 'expected text']
Examples
And I see object "cssSelector:button[text = 'Cancel']" in java app
And I see object "cssSelector:*[text *= 'Click']" in java app
Find an element by its parent element
Sometimes it can be difficult to craft a unique locator for an individual element. You can narrow the scope of an element locator by combining it with a parent element locator.
Syntax
parent > child
Examples
# The application has multiple menu items with the text 'Edit', but you specifically want the one in the popup-menu
And I click object "cssSelector:popup-menu > menu-item[text = 'Edit']" in java app
Find an element by an ancestor element
Sometimes it can be difficult to craft a unique locator for an individual element. You can narrow the scope of an element locator by combining it with a ancestor element locator. This is technique is similar to using a parent locator, but this will find elements that may have intermediate parents between the target ancestor and the target element.
Syntax
ancestor descendant
Examples
# The application may have multiple buttons with the text 'Confirm', but you specifically want the one in the 'Enter User Information' Dialog
And I click object "cssSelector:dialog[title='Enter User Information' button[text = 'Confirm']" in java app
Additional Resources
CSS Selector syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors