PageElement serves as the main building block for all page objects.
Modern websites are usually built with reusable components (eg. in React or Angular) which provide a consistent structure of the component's HTML elements and their behavior.
The goal of PageElements is to also benefit from these advantages by recreating website components as testing components. To do so, PageElement maps the structure of a website's components and provides an api to interact with them.
A big pitfall of scripted browser testing is that a website and its building blocks need to be loaded and rendered before they can be interacted with and all of this takes time. Therefore, browser based tests constantly need to wait for elements of a page to be loaded and rendered or for certain conditions to be met.
PageElements try to overcome these hurdles be performing an "initial waiting condition" before interacting with elements on the page. The supported initial wait conditions include:
Functions/actions defined on the PageElement class that interact with an element on the page or that retrieve or check an element's state automatically wait for this initial wait condition to become true before proceeding with any other functionality.
PageElement furthermore provides three apis to:
.currently: retrieve or check the current state.wait: wait for a certain state.eventually: check if a certain state is eventually reached within a specific timeout.the XPath selector used to identify PageElement on the page
_$ provides access to the PageNode retrieval functions of PageElementBase's PageNodeStore and prefixes the
selectors of all PageNodes retrieved via _$ with the selector of PageElementBase.
stores the default custom scrolling behaviour
the default interval used by PageElement for all of its functions that operate with intervals
(eg. wait and eventually)
Stores the last differences of PageNode's check state functions.
Intended for framework-internal usage only.
the XPath selector of PageNode
an instance of PageNodeStore which can be used to retrieve/create PageNodes
the default timeout used by PageElement for all of its functions that operate with timeouts
(eg. wait and eventually)
Defines the kind of wait condition performed when initialWait is invoked.
The initial wait condition is performed every time before an interaction with the tested application takes place via a PageElement's action (eg. click).
$ provides access to the PageNode retrieval functions of PageElementBase's PageNodeStore and prefixes the
selectors of all PageNodes retrieved via $ with the selector of PageElementBase.
Fetches the first webdriverio element from the HTML page that is identified by PageElement's XPath selector without performing PageElement's initial waiting condition.
Fetches the first webdriverio element from the HTML page that is identified by PageElement's XPath selector after performing PageElement's initial waiting condition.
Returns true if actual has any value.
By default, the comparison is only implemented for the types string, number and boolean.
If actual is of type number or boolean, this function always returns true
unless the value of actual is undefined or null.
If the implementation is missing for the type of actual, an error will be thrown.
an actual value retrieved from the page's state
Returns true if actual contains expected. Both actual and expected are supposed to be
of the same type.
By default, the comparison is only implemented for the type string.
If the implementation is missing for the type of actual and expected, an error will be thrown.
an actual value retrieved from the page's state
an expected value
Returns true if actual equals expected. Both actual and expected are supposed to be
of the same type.
By default, the comparison is only implemented for the types string, number, boolean
undefined and null.
If the implementation is missing for the type of actual and expected, an error will be thrown.
an actual value retrieved from the page's state
an expected value
Provides custom error handling of 'could not be located' and 'WaitUntilTimeoutError' errors for functions that check if a condition returns true within a specific timeout.
the function which is supposed to return true within a specific timeout
Executes func and trows any errors that occur during its execution.
If an error occurs because an element could not be located on the page, throws a custom 'could not be located' error message.
the function to be executed
the result value of the executed function
Converts value to the type string.
This function is used to write a value of an arbitrary type into error messages and log outputs.
By default, the comparison is only implemented for the types string, number, boolean,
undefined and for the value null.
If the implementation is missing for the type of value, an error will be thrown.
the value whose type should be converted
Provides custom error handling of 'could not be located' and 'WaitUntilTimeoutError' errors for functions that wait for a condition to become true within a specific timeout and throw an error if the condition does not become true.
the function which is supposed to return true within a specific timeout and throws an error if the condition does not become true
an errorMessage that describes the condition which did not become true within a specific timeout
the timeout used to wait for the result of the passed func to return true
this (an instance of PageNode)
This function executes a waitFunc until it returns true or a specific timeout is reached. If the return value of waitFunc does not become true within the timeout, this function throws a 'WaitUntilTimeoutError'.
__waitUntil also provides custom error handling for 'could not be located' errors.
the function which is supposed to return true within a specific timeout
a function that returns an errorMessage which describes the condition that did not become true within a specific timeout
the timeout used to wait for the result of the waitFunc to return true
the interval used to check for the result of the waitFunc to return true
this (an instance of PageNode)
Executes func after initial wait and, if an error occurs during execution of func, throws a custom error message that the page element could not be located on the page.
the function to be executed after performing the initial wait condition
This function implements custom error handling for 'could not be located' and 'WaitUntilTimeoutError' errors.
an arbitrary type of error
used to describe the failed condition check which caused a WaitUntilTimeoutError
the timeout used to wait for an element to be located or for a wait condition to return true
Scrolls PageElement into view if PageElement resides in a scrollable container.
Does not perform the initial waiting condition.
configures the scrolling behavior
this (an instance of PageElement)
Clicks on PageElement after performing PageElement's initial waiting condition.
Before clicking on PageElement, it is scrolled into the viewport.
If the clicked HTML element is obscured by another HTML element, the click will be repeated until the clicked HTML element is no longer obscured and can therefore receive the click or until a specific timeout is reached.
If a postCondition is defined in click's options, the click will be repeated until the postCondition function
returns true or until a specific timeout is reached.
includes options used to configure the behavior of the click function:
If no timeout is specified, PageElement's default timeout is used.
If no interval is specified, PageElement's default interval is used.
this (an instance of PageElement)
Returns PageElement's HTML attribute with the passed attribute name after performing the initial waiting condition.
the name of the HTML attribute whose value should be returned
Returns the value of PageElement's 'class' HTML attribute after performing the initial waiting condition.
Returns a PageElement's 'containsDirectText' status after performing the initial waiting condition.
A PageElement's 'containsDirectText' status is set to true if its actual direct text contains the expected direct text.
A direct text is a text that resides on the level directly below the selected HTML element. It does not include any text of the HTML element's nested children HTML elements.
the expected direct text used in the comparison which sets the 'containsDirectText' status
Returns a PageElement's 'containsText' status after performing the initial waiting condition.
A PageElement's 'containsText' status is set to true if its actual text contains the expected text.
the expected text used in the comparison which sets the 'containsText' status
Returns PageElement's direct text after performing the initial waiting condition.
A direct text is a text that resides on the level directly below the selected HTML element. It does not include any text of the HTML element's nested children HTML elements.
Returns PageElement's HTML after performing the initial waiting condition.
Returns a PageElement's 'hasAnyDirectText' status after performing the initial waiting condition.
A PageElement's 'hasAnyDirectText' status is set to true if it has any direct text.
Returns a PageElement's 'hasAnyText' status after performing the initial waiting condition.
A PageElement's 'hasAnyText' status is set to true if it has any text.
Returns a PageElement's 'hasDirectText' status after performing the initial waiting condition.
A PageElement's 'hasDirectText' status is set to true if its actual direct text equals the expected direct text.
A direct text is a text that resides on the level directly below the selected HTML element. It does not include any text of the HTML element's nested children HTML elements.
the expected direct text used in the comparison which sets the 'hasDirectText' status
Returns a PageElement's 'hasText' status after performing the initial waiting condition.
A PageElement's 'hasText' status is set to true if its actual text equals the expected text.
the expected text used in the comparison which sets the 'hasText' status
Returns the height of PageElement in pixels after performing the initial waiting condition.
Returns the value of PageElement's 'id' HTML attribute after performing the initial waiting condition.
Returns the default interval that a PageElement uses if no other explicit interval is passed to one of its functions which operates with intervals (eg. wait, eventually)
Returns true if the PageElement is enabled after performing the initial waiting condition.
Returns the location of PageElement in pixels after performing the initial waiting condition.
Returns the value of PageElement's 'name' HTML attribute after performing the initial waiting condition.
Returns the XPath selector of PageElementBase.
Returns the size of PageElement in pixels after performing the initial waiting condition.
Returns PageElement's text after performing the initial waiting condition.
Returns the default timeout that a PageElement uses if no other explicit timeout is passed to one of its functions which operates with timeouts (eg. wait, eventually)
Returns the width of PageElement in pixels after performing the initial waiting condition.
Returns the X-location of PageElement in pixels after performing the initial waiting condition.
Returns the Y-location of PageElement in pixels after performing the initial waiting condition.
This function performs PageElement's initial waiting condition.
It supports the following waiting types:
this (an instance of PageElement)
Scrolls PageElement into view if PageElement resides in a scrollable container after performing the initial waiting condition.
configures the scrolling behavior
this (an instance of PageElement)
Generated using TypeDoc
PageElement is the main building block for all page objects.
Modern websites are usually built with reusable components (eg. in React or Angular) which provide a consistent structure of the component's HTML elements and their behavior.
The goal of PageElements is to also benefit from these advantages by recreating website components as testing components. To do so, PageElement maps the structure of a website's components and provides an api to interact with them.
A big pitfall of scripted browser testing is that a website and its building blocks need to be loaded and rendered before they can be interacted with and all of this takes time. Therefore, browser based tests constantly need to wait for elements of a page to be loaded and rendered or for certain conditions to be met.
PageElements try to overcome these hurdles be performing an "initial waiting condition" before interacting with elements on the page. The supported initial wait conditions include:
All public functions/actions defined on the PageElement class that interact with an element on the page or that retrieve or check an element's state automatically wait for this initial wait condition to become true before proceeding with any other functionality.
PageElement furthermore provides three apis to:
.currently: retrieve or check the current state.wait: wait for a certain state.eventually: check if a certain state is eventually reached within a specific timeout.Store type of the PageNodeStore instance which can be used to retrieve/create PageNodes