Version: 9.0.0

Autocompletion field

It is possible to find an autocompletion element by following attributes:

Name	Parameter(s)	Type	Description
`autocompletionField`	`dataTestId`	`string`	Searches for an autocompletion field by value of a Pega `data-test-id` attribute, same as `autocompletionFieldByDataTestId`
	`container?`	`string`
`autocompletionFieldByDataTestId`	`dataTestId`	`string`	Searches for an autocompletion field by value of a Pega `data-test-id` attribute, same as `autocompletionField`
	`container?`	`string`
`autocompletionFieldById`	`id`	`string`	Searches for an autocompletion field by value of an `id` attribute
	`container?`	`string`
`autocompletionFieldByCss`	`css`	`string`	Searches for an autocompletion field by a custom scc selector
`autocompletionFieldByXPath`	`xpath`	`string`	Searches for an autocompletion field by a custom xpath selector
	`container?`	`string`
`autocompletionFieldBy`	`attributeName`	`string`	Searches for an autocompletion field by an attribute name and value
	`attributeValue`	`string`
	`container?`	`string`

Main action functions

In Pega, there are two types of filtered values DOM structure:

After the filtering, results are inside the autocomplete-results class.
After the filtering, results are inside the ooargs or gargs type of attribute.

In the first case, main action functions are:

Name	Parameter(s)	Type	Description
`filter`	`filter`	`string` / `string[]`	Filters the value by the passed string (minus 1 character, if the value length is >=3)
	`options?`	`{ index?: number, timeout?: number, interval?: number, retries?: number }`
`filterCharacterByCharacter`	`filter`	`string`	Filters the value by the passed string with a pause after each character (intervalBetweenCharacters is configurable, default value is 1000 ms)
	`intervalBetweenCharacters?`	`number`
	`options?`	`{ index?: number, timeout?: number, interval?: number, retries?: number }`
`select`	`text`	`string`	Selects the value equal to the passed string (if it is available in filtered results)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`selectByIndex`	`index`	`number`	Selects the value by index
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`filterAndSelect`	`filter`	`string`	Filters values and selects the one equal to the passed string
	`text?`	`string` (value to select; if no value provided, text === filter)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`openList`	`options?`	`{ timeout?: number, interval?: number, retries?: number }`	Opens the list with possible filtering results
`closeList`	`options?`	`{ timeout?: number, interval?: number, retries?: number }`	Closes the list with possible filtering results

In the second case, main action functions are:

Name	Parameter(s)	Type	Description
`filter`	`filter`	`string` / `string[]`	Filters the value by the passed string (minus 1 character, if the value length is >=3)
	`options?`	`{ index?: number, timeout?: number, interval?: number, retries?: number }`
`filterCharacterByCharacter`	`filter`	`string`	Filters the value by the passed string with a pause after each character (intervalBetweenCharacters is configurable, default value is 1000 ms)
	`intervalBetweenCharacters?`	`number`
	`options?`	`{ index?: number, timeout?: number, interval?: number, retries?: number }`
`selectResultFromExternalSource`	`plPropName`	`string` (plPropName attribute value)	Selects the value equal to the passed string (if it is available in filtered results)
	`texts`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`selectResultFromExternalSourceWithRetries`	`plPropName`	`string` (plPropName attribute value)	Selects the value equal to the passed string (if it is available in filtered results) and retries if the value was not selected from the first attempt
	`texts`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`selectResultFromExternalSourceByJsClick`	`plPropName`	`string` (plPropName attribute value)	Selects the value equal to the passed string (if it is available in filtered results) by performing a JavaScript code in the console
	`texts`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`filterAndSelectResultsFromExternalSource`	`plPropName`	`string` (plPropName attribute value)	Filters values and selects the one equal to the passed string
	`filterValue`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`filterAndSelectResultsFromExternalSourceWithRetries`	`plPropName`	`string` (plPropName attribute value)	Filters values and selects the one equal to the passed string and retries if the value was not selected from the first attempt
	`filterValue`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`filterAndSelectResultsFromExternalSourceByJsClick`	`plPropName`	`string` (plPropName attribute value)	Filters and selects the value equal to the passed string (if it is available in filtered results) by performing a JavaScript code in the console
	`filterValue`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`filterAndSelectResultsFromExternalSourceByJsClickWithRetries`	`plPropName`	`string` (plPropName attribute value)	Filters and selects the value equal to the passed string (if it is available in filtered results) by performing a JavaScript code in the console and retries if the value was not selected from the first attempt
	`filterValue`	`string`/`string[]`
	`expectedValueAfterSelection?`	`string` (if no value provided, `expectedValueAfterSelection` === `texts`)
	`options?`	`{ timeout?: number, interval?: number, retries?: number }`
