Options
All
  • Public
  • Public/Protected
  • All
Menu

Class PageElementMap<Store, K, PageElementType, PageElementOpts>

A PageElementMap manages multiple related "static" PageElements which all have the same type and the same "base" selector.

The PageElements managed by PageElementMap are always known in advance and do not change (eg. navigation menu entries). They can therefore be statically identified when PageElementMap is initially created by constraining the map's "base" XPath selector using XPath modification functions.

This initial identification process makes use of a mappingObject and a mappingFunc which are both defined in PageElement's identifier object:

  • For each property of mappingObject, mappingFunc is invoked with the map's "base" selector as the first and the value of the currently processed property as the second parameter.
  • mappingFunc then constrains the "base" selector by using XPath modification functions which are passed the values of the currently processed properties as parameters.
  • Each resulting constrained selector is used to retrieve a managed PageElement from the map's PageNodeStore.
  • These identified PageElements are then mapped to the corresponding key names of mappingObject's properties

The resulting object of mapped PageElements can be accessed via PageElementMap's $ accessor.

All of PageElementMap's state retrieval (getXXX) and state check functions (hasXXX/hasAnyXXX/containsXXX) return their result values as a result map. This is an object whose key names or taken from PageElementMap's $ accessor and whose values are the results of the respective function being executed on the mapped PageElement.

example

// baseSelector = "//nav/a[.="Dashboard"]" // mappingObject = {dashboard: "Dashboard"} // // returns '//nav/a[.="Dashboard"]' for this mappingFunc: ( baseSelector, mappingValue ) => xpath( baseSelector ).text( mappingValue )

// returns {dashboard: PageElement("//nav/a[.="Dashboard"]")} this.$

template

Store type of the PageNodeStore instance which can be used to retrieve/create PageNodes

template

K the key names of PageElementMap's $ accessor used to access the map's managed PageElements

template

PageElementType type of the PageElements managed by PageElementList

template

PageElementOpts type of the opts parameter passed to the constructor function of the PageElements managed by PageElementList

Type parameters

Hierarchy

Implements

  • IPageNode
  • IElementNode<Partial<Record<K, string>>, Partial<Record<K, boolean>>, Partial<Record<K, boolean>>>

Index

Constructors

constructor

  • new PageElementMap(selector: string, __namedParameters: object): PageElementMap
  • A PageElementMap manages multiple related "static" PageElements which all have the same type and the same "base" selector.

    The PageElements managed by PageElementMap are always known in advance and do not change (eg. navigation menu entries). They can therefore be statically identified when PageElementMap is initially created by constraining the map's "base" XPath selector using XPath modification functions.

    This initial identification process makes use of a mappingObject and a mappingFunc which are both defined in PageElement's identifier object:

    • For each property of mappingObject, mappingFunc is invoked with the map's "base" selector as the first and the value of the currently processed property as the second parameter.
    • mappingFunc then constrains the "base" selector by using XPath modification functions which are passed the values of the currently processed properties as parameters.
    • Each resulting constrained selector is used to retrieve a managed PageElement from the map's PageNodeStore.
    • These identified PageElements are then mapped to the corresponding key names of mappingObject's properties

    The resulting object of mapped PageElements can be accessed via PageElementMap's $ accessor.

    All of PageElementMap's state retrieval (getXXX) and state check functions (hasXXX/hasAnyXXX/containsXXX) return their result values as a result map. This is an object whose key names or taken from PageElementMap's $ accessor and whose values are the results of the respective function being executed on the mapped PageElement.

    example

    // baseSelector = "//nav/a[.="Dashboard"]" // mappingObject = {dashboard: "Dashboard"} // // returns '//nav/a[.="Dashboard"]' for this mappingFunc: ( baseSelector, mappingValue ) => xpath( baseSelector ).text( mappingValue )

    // returns {dashboard: PageElement("//nav/a[.="Dashboard"]")} this.$

    opts

    the options used to configure an instance of PageElementMap

    Parameters

    • selector: string

      the "base" XPath selector of PageElementMap which is constrained to identify the map's managed PageElements

    • __namedParameters: object
      • elementOptions: PageElementOpts
      • elementStoreFunc: function
          • (selector: string, options: PageElementOpts): PageElementType
          • Parameters

            • selector: string
            • options: PageElementOpts

            Returns PageElementType

      • identifier: IPageElementMapIdentifier<K>
      • superOpts: superOpts

    Returns PageElementMap

Properties

