Skip to main content
Version: 7.5.5

Element (Custom Control)

Element (a custom control) gives a user a lot of flexibility because it does not belong to any specific control and can be used to find and interact with any type of Pega controls. It is especially useful for not OOTB elements without specific identifiers (as id or data-test-id). With elements it is possible to use all the power of xpath or css selectors, perform many actions and verify different statuses.

It is possible to find a dropdown element by following attributes:

NameParameter(s)TypeDescription
elementargs{ dataTestId: string, elementType?: string, container?: string }Searches for an element by value of a Pega data-test-id attribute, same as elementByDataTestId. ElementType* and container are optional parameters
elementByDataTestIdargs{ dataTestId: string, elementType?: string, container?: string }Searches for an element by value of a Pega data-test-id attribute, same as element. ElementType* and container are optional parameters
elementByIdidstringSearches for an element by value of an id attribute
elementByCsscssstringSearches for an element by a custom scc selector
elementByXpathxpathstringSearches for an element by a custom xpath selector
elementByAttributesattributeNamestringSearches for an element by an attribute name and value
attributeValuestring

*elementType allows being more precise while defining the element's selector (e.g. if there are several elements with same data-test-id but with different tags (input, label, etc)).

Main action functions

NameParameter(s)TypeDescription
setvaluestring/ numberSets the value. Accepts string or number, it is also possible to select the element by index (in options parameter)
options?{ index?: number, timeout?: number, interval?: number, retries?: number }
pastevaluestring/ numberHas the same functionality as set() but allows pasting text quickly. Attention! In many cases Pega applications "don't see" this pasted value, so if the further action is required, it is better to use set() or to add pressTab() step after paste() one
options?{ index?: number, timeout?: number, interval?: number, retries?: number }
appendValuevaluestring/ numberAppends value to an existing one (without the field being cleared)
options?{ index?: number, timeout?: number, interval?: number, retries?: number }
clearFieldoptions?{ index?: number, timeout?: number, interval?: number, retries?: number }Clears the field value
focusoptions?{ index?: number, timeout?: number, interval?: number, retries?: number }Focuses the element. A focused element is ready to be activated with a keyboard or any keyboard-emulating technology
hoveroptions?{ index?: number, timeout?: number, interval?: number, retries?: number }Hovers over the element. A hovered element is ready to be activated with a mouse or any mouse-emulating technology
pressTabSimulates "press Tab key" action
pressEnterSimulates "press Enter key" action
clickoptions?{ index?: number, timeout?: number, interval?: number, retries?: number }Clicks in the field
checkoptions?{ index?: number, timeout?: number, interval?: number, retries?: number }Clicks in the field ("checks" the value)
uncheckoptions?{ index?: number, timeout?: number, interval?: number, retries?: number }Clicks in the field ("unchecks" the value)

Assertions

NameParameter(s)TypeDescription
shouldBeVisibleoptions?{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element exists and visible
shouldBeVisibleByIndexindexnumberChecks if the element exists and visible by a given index
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldBeVisibleByAttributeattributeNamestringChecks if the element exists and visible by given attributes
attributeValue?string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldExistoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element exists
shouldNotBeVisibleoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element exists but is not visible
shouldNotBeVisibleByIndexindexnumberChecks if the element exists but is not visible by a given index
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotExistoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element does not exist
shouldHaveTextvaluestringChecks if the element's inner text contains a given string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldHaveTextByIndexvaluestringChecks if the element's inner text by a given index contains a given string
indexnumber
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveTextvaluestringChecks if the element's inner text does not contain a given string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveTextByIndexvaluestringChecks if the element's inner text by a given index does not contain a given string
indexnumber
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldHaveExactTextvaluestringChecks if the element's inner text is equal to a given string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldHaveExactTextByIndexvaluestringChecks if the element's inner text by a given index is equal to a given string
indexnumber
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveExactTextvaluestringChecks if the element's inner text is not equal to a given string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveExactTextByIndexvaluestringChecks if the element's inner text by a given index is not equal to a given string
indexnumber
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldHaveValuevaluestringChecks if the element's value contains a given string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldHaveValueByIndexvaluestringChecks if the element's value by a given index contains a given string
indexnumber
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveValuevaluestringChecks if the element's value does not contain a given string
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveValueByIndexvaluestringChecks if the element's value by a given index does not contain a given string
indexnumber
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldBeEnabledoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element doesn't have a disabled attribute
shouldBeDisabledoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element has a disabled attribute
shouldNotBeBlankoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the element's inner text is not equal to an empty string ("")
shouldNotBeBlankByIndexindexnumberChecks if the element's inner text by a given index is not equal to an empty string ("")
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldBeRequiredoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the field is mandatory
shouldNotBeRequiredoptions?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }Checks if the field is not mandatory
shouldHaveValidationTypevalidationTypestringChecks if the element's validation type is equal to a given one
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }
shouldNotHaveValidationTypevalidationTypestringChecks if the element's validation type is not equal to a given one
options?{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number }

Wait for functions

Simple wait for visibility functions

NameParameter(s)TypeDescription
waitUntilVisibilityoptions?{ timeout?: number, interval?: number, retries?: number }Waits for the element to be visible
waitUntilInvisibilityoptions?{ timeout?: number, interval?: number, retries?: number }Waits for the element to be invisible
waitUntilElementExistsoptions?{ timeout?: number, interval?: number, retries?: number }Waits for the element to exist
waitUntilElementNotExistoptions?{ timeout?: number, interval?: number, retries?: number }Waits for the element not to exist

Complex wait for visibility functions

Allow filtering of available elements by index, text, attribute:

NameParameter(s)TypeDescription
waitUntilVisibilityByTexttextstringFilters collection of elements by text and waits for the element to be visible
options?{ timeout?: number, interval?: number, retries?: number }
waitUntilVisibilityByAttributeattributeNamestringFilters collection of elements by attribute and waits for the element to be visible
attributeValuestring
options?{ timeout?: number, interval?: number, retries?: number }
waitUntilVisibilityByIndexindexnumberFilters collection of elements by index and waits for the element to be visible
options?{ timeout?: number, interval?: number, retries?: number }
waitUntilInvisibilityByIndexindexnumberFilters collection of elements by index and waits for the element not to be visible
options?{ timeout?: number, interval?: number, retries?: number }

Wait for a collection size functions

NameParameter(s)TypeDescription
waitUntilCollectionOfElementsSizeIsGreaterOrEqualexpectedSizenumberWaits until collection of elements have specific size (or there are more)
options?{ timeout?: number, interval?: number, retries?: number }
waitUntilCollectionOfElementsSizeIsLessThanexpectedSizenumberWaits until collection of elements have fewer elements than specified
options?{ timeout?: number, interval?: number, retries?: number }

Actionability check

ActionabilityCheckTypes == attached | stable | visible | enabled | editable

NameParameter(s)TypeDescription
waitForSelectActionabilityCheckcheck types[]Waits for the element to pass all the selected actionability check types
isFilterByVisibilityboolean (true by default)

e.g.

await pega.elementById('customElement').waitForSelectActionabilityCheck(['attached', 'visible', 'stable']);

IsVisible and IsExists functions

NameParameter(s)TypeDescription
isVisibleoptions?{ timeout?: number, interval?: number, retries?: number }Returns true if the element exists and is visible
isExistsoptions?{ timeout?: number, interval?: number, retries?: number }Returns true if the element exists

GetValue and GetText functions

NameParameter(s)TypeDescription
getValueReturns element's value as a string
getTextReturns element's inner text as a string