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 by matcher.
  • For a custom element: the method name declared inside the page object.
  • For a basic element: one of the supported actions.
• findFirst (Optional, default is false) Boolean. If true, returns the first element that matches the filter. If false, returns a list of elements. If the element is marked as nullable, the filter can return null if no match is found.
• matcher (Required) Object. Defines the filter criteria for the data returned by the apply 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 an apply method or an element's getter method. These types are supported:
  • isFalse Matches false values.
  • isTrue Matches true values.
  • notNull Matches values that are not null.
  • stringContains Matches values containing the string passed to the matcher's args array.
  • stringEquals Matches values that equal the string passed to the matcher's args 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"
        }
    ]
}