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:

Name	Parameter(s)	Type	Description
element	args	{ 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
elementByDataTestId	args	{ 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
elementById	args	{id: string, elementType?: string, container?: string }	Searches for an element by value of an id attribute
elementByCss	css	string	Searches for an element by a custom scc selector
elementByXPath	xpath	string	Searches for an element by a custom xpath selector
	container?	string
elementByAttributes	args	{ attributeName: string, attributeValue: string, elementType?: string, container?: string }	Searches for an element by an attribute name and value

*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

Name	Parameter(s)	Type	Description
set	value	string/ number	Sets 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 }
paste	value	string/ number	Has 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 }
appendValue	value	string/ number	Appends value to an existing one (without the field being cleared)
	options?	{ index?: number, timeout?: number, interval?: number, retries?: number }
clearField	options?	{ index?: number, timeout?: number, interval?: number, retries?: number }	Clears the field value
focus	options?	{ 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
hover	options?	{ 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
pressTab			Simulates "press Tab key" action
pressEnter			Simulates "press Enter key" action
click	options?	{ index?: number, timeout?: number, interval?: number, retries?: number }	Clicks in the field
check	options?	{ index?: number, timeout?: number, interval?: number, retries?: number }	Clicks in the field ("checks" the value)
uncheck	options?	{ index?: number, timeout?: number, interval?: number, retries?: number }	Clicks in the field ("unchecks" the value)

Assertions

Name	Parameter(s)	Type	Description
shouldBeVisible	options?	{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element exists and visible
shouldBeVisibleByIndex	index	number	Checks if the element exists and visible by a given index
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldBeVisibleByAttribute	attributeName	string	Checks if the element exists and visible by given attributes
	attributeValue?	string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldExist	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element exists
shouldNotBeVisible	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element exists but is not visible
shouldNotBeVisibleByIndex	index	number	Checks if the element exists but is not visible by a given index
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotExist	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element does not exist
shouldHaveText	value	string	Checks if the element's inner text contains a given string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldHaveTextByIndex	value	string	Checks if the element's inner text by a given index contains a given string
	index	number
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveText	value	string	Checks if the element's inner text does not contain a given string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveTextByIndex	value	string	Checks if the element's inner text by a given index does not contain a given string
	index	number
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldHaveExactText	value	string	Checks if the element's inner text is equal to a given string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldHaveExactTextByIndex	value	string	Checks if the element's inner text by a given index is equal to a given string
	index	number
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveExactText	value	string	Checks if the element's inner text is not equal to a given string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveExactTextByIndex	value	string	Checks if the element's inner text by a given index is not equal to a given string
	index	number
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldHaveValue	value	string	Checks if the element's value contains a given string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldHaveValueByIndex	value	string	Checks if the element's value by a given index contains a given string
	index	number
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveValue	value	string	Checks if the element's value does not contain a given string
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveValueByIndex	value	string	Checks if the element's value by a given index does not contain a given string
	index	number
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldBeEnabled	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element doesn't have a disabled attribute
shouldBeDisabled	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element has a disabled attribute
shouldNotBeBlank	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the element's inner text is not equal to an empty string ("")
shouldNotBeBlankByIndex	index	number	Checks 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, soft?: boolean }
shouldBeRequired	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the field is mandatory
shouldNotBeRequired	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }	Checks if the field is not mandatory
shouldHaveValidationType	validationType	string	Checks if the element's validation type is equal to a given one
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }
shouldNotHaveValidationType	validationType	string	Checks if the element's validation type is not equal to a given one
	options?	{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }

Wait for functions

Simple wait for visibility functions

Name	Parameter(s)	Type	Description
waitUntilVisibility	options?	{ timeout?: number, interval?: number, retries?: number }	Waits for the element to be visible
waitUntilInvisibility	options?	{ timeout?: number, interval?: number, retries?: number }	Waits for the element to be invisible
waitUntilElementExists	options?	{ timeout?: number, interval?: number, retries?: number }	Waits for the element to exist
waitUntilElementNotExist	options?	{ 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:

Name	Parameter(s)	Type	Description
waitUntilVisibilityByText	text	string	Filters collection of elements by text and waits for the element to be visible
	options?	{ timeout?: number, interval?: number, retries?: number }
waitUntilVisibilityByAttribute	attributeName	string	Filters collection of elements by attribute and waits for the element to be visible
	attributeValue	string
	options?	{ timeout?: number, interval?: number, retries?: number }
waitUntilVisibilityByIndex	index	number	Filters collection of elements by index and waits for the element to be visible
	options?	{ timeout?: number, interval?: number, retries?: number }
waitUntilInvisibilityByIndex	index	number	Filters 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

Name	Parameter(s)	Type	Description
waitUntilCollectionOfElementsSizeIsGreaterOrEqual	expectedSize	number	Waits until collection of elements have specific size (or there are more)
	options?	{ timeout?: number, interval?: number, retries?: number }
waitUntilCollectionOfElementsSizeIsLessThan	expectedSize	number	Waits until collection of elements have fewer elements than specified
	options?	{ timeout?: number, interval?: number, retries?: number }

Actionability check

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

Name	Parameter(s)	Type	Description
waitForSelectActionabilityCheck	check types	[]	Waits for the element to pass all the selected actionability check types
	isFilterByVisibility	boolean (true by default)

e.g.

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

IsVisible and IsExists functions

Name	Parameter(s)	Type	Description
isVisible	options?	{ timeout?: number, interval?: number, retries?: number }	Returns true if the element exists and is visible
isExist	options?	{ timeout?: number, interval?: number, retries?: number }	Returns true if the element exists

GetValue and GetText functions

Name	Parameter(s)	Type	Description
getValue			Returns element's value as a string
getText			Returns element's inner text as a string