OnScreenElement Methods

CloneForMultipleInstances

This method is used to clone an element when finding all instances with FindAllInstances. The returned elements are in general shallow clones of the original element, however for elements with sub-elements (e.g. LabelWithCheckbox) those should be cloned in an override.

Syntax:

public virtual OnScreenElement CloneForMultipleInstances()

Return Value:

A clone of the element.

FindAllInstances

Finds all instances of the element that are visible on the screen and returns them as a list of OnScreenElement. The returned elements all have UseCachedPosition set to true, so that the respective position is used when we interact with the element. The returned elements are in general shallow clones of the original element, however for elements with sub-elements (e.g. LabelWithCheckbox) those should be cloned in an override of the CloneForMultipleInstances method.

Syntax:

public IList<IEngineResult> FindAllInstances()

Return Value:

A list of elements corresponding to all positions where the element was found on the screen.

Exceptions:

Exception	Condition
ElementNotFoundException	When the element is not found at all.
ScreenNotFoundException	When the element is not found at all. (In the case that the element is derived from BaseScreen)

FindAllInstances<T>

Finds all instances of the element that are visible on the screen.

Syntax:

public IList<IEngineResult> FindAllInstances()

Return Value:

A list of all positions (IEngineResults) where the current element was found on the screen.

Exceptions:

Exception	Condition
ElementNotFoundException	When the element is not found at all.
ScreenNotFoundException	When the element is not found at all. (In the case that the element is derived from BaseScreen)

IsOnScreen

Determines whether the element is currently shown on the screen, using the WaitFor method with a very short wait time. Note: Do not use this if you expect the element to appear after an action (e.g. as verify method of another action), only if the screen is expected to be static.

Syntax:

public bool IsOnScreen()

ScrollAndFindElement

Uses the provided IScroller (if available) to find the OnScreenElement in a scrollable area. If the element is not found at current position, scrolls to top and then down in steps.

Syntax:

public IEngineResult ScrollAndFindElement(
	IScroller scroller,
	bool throwException = true,
	TimeSpan searchTime = default
)

Parameters:

Parameter	Description
scroller	Type: IScroller The scroller that shall be used to find the elemnt. Typically the scroller is a property on the screen object containing the element.
[throwException]	Type: Boolean if set to false, returns a failed IEngineResult instead of throwing an exception.
[waitTime]	Type: TimeSpan For how long the element should be searched before each scroll action. If not set or set to default(TimeSpan), only 1 search is performed before scrolling again (recommended).

Return Value:

The IEngineResult of the search for the element.

Exceptions:

Exception	Condition
ElementNotFoundException	When the element is not found after scrolling through the complete range, and throwException is true or not set.

SetSelectFilter

Adds the select filter to Filters or replaces any existing Select filter. Other filter types in Filters are not changed. If Filters was not yet defined, it is created by this method. Invalid or empty Select filters are ignored by this method and the Filters property is not changed.

Syntax:

public void SetSelectFilter(
	Select select
)

Parameters:

Parameter	Description
select	Type: Select The new Select filter to be used for this element.

ToString

Returns a string that represents this instance, usually the DisplayName. Used for logging; just use $"{this}".

Syntax:

public string ToString()

WaitFor

Waits for the element to appear on screen and returns an IEngineResult. If the element is found, it will call the Initialize method to initialize potential child elements that depend on the Position found by WaitFor. By default throws an exception if the element is not found after WaitTimeInSeconds.

Syntax:

public virtual IEngineResult WaitFor(
	bool throwException = true,
	TimeSpan waitTime = default(TimeSpan)
)

Parameters:

Parameter	Description
[throwException]	Type: Boolean if set to false, returns a failed IEngineResult instead of throwing an exception.
[waitTime]	Type: TimeSpan For how long the element should be searched. If not set or set to default(TimeSpan), the WaitTimeInSeconds property is used.

Return Value:

The IEngineResult of the search for the element.

Exceptions:

Exception	Condition
ElementNotFoundException	When the element is not found, and throwException is true or not set.

WaitForAppear

Shorthand notation for WaitFor(false).HasSucceeded; Can be used as verify function without lambda operator (e.g. Buttton.Click(element.WaitForDisappear);) Note: This method logs, whereas WaitFor() does not log.

Syntax:

public bool WaitForAppear()

WaitForDisappear