Protected _$

_$: Record<K, PageElementType>

_$ provides access to all mapped PageElements of PageElementMap.

Protected _elementOpts

_elementOpts: PageElementOpts

the options passed to _elementStoreFunc to configure a managed PageElement instance

Protected _elementStoreFunc

_elementStoreFunc: function

This function retrieves an instance of a PageElement mapped by PageElementMap from the map's PageNodeStore.

param

the XPath expression used to identify the retrieved PageElement in the DOM

param

the options used to configure the retrieved PageElement

Type declaration

    • (selector: string, options: PageElementOpts): PageElementType
    • Parameters

      • selector: string
      • options: PageElementOpts

      Returns PageElementType

Protected _identifier

This _identifier provides a mappingObject and a mappingFunc which are used to constrain the "base" XPath selector of PageElementMap using XPath modification functions in order to statically identify a PageElementMap's managed PageElements when the PageElementMap is initially created.

The identified and mapped PageElements can be accessed via PageElementMap's $ accessor.

Protected _lastDiff

_lastDiff: IDiff

Stores the last differences of PageNode's check state functions.

Intended for framework-internal usage only.

Protected _selector

_selector: string

the XPath selector of PageNode

Protected _store

_store: Store

an instance of PageNodeStore which can be used to retrieve/create PageNodes

currently

currently: PageElementMapCurrently<Store, K, PageElementType, PageElementOpts, this>

eventually

eventually: PageElementMapEventually<Store, K, PageElementType, PageElementOpts, this>

wait

wait: PageElementMapWait<Store, K, PageElementType, PageElementOpts, this>

Accessors

$

  • get $(): object

__lastDiff

  • get __lastDiff(): IDiff

Methods

__eventually

  • __eventually(func: function): boolean
  • 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.

    Parameters

    • func: function

      the function which is supposed to return true within a specific timeout

        • (): void
        • Returns void

    Returns boolean

__execute

  • __execute<ResultType>(func: function): ResultType
  • 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.

    template

    ResultType the result type of the executed function

    Type parameters

    • ResultType

    Parameters

    • func: function

      the function to be executed

        • (): ResultType
        • Returns ResultType

    Returns ResultType

    the result value of the executed function

__getNodeId

  • __getNodeId(): string

__setLastDiff

  • __setLastDiff(diff: IDiff): void

__wait

  • __wait(func: function, errorMessage: string, timeout: number): this
  • 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.

    Parameters

    • func: function

      the function which is supposed to return true within a specific timeout and throws an error if the condition does not become true

        • (): boolean
        • Returns boolean

    • errorMessage: string

      an errorMessage that describes the condition which did not become true within a specific timeout

    • timeout: number

      the timeout used to wait for the result of the passed func to return true

    Returns this

    this (an instance of PageNode)

__waitUntil

  • __waitUntil(waitFunc: function, errorMessageFunc: function, timeout: number, interval?: number): this
  • 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.

    Parameters

    • waitFunc: function

      the function which is supposed to return true within a specific timeout

        • (): boolean
        • Returns boolean

    • errorMessageFunc: function

      a function that returns an errorMessage which describes the condition that did not become true within a specific timeout

        • (): string
        • Returns string

    • timeout: number

      the timeout used to wait for the result of the waitFunc to return true

    • Optional interval: number

      the interval used to check for the result of the waitFunc to return true

    Returns this

    this (an instance of PageNode)

Protected _handleWaitError

  • _handleWaitError(error: any, errorMessage: string, timeout: number): void
  • This function implements custom error handling for 'could not be located' and 'WaitUntilTimeoutError' errors.

    Parameters

    • error: any

      an arbitrary type of error

    • errorMessage: string

      used to describe the failed condition check which caused a WaitUntilTimeoutError

    • timeout: number

      the timeout used to wait for an element to be located or for a wait condition to return true

    Returns void

Protected _includedInFilter

  • _includedInFilter(value: any): boolean
  • Used to determine if a function of a managed PageElement should be invoked or if its invocation should be skipped because the PageElement is not included by a filterMask.

    Parameters

    • value: any

    Returns boolean

changeMappingObject

  • changeMappingObject(mappingObject: Record<K, string>): void
  • This function changes the mappingObject used by PageElementMap's identifier object to constrain the "base" XPath selector of PageElementMap using XPath modification functions in order to statically identify a PageElementMap's managed PageElements.

    This can be useful if, for example, the links of a navigation menu are represented using a PageElementMap and the GUI is switched to another language: Now the values used to identify the links by text change while the keys used to access the links via tha map's $ property stay the same.

    Parameters

    • mappingObject: Record<K, string>

    Returns void

