Class NamedWaitBuilder

Namespace

CSF.Screenplay.Selenium.Builders

Assembly

CSF.Screenplay.Selenium.dll

Provides a builder for configuring wait actions in Selenium.

public class NamedWaitBuilder : IGetsPerformable

Inheritance

object

NamedWaitBuilder

Implements

IGetsPerformable

Derived

UnnamedWaitBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class provides methods for configuring various aspects of a wait action, such as timeout, polling interval, and ignored exception types. Using this class directly requires that a WaitUntilPredicate instance is provided to the constructor. The specified predicate provides both the logic to evaluate and a human-readable name for the wait condition.

Constructors

NamedWaitBuilder()

Initializes a new instance of the NamedWaitBuilder class.

protected NamedWaitBuilder()

Remarks

This constructor is protected, as it is only to be used by derived classes which provide an alternative implementation of GetWaitUntilPredicate().

NamedWaitBuilder(WaitUntilPredicate<bool>)

Initializes a new instance of the NamedWaitBuilder class.

public NamedWaitBuilder(WaitUntilPredicate<bool> predicate)

Parameters

predicate WaitUntilPredicate<bool>

The predicate which ends the wait when it returns a successful result.

Properties

IgnoredExceptionTypes

Gets or sets the collection of exception types which will be ignored when evaluating the wait predicate.

protected ICollection<Type> IgnoredExceptionTypes { get; set; }

Property Value

ICollection<Type>

PollingInterval

Gets or sets the interval at which Selenium will poll to determine if the predicate to end the wait has been met.

protected TimeSpan? PollingInterval { get; set; }

Property Value

TimeSpan?

Remarks

If this property is null, then Selenium provides a default polling interval of 500ms.

Timeout

Gets or sets the maximum timeout for the wait action.

protected TimeSpan? Timeout { get; set; }

Property Value

TimeSpan?

Methods

ForAtMost(TimeSpan)

Configures the wait action to use a specified maximum timeout.

public NamedWaitBuilder ForAtMost(TimeSpan timeout)

Parameters

timeout TimeSpan

The maximum amount of time to wait.

Returns

NamedWaitBuilder

The same wait builder, so that calls may be chained.

Remarks

If the timeout is reached before the predicate function returns a true result then the wait will end, and an exception will be raised.

This method is optional. If it is not called then the default behaviour of the Wait question will be used. See the documentation for that class for more details.

GetWaitUntilPredicate()

Gets the wait-until predicate, which wraps both the predicate logic and a human-readable name.

protected virtual WaitUntilPredicate<bool> GetWaitUntilPredicate()

Returns

WaitUntilPredicate<bool>

The wait-until predicate instance.

IgnoringTheseExceptionTypes(params Type[])

Configures the wait action which will be created to ignore exceptions of the specified types.

public NamedWaitBuilder IgnoringTheseExceptionTypes(params Type[] ignoredExceptionTypes)

Parameters

ignoredExceptionTypes Type[]

A collection of exception types to be ignored when polling the predicate function.

Returns

NamedWaitBuilder

Remarks

When evaluating the predicate/condition function, the WebDriver may throw exceptions, such as if an element doesn't exist. Use this method to specify a collection of exception types which should be ignored. If an exception thrown of one of these types then the WebDriver wait will treat it the same as a false outcome and continue to poll the predicate.

This method is optional. If it is not called then by default, only exceptions of type TargetNotFoundException will be ignored. That is - waiting will continue if the target element does not yet exist. If you choose to replace this collection with your own, be sure to include the type TargetNotFoundException if you wish to retain that behaviour.

Exceptions

InvalidOperationException

Thrown if the ignored exception types have already been set.

WithPollingInterval(TimeSpan)

Configures the wait action which will be created to use a specified polling interval.

public NamedWaitBuilder WithPollingInterval(TimeSpan pollingInterval)

Parameters

pollingInterval TimeSpan

The polling interval to use.

Returns

NamedWaitBuilder

The same wait builder, so that calls may be chained.

Remarks

The polling interval is the amount of time that the WebDriver will wait between each evaluation of the predicate function.

This method is optional. If it is not called then Screenplay will not specify a polling interval. Selenium will then use its own default interval, which is 500ms.

Choosing a polling interval is a balance between responsiveness and resource usage. A shorter polling interval may lead to quicker detection of the condition being met (a more responsive predicate), but at the cost of increased network usage as more round-trips are made to the WebDriver. Conversely, a longer polling interval reduces network traffic but may result in a less responsive predicate. If you are not sure what to choose, it's recommended not to use this method; use the default provided by Selenium.

Exceptions

InvalidOperationException

Thrown if the polling interval has already been set.