Waits for the element to disappear from the screen. Returns false if element is still found after DisappearWaitTimeInSeconds. Can be used as verify function without lambda operator (e.g. Buttton.Click(element.WaitForDisappear);)

Syntax:

public bool WaitForAppear()

WaitForDisappearOrOtherElement

Waits for the element to disappear from the screen or any element from elements to appear. This is often used as verify method of an interaction that closes a dialog or similar but can also show a warning instead. Returns false if this element is still found after DisappearWaitTimeInSeconds and no element from elements was found. Will return the element that was found in foundElement.

Syntax:

public bool WaitForDisappearOrOtherElement(
    out OnScreenElement foundElement,
    params OnScreenElement[] elements
)

Parameters:

Parameter	Description
foundElement	Type: OnScreenElement The element that was found or null, if this element disappeared.
elements	Type: OnScreenElement[] A list of elements that can appear instead of this element disappearing. Typically warnings, confirmation or failure notification.

Return Value:

True, if this element disappeared or an element from elements was found. Otherwise false.

Exceptions:

Exception	Condition
ArgumentNullException	When elements is null or an empty list.

Protected Methods

WaitForImpl

The implementation for WaitFor that performs the actual search of the element on the screen.

Syntax:

protected virtual IEngineResult WaitForImpl(
    TimeSpan waitTime,
    ImageReference imgRef = null
)

Parameters:

Parameter	Description
waitTime	Type: TimeSpan For how long the element should be searched.
imgRef	Type: ImageReference A specific image representation to wait for, or null to wait for ImageReferences

Return Value:

The IEngineResult of the search for the element.

WaitFor (ImageReference, bool, TimeSpan)

Waits for a specific imageReference of the element to appear on screen and returns an IEngineResult. This method is intended for elements like Button or Checkbox to Wait for a certain state (like inactive or checked). If imageReference is null, behaves like WaitFor(bool, TimeSpan) If the imageReference is found, it will call the Initialize method to initialize potential child elements that depend on the Position found by WaitFor. By default throws an exception if the element is not found after WaitTimeInSeconds.

Syntax:

protected virtual IEngineResult WaitFor(
	ImageReference imageReference,
	bool throwException = true,
	TimeSpan waitTime = default(TimeSpan)
)

Parameters:

Parameter	Description
imageReference	Type: ImageReference The image reference that will be used to locate the element on the screen.
[throwException]	Type: Boolean if set to false, returns a failed IEngineResult instead of throwing an exception.
[waitTime]	Type: TimeSpan For how long the element should be searched. If not set or set to default(TimeSpan), the WaitTimeInSeconds property is used.

Return Value:

The IEngineResult of the search for the element.

Exceptions:

Exception	Condition
ElementNotFoundException	When the element is not found, and throwException is true or not set.

Do (Action, Func<bool>)

Executes the specified interact method on the element and verifies the interaction with the verify function. Performs RetryCount retries if the verify is not successful.

Syntax:

protected virtual void Do(
    Action interact,
    Func<bool> verify
)

Parameters:

Parameter	Description
interact	Type: Action The interaction that should be performed and retried if verify was not successful. Note: Ensure that the interact can be executed more than once or set RetryCount to 1.
verify	Type: Func<Boolean> The verification method that will decide whether the interaction was successful or it should be retried.

Exceptions:

Exception	Condition
InteractionFailedException	When verify returned false even after the retries.

Do (Action, Func<bool>, Action)

Executes the specified interact method on the element and verifies the interaction with the verify function. Performs RetryCount retries if the verify is not successful. Before each retry, a recovery action is executed.

Syntax:

protected virtual void Do(
    Action interact,
    Func<bool> verify,
    Action recovery
)

Parameters:

Parameter	Description
interact	Type: Action The interaction that should be performed and retried if verify was not successful. Note: Ensure that the interact can be executed more than once or set RetryCount to 1.
verify	Type: Func<Boolean> The verification method that will decide whether the interaction was successful or it should be retried.
recovery	Type: Action The action that should be performed if the verify failed before doing a retry. This can be used to make sure the state of the element is the same as before the first interact (e.g. Click out to unfocus, close DropdownList, etc)

Exceptions:

Exception	Condition
InteractionFailedException	When verify returned false even after the retries.

Initialize

Initializes potential child controls on this Element. This method is called when WaitFor() did find the element. Has no implementation on OnScreenElement.

Syntax:

protected virtual void Initialize()