TestResults.io
Product
Search
⌃K
Links

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
When the element is not found at all.
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
When the element is not found at all.
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
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
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
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
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
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()
Previous
OnScreenElement
Next
OnScreenElement Properties
Last modified 10d ago