eachCheck

  • eachCheck<T>(context: Record<K, PageElementType>, checkFunc: function, expected: Partial<Record<K, T>>, isFilterMask?: boolean): boolean
  • Invokes a state check function for each PageElement in a passed context map and returns true if the result of each state check function invocation was true.

    template

    T the type of an expected value

    Type parameters

    • T

    Parameters

    • context: Record<K, PageElementType>

      a map containing all PageElements for which checkFunc should be executed

    • checkFunc: function

      a state check function executed for each PageElement in context. It is passed a PageElement as first parameter and an expected value used by the state check comparison as an optional second parameter.

        • (element: PageElementType, expected?: T): boolean
        • Parameters

          • element: PageElementType
          • Optional expected: T

          Returns boolean

    • expected: Partial<Record<K, T>>

      a map of expected values used for the state check comparisons

    • Default value isFilterMask: boolean = false

      if set to true, the expected parameter represents a filterMask which can be used to skip the invocation of the state check function for some or all PageElements. The results of skipped function invocations are not included in the results map.

    Returns boolean

    true if the state check functions of all checked PageElements returned true or if no state check functions were invoked at all

eachCompare

  • eachCompare<T>(context: Record<K, PageElementType>, checkFunc: function, expected: Partial<Record<K, T>>, isFilterMask?: boolean): Partial<Record<K, boolean>>
  • Invokes a state check function for each PageElement in a passed context map and returns a map of state check function results.

    template

    T the type of an expected value

    Type parameters

    • T

    Parameters

    • context: Record<K, PageElementType>

      a map containing all PageElements for which checkFunc should be executed

    • checkFunc: function

      a state check function executed for each PageElement in context. It is passed a PageElement as first parameter and an expected value used by the state check comparison as an optional second parameter.

        • (element: PageElementType, expected?: T): boolean
        • Parameters

          • element: PageElementType
          • Optional expected: T

          Returns boolean

    • expected: Partial<Record<K, T>>

      a map of expected values used for the state check comparisons

    • Default value isFilterMask: boolean = false

      if set to true, the expected parameter represents a filterMask which can be used to skip the invocation of the state check function for some or all PageElements. The results of skipped function invocations are not included in the total results map.

    Returns Partial<Record<K, boolean>>

    an map of results of a state check function executed for each PageElement in context

eachDo

  • Invokes an action for each of PageElementMap's managed PageElements.

    Parameters

    • action: function

      an action executed for each of PageElementMap's managed PageElements

        • (element: PageElementType): any
        • Parameters

          • element: PageElementType

          Returns any

    • Optional filterMask: MapFilterMask<K>

      can be used to skip the execution of an action for some or all PageElements

    Returns this

    this (an instance of PageElementMap)

eachGet

  • eachGet<T>(context: Record<K, PageElementType>, getFunc: function, filterMask: MapFilterMask<K>): Partial<Record<K, T>>
  • Invokes a state retrieval function for each PageElement in a passed context map and returns a map of state retrieval function results.

    template

    T the type of a value of the results map

    Type parameters

    • T

    Parameters

    • context: Record<K, PageElementType>

      a map containing all PageElements for which getFunc should be executed

    • getFunc: function

      a state retrieval function executed for each PageElement in context. It is passed a PageElement as first parameter.

        • (node: PageElementType): T
        • Parameters

          • node: PageElementType

          Returns T

    • filterMask: MapFilterMask<K>

      can be used to skip the invocation of the state retrieval function for some or all PageElements. The results of skipped function invocations are not included in the total results map.

    Returns Partial<Record<K, T>>

    an map of results of a state retrieval function executed for each PageElement in context

eachSet

  • eachSet<T>(context: Record<K, PageElementType>, setFunc: function, values: Partial<Record<K, T>>): this
  • Invokes a setter function for each PageElement in a passed context map.

    template

    T the type of a single setter value

    Type parameters

    • T

    Parameters

    • context: Record<K, PageElementType>

      a map containing all PageElements for which setFunc should be executed

    • setFunc: function

      a setter function executed for each PageElement in context. It is passed a PageElement as first parameter and the value to be set as second parameter.

        • (element: PageElementType, value?: T): PageElementType
        • Parameters

          • element: PageElementType
          • Optional value: T

          Returns PageElementType

    • values: Partial<Record<K, T>>

      a map of setter values

    Returns this

    this (an instance of PageElementMap)

