Element Filters
To pick an element or a list of elements based on a condition at run time, add a filter inside an element node. An element with a filter
must have a selector
with returnAll
set to true
.
Filter Properties
A filter
object inside an element has these properties:
apply
(Required) String. The method called on the element, which must return a value of the type expected bymatcher
.- For a custom element: the method name declared inside the page object.
- For a basic element: one of the supported actions.
findFirst
(Optional, default isfalse
) Boolean. Iftrue
, returns the first element that matches the filter. Iffalse
, returns a list of elements. If the element is marked asnullable
, the filter can returnnull
if no match is found.matcher
(Required) Object. Defines the filter criteria for the data returned by theapply
method.type
(Required) String. The matcher type for filtering data. For supported types, see Matchers.args
(Optional) Array. If the matcher type requires arguments, pass them in this array.
This example uses a filter to pick one of the lightning-menu-item
instances inside a lightning-button-menu
based on the item text.
{
"elements": [
{
"name": "menuItemByText",
"type": "utam-lightning/pageObjects/lightning/menuItem",
"selector": {
"css": "lightning-menu-item",
"returnAll": true
},
"filter": {
"apply": "getItemText",
"findFirst": true,
"matcher": {
"type": "stringContains",
"args": [
{
"name": "itemText",
"type": "string"
}
]
}
},
"public": true
}
]
}
For the example to work, the lightning-menu-item
page object must declare a public method getItemText
that returns menu item text.
The generated method finds all lightning-menu-item
instances inside a lightning-button-menu
based on the item text. For each item, getItemText
executes and picks the first item that contains the parameter value as a substring. If no match is found, it returns null.
public MenuItem getMenuItemByText(String itemText) {
// find all available menu items
// get text for each item
// pick first item that contains value provided in parameter
}
Example of a basic element filter that returns a list:
{
"elements": [
{
"name": "myElement",
"selector": {
"css": ".myClass",
"returnAll": true
},
"filter": {
"apply": "getText",
"matcher": {
"type": "stringContains",
"args": [
{
"name": "matcherArg",
"type": "string"
}
]
}
},
"public": true
}
]
}
UTAM generates this compiled type:
getMyElement(matcherArg: string): Promise<_ActionableUtamElement[]>;
UTAM generates this compiled JavaScript:
async getMyElement(matcherArg) {
const driver = this.driver;
const root = await this.getRootElement();
let elements = await _utam_get_myElements(driver, root, );
elements = elements.map(function _createUtamElement(element) {
return new _ActionableUtamElement(driver, element);
});
const appliedFilter = await Promise.all(elements.map(el => _utam_filter_myElement(el, matcherArg)));
elements = elements.filter((_, i) => appliedFilter[i]);
return elements;
}
Matchers
Use a matcher to apply a condition at run time:
- To pick an element or a list of elements in an element filter. For an example, see Element Filters.
- To transform the return value of a compose statement. For an example, see Methods.
A matcher is an object with these properties.
type
(Required) String. The matcher type to filter data returned by anapply
method or an element's getter method. These types are supported:isFalse
Matchesfalse
values.isTrue
Matchestrue
values.notNull
Matches values that are not null.stringContains
Matches values containing the string passed to the matcher'sargs
array.stringEquals
Matches values that equal the string passed to the matcher'sargs
array.
args
(Optional) Array. If the matcher type requires arguments, pass them in this array.
This matcher uses the stringContains
matcher type.
"matcher": {
"type": "stringContains",
"args": [
{
"name": "itemText",
"type": "string"
}
]
}