`openList`	`options?`	`{ timeout?: number, interval?: number, retries?: number }`	opens the list with possible filtering results
`closeList`	`options?`	`{ timeout?: number, interval?: number, retries?: number }`	closes the list with possible filtering results

Example of the DOM structure with the second type of autocompletion field structure:

<table class="gridTable " style="width: 630px; table-layout: fixed;" cellspacing="0" cellpadding="0" id="bodyTbl_right" browresize="false" pl_prop="D_BooksList.pxResults" pl_prop_class="KE-TCF-Data-Books" prim_page="pyWorkPage" grid_ref_page="pyWorkPage">
		<tbody>
				<tr class="cellCont"><td title="" class="hiddenCell" pycelltype="static" style="height:0px;width:152px;visibility:hidden;height:1px;"><div class="oflowDiv" style="height:0px;"><div tabindex="0" class="divCont "><span class="wspan"></span><div class="cellIn ">Name</div></div></div></td><td title="" class="hiddenCell" pycelltype="static" style="width: 315px; visibility: hidden; height: 1px;"><div class="oflowDiv" style="height:0px;"><div tabindex="0" class="divCont "><span class="wspan"></span><div class="cellIn ">Author</div></div></div></td> </tr>
				<tr class="oddRow cellCont" data-gargs="[&quot;William Shakespeare&quot;,&quot;1232&quot;,&quot;Hamlet&quot;]" oaargs="KE-TCF-Data-Books','&amp;Name=Hamlet&amp;Author=William Shakespeare" id="$PD_BooksList$ppxResults$l1" pl_index="1"><td title="" style="height:22px;" class="autocompleteAGleft gridCell" tabindex="0"><div class="oflowDiv" style="height:22px;"><div class="divCont"><span class="wspan"></span><div class="cellIn"><span>William Shakespeare</span></div></div></div></td><td title="" headers="a2" style="height:-2px;" class="gridCell"><div class="oflowDivM "><span>Hamlet</span></div></td> </tr>
				<tr class="evenRow cellCont" data-gargs="[&quot;Gustav Flaubert&quot;,&quot;1850&quot;,&quot;Madame Bovary&quot;]" oaargs="KE-TCF-Data-Books','&amp;Name=Madame Bovary&amp;Author=Gustav Flaubert" id="$PD_BooksList$ppxResults$l2" pl_index="2"><td title="" style="height:22px;" class="autocompleteAGleft gridCell"><div class="oflowDiv" style="height:22px;"><div class="divCont"><span class="wspan"></span><div class="cellIn"><span>Gustav Flaubert</span></div></div></div></td><td title="" headers="a2" style="height:-2px;" class="gridCell"><div class="oflowDivM "><span>Madame Bovary</span></div></td> </tr>
				<tr class="oddRow cellCont" data-gargs="[&quot;Gustav Flaubert&quot;,&quot;1850&quot;,&quot;Madame Bovary Second&quot;]" oaargs="KE-TCF-Data-Books','&amp;Name=Madame Bovary Second&amp;Author=Gustav Flaubert" id="$PD_BooksList$ppxResults$l3" pl_index="3"><td title="" style="height:22px;" class="autocompleteAGleft gridCell   "><div class="oflowDiv" style="height:22px;"><div class="divCont"><span class="wspan"></span><div class="cellIn"><span>Gustav Flaubert</span></div></div></div></td><td title="" headers="a2" style="height:-2px;" class=" gridCell "><div class="oflowDivM "><span>Madame Bovary Second</span></div></td> </tr>
				<tr class="evenRow cellCont" data-gargs="[&quot;Marcel Proust&quot;,&quot;1879&quot;,&quot;Search of Lost Time&quot;]" oaargs="KE-TCF-Data-Books','&amp;Name=Search of Lost Time&amp;Author=Marcel Proust" id="$PD_BooksList$ppxResults$l4" pl_index="4"><td title="" style="height:22px;" class="autocompleteAGleft gridCell cellHover"><div class="oflowDiv" style="height:22px;"><div class="divCont"><span class="wspan"></span><div class="cellIn"><span>Marcel Proust</span></div></div></div></td><td title="" headers="a2" style="height:-2px;" class="gridCell cellHover"><div class="oflowDivM "><span>Search of Lost Time</span></div></td> </tr>
		</tbody>
</table>

To select a value of the autocompletion field from the example above, you need to use a pl_prop attribute (full value or partial value), e.g.:

