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"
        }
    ]
}

Nested elements inside filtered parent

Element with filter can have nested elements.

Element with findFirst set to true (filtered element returns single element)

For example UTAM page object that has "child" element nested inside filtered "parent" that returns single element ("findFirst": true):

{
    "name": "parent",
    "selector": {
        "css": "div",
        "returnAll": true
    },
    "filter": {
        "apply": "isVisible",
        "findFirst": true,
        "matcher": {
            "type": "isTrue"
        }
    },
    "elements": [
        {
            "name": "child",
            "selector": {
                "css": "button"
            },
            "public": true
        }
    ]
}

Generated code:

1. Type definition for JavaScript

getChild(): Promise<_BaseUtamElement>;

2. Java interface

BasicElement getChild();

Element with findFirst is set to false (filtered element returns list, default)

UTAM compiler will add additional index parameter to nested element's gettter. For example UTAM page object that has "listField" element nested inside filtered list "visibleTableCells": true`):

{
    "name": "visibleTableCells",
    "selector": {
        "css": "td",
        "returnAll": true
    },
    "filter": {
        "apply": "isVisible",
        "matcher": {
            "type": "isTrue"
        }
    },
    "elements": [
        {
            "name": "listField",
            "selector": {
                "css": "lst-template-list-field"
            },
            "type": "utam-lst/pageObjects/templateListField",
            "public": true
        }
    ]
}

Generated code:

1. Type definition for JavaScript

/**
* @param _visibleTableCellsIndex index of parent element
*/
getListField(_visibleTableCellsIndex: number): Promise<(_TemplateListField)>;

2. Java interface

/**
* @param _visibleTableCellsIndex index of parent element
*/
TemplateListField getListField(_visibleTableCellsIndex: integer);