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:

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:

A matcher is an object with these properties.

This matcher uses the stringContains matcher type.

"matcher": {
    "type": "stringContains",
    "args": [
        {
            "name": "itemText",
            "type": "string"
        }
    ]
}