await pega.autocompletionFieldByDataTestId(`202004070615060327134211`)
    .filterAndSelectResultsFromExternalSource('D_BooksList.pxResults', 'Madame Bovary'); 

or

await pega.autocompletionFieldByDataTestId(`202004070615060327134211`)
    .filterAndSelectResultsFromExternalSourceWithRetries('D_BooksList', 'Search of Lost Time'); 

There is an option to check if the selected value of an autocompletion file is equal to the expected one. By default, it is equal to the text set to be used at the selection step, but you can specify a different value if required. In the example below, the value "Madame Bovary" is selected, but the autocompletion field will show an author name, "Gustav Flaubert":

await pega.autocompletionFieldByDataTestId(`202004070615060327134211`)
    .selectResultFromExternalSource('D_BooksList.pxResults', 'Madame Bovary', 'Gustav Flaubert');

If there is a need to be very precise with selection because of many very similar options after filtering, you can pass the list of strings as the value to be selected. In this case, only the option that contains ALL the parts of this list will be used for selection step. If filterAndSelectResultsFromExternalSource function was used, only the first item in the list will be applied for filtering, but all the items should be presented in the selected option:

await pega.autocompletionFieldByDataTestId(`202004070615060327134211`)
    .filterAndSelectResultsFromExternalSource('D_BooksList.pxResults', ['Gustav Flaubert', 'Madame Bovary'], 'Gustav Flaubert');

Get element to select

If you need a Selector of the element you want to select after filtering, use this function:

Name	Parameter(s)	Type	Description
`getElementToSelect`	`plPropName`	`string` (plPropName attribute value)	Returns selector (xpath) of the element in the results list that contains text or texts passed (in a string format)
	`texts`	`string` / `string[]`

Assertions

Specific assertions

Name	Parameter(s)	Type	Description
`assertResultFromExternalSourceIsVisible`	`plPropName`	`string` (plPropName attribute value)	Checks if the the option with a particular string is visible after filtering
	`text`	`string`
	`options?`	`{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`assertResultFromExternalSourceIsNotVisible`	`plPropName`	`string` (plPropName attribute value)	Checks if the the option with a particular string is no visible after filtering
	`text`	`string`
	`options?`	`{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`assertResultWithComponentsIsVisible`	`plPropName`	`string` (plPropName attribute value)	Checks if the the option with particular strings is visible after filtering
	`texts`	`string[]`
	`options?`	`{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`assertResultWithComponentsIsNotVisible`	`plPropName`	`string` (plPropName attribute value)	Checks if the the option with particular strings is not visible after filtering
	`texts`	`string[]`
	`options?`	`{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`shouldHaveSizeOfResultsFromExternalSource`	`plPropName`	`string` (plPropName attribute value)	Checks if the the size of the results collection is equal to a passed number (option 2 of autocomplete results selection)
	`size`	`number`
	`options?`	`{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`shouldHaveSizeOfResultsList`	`size`	`number`	Checks if the the size of the results collection is equal to a passed number (option 1 of autocomplete results selection)
	`options?`	`{ timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`

Common 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 is visible
`shouldExist`	`options?`	`{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`	Checks if the element exists
`shouldNotBeVisible`	`options?`	`{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`	Checks if the element exists but is not visible
`shouldNotExist`	`options?`	`{ index?: number, 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?`	`{ index?: number, 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?`	`{ index?: number, 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?`	`{ index?: number, 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?`	`{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`shouldHaveValue`	`value`	`string`	Checks if the element's value contains a given string
	`options?`	`{ index?: number, 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?`	`{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`
`shouldBeEnabled`	`options?`	`{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`	Checks if the element doesn't have a disabled attribute
`shouldBeDisabled`	`options?`	`{ index?: number, timeout?: number, assertionTimeout?: number, interval?: number, retries?: number, soft?: boolean }`	Checks if the element has a disabled attribute
`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

Allows 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.autocompletionFieldByDataTestId(`202004070615060327134211`)
    .waitForSelectActionabilityCheck(['attached', 'visible', 'stable']);

Other helpers

Name	Parameter(s)	Type	Description
`focus`	`options?`	`{ 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
`pressTab`			Simulates "press Tab key" action
`click`	`options?`	`{ timeout?: number, interval?: number, retries?: number }`	Clicks in the field

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
`isExists`	`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

Main action functions​

Get element to select​

Assertions​

Specific assertions​

Common assertions​

Wait for functions​

Simple wait for visibility functions​

Complex wait for visibility functions​

Wait for a collection size functions​

Actionability check​

Other helpers​

IsVisible and IsExists functions​

GetValue and GetText functions​