eachWait

  • eachWait<ValueType>(context: Record<K, PageElementType>, waitFunc: function, expected: Partial<Record<K, ValueType>>, isFilterMask?: boolean): this
  • Invokes a wait function for each PageElement in a passed context map.

    template

    T the type of an expected value

    Type parameters

    • ValueType

    Parameters

    • context: Record<K, PageElementType>

      a map containing all PageElements for which checkFunc should be executed

    • waitFunc: function

      a wait function executed for each PageElement in context. It is passed a PageElement as first parameter and an expected value used by the wait condition as an optional second parameter.

        • (element: PageElementType, expected?: ValueType): PageElementType
        • Parameters

          • element: PageElementType
          • Optional expected: ValueType

          Returns PageElementType

    • expected: Partial<Record<K, ValueType>>

      a map of expected values used for the wait conditions

    • Default value isFilterMask: boolean = false

      if set to true, the expected parameter represents a filterMask which can be used to skip the invocation of the wait function for some or all PageElements.

    Returns this

    this (an instance of PageElementMap)

getContainsDirectText

  • getContainsDirectText(directTexts: Partial<Record<K, string>>): object
  • Returns the 'containsDirectText' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each managed PageElement.

    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.

    Parameters

    • directTexts: Partial<Record<K, string>>

      the expected direct texts used in the comparisons which set the 'containsDirectText' status

    Returns object

getContainsText

  • getContainsText(texts: Partial<Record<K, string>>): object
  • Returns the 'containsText' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each managed PageElement.

    A PageElement's 'containsText' status is set to true if its actual text contains the expected text.

    Parameters

    • texts: Partial<Record<K, string>>

      the expected texts used in the comparisons which set the 'containsText' status

    Returns object

getDirectText

  • Returns the direct texts of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each PageElement.

    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.

    Parameters

    • Optional filterMask: MapFilterMask<K>

      can be used to skip the invocation of the getDirectText function for some or all managed PageElements. The results of skipped function invocations are not included in the total results object.

    Returns object

getHasAnyDirectText

  • Returns the 'hasAnyDirectText' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each managed PageElement.

    A PageElement's 'hasAnyDirectText' status is set to true if the PageElement has any 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.

    Parameters

    • Optional filterMask: MapFilterMask<K>

      can be used to skip the invocation of the getHasAnyDirectText function for some or all managed PageElements. The results of skipped function invocations are not included in the total results object.

    Returns object

getHasAnyText

  • Returns the 'hasAnyText' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each managed PageElement.

    A PageElement's 'hasAnyText' status is set to true if the PageElement has any text.

    Parameters

    • Optional filterMask: MapFilterMask<K>

      can be used to skip the invocation of the getHasAnyText function for some or all managed PageElements. The results of skipped function invocations are not included in the total results object.

    Returns object

getHasDirectText

  • getHasDirectText(directTexts: Partial<Record<K, string>>): object
  • Returns the 'hasDirectText' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each managed PageElement.

    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.

    Parameters

    • directTexts: Partial<Record<K, string>>

      the expected direct texts used in the comparisons which set the 'hasDirectText' status

    Returns object

getHasText

  • getHasText(texts: Partial<Record<K, string>>): object
  • Returns the 'hasText' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each managed PageElement.

    A PageElement's 'hasText' status is set to true if its actual text equals the expected text.

    Parameters

    • texts: Partial<Record<K, string>>

      the expected texts used in the comparisons which set the 'hasText' status

    Returns object

getIsEnabled

  • getIsEnabled(filterMask?: MapFilterMask<K>): Partial<Record<K, boolean>>
  • Returns the 'enabled' status of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each PageElement.

    Parameters

    • Optional filterMask: MapFilterMask<K>

      can be used to skip the invocation of the getIsEnabled function for some or all managed PageElements. The results of skipped function invocations are not included in the total results object.

    Returns Partial<Record<K, boolean>>

getSelector

  • getSelector(): string

getText

  • Returns the texts of all PageElements managed by PageElementMap as a result map after performing the initial waiting condition of each PageElement.

    Parameters

    • Optional filterMask: MapFilterMask<K>

      can be used to skip the invocation of the getText function for some or all managed PageElements. The results of skipped function invocations are not included in the total results object.

    Returns object

toJSON

Generated using TypeDoc