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.

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.

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.

Example of a basic element filter that returns a list:

UTAM generates this compiled type:

UTAM generates this compiled JavaScript:

Use a matcher to apply a condition at run time:

  • To pick an element or a list of elements in an element filter.
  • 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.

Element with filter can have nested elements.

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

Generated code:

  1. Type definition for JavaScript
  1. Java interface

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`):

Generated code:

  1. Type definition for JavaScript
  1. Java interface