Class Wait

Namespace

CSF.Screenplay.Selenium.Actions

Assembly

CSF.Screenplay.Selenium.dll

A Screenplay action which pauses the Performance until either a specified condition is met or a timeout expires, whichever occurs sooner.

public class Wait : IPerformable, ICanReport

Inheritance

object

Wait

Implements

IPerformable

ICanReport

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

In this example, Screenplay instructs the WebDriver to wait for up to 2 seconds, or until no element with the class loading_spinner is visible on the web page.

using CSF.Screenplay.Selenium.Elements;
using static CSF.Screenplay.Selenium.PerformableBuilder;

readonly ITarget spinner = new ClassName("loading_spinner", "the loading spinner");

// Within the logic of a custom task, deriving from IPerformable
public async ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    // ... other performance logic
    await actor.PerformAsync(WaitUntil(spinner.Is().NotVisible().ForAtMost(TimeSpan.FromSeconds(2)), cancellationToken);
    // ... other performance logic
}

Remarks

Use this action via either the builder method WaitUntil(IBuildsElementPredicates) or WaitUntil(Func<IWebDriver, bool>). The former is preferred over the latter, as it permits the use of a fluent builder syntax to specify the behaviour of the wait. See the documentation of those builder methods to learn more about their use.

This action forces the progress of the IPerformance to be delayed whilst the WebDriver waits for a condition to be true. Internally, this action makes use of Selenium's WebDriverWait functionality to implement the waiting logic. Documentation for the WebDriver Wait functionality from the web may be useful if you would like a deeper understanding of this action. This action accepts a number of parameters.

The Predicate is the condition for which we are waiting. In other words, we are waiting until the Predicate is true. This is expressed using a WaitUntilPredicate<T>, of bool. See TargetExtensions for extension methods which act as builders for a predicate: Has(ITarget) builds a predicate for a single element whereas AllHave(ITarget) builds a predicate for a collection of elements.

The Timeout is the maximum time which this Action will wait. If the Predicate (above) is not true. If the timeout elapses before the Predicate is true then this action will throw WebDriverTimeoutException. In fact, it is the underlying Selenium WebDriver which will throw this exception; this action does not change that. It is impossible to specify an indefinite timeout. The following rules of precedence are used to ensure that the timeout is always set:

1. If a timeout was specified when constructing this instance, that value is used.
2. If the Actor performing this question has the ability UseADefaultWaitTime, then the time specified by WaitTime is used.
3. If neither of the above apply, a default timeout of 5 seconds is used.

The Polling Interval controls how often the WebDriver queries the web browser to determine if the Predicate (above) has been fulfilled. Shorter polling intervals can lead to more responsive waits, the Performance is not left waiting longer than it needs. The 'cost' of a shorter polling interval is increased traffic between the Screenplay and the WebDriver. This is particularly relevant when using a Remote WebDriver, as this translates to actual network/Internet traffic and latency. If unspecified, Selenium's default polling interval is used. At the time of writing that is 500 milliseconds.

Lastly, the Ignored Exception Types is a collection of Type. Each entry should be a type which derives from Exception which should be silently ignored whilst testing the Predicate (above). This can be useful to ignore errors which are raised because the Predicate isn't true yet, without needing expensive (and performance-impacting) defensive programming. If this collection is specified then these exception types will be caught and silently ignored whilst evaluating the Predicate, treating an exception as "not true".

Constructors

Wait(WaitUntilPredicate<bool>, TimeSpan?, TimeSpan?, ICollection<Type>)

Initializes a new instance of the Wait class.

public Wait(WaitUntilPredicate<bool> predicate, TimeSpan? timeout, TimeSpan? pollingInterval = null, ICollection<Type> ignoredExceptionTypes = null)

Parameters

predicate WaitUntilPredicate<bool>

The predicate function to evaluate.

timeout TimeSpan?

An optional maximum amount of time to wait for the condition; the default is determined by the presence of the UseADefaultWaitTime ability. See the documentation of this class for more details.

pollingInterval TimeSpan?

An optional interval at which to poll the predicate; the Selenium default is 500ms.

ignoredExceptionTypes ICollection<Type>

An optional collection of types of exceptions to ignore while waiting; the default is an empty collection.

Fields

DefaultTimeout

This default timeout of 5 seconds used when no timeout is specified and the actor has no UseADefaultWaitTime ability.

public static readonly TimeSpan DefaultTimeout

Field Value

TimeSpan

Remarks

This, along with a few other performables in the Selenium extension for Screenplay involve waiting, with a timeout to prevent waiting indefinitely. If no timeout has been specified then this 5-second timeout is used as a fall-back default. This may be overridden by granting the Actor the ability UseADefaultWaitTime, with a different timeout specified.

Methods

GetReportFragment(Actor, IFormatsReportFragment)

Gets a fragment of a Screenplay report, specific to the execution (performables) or gaining (abilities) of the current instance, for the specified actor.

public ReportFragment GetReportFragment(Actor actor, IFormatsReportFragment formatter)

Parameters

actor Actor

An actor for whom to write the report fragment

formatter IFormatsReportFragment

A report-formatting service

Returns

ReportFragment

A human-readable report fragment.

Examples

For a performable which clicks a button (where the button itself has been constructor-injected into the performable instance), then a suitable return value might be a formatted string such as {Actor name} clicks {Button}, where the two placeholders indicated by braces: {} are substituted with the actor's Name and a string representation of the button.

For a performable which reads the temperature from a thermometer, a suitable return value might be a string in the format {Actor name} reads the temperature.

For an ability which allows the actor to wash dishes then a suitable return value might be a string in the format {Actor name} is able to wash the dishes.

Remarks

Implementers should return a string which indicates that the named actor is performing (present tense) the performable, for types which also implement a performable interface. For types which represent abilities, the implementer should return a string which indicates that the named actor is able to do something. In particular for abilities, to make them easily recognisable in reports, it helps to stick to the convention {Actor name} is able to {Ability summary}.

For performables which return a value (Questions, or Tasks which behave like Questions), there is no need to include the returned value within the report fragment. The framework will include the return value in the report and will format it via a different mechanism.

Good report fragments are concise. Be aware that report fragments for Tasks (which are composed from other performables) do not need to go into detail about what they do. Users reading Screenplay reports are able to drill-down into Tasks to see what they are composed from, so if the user is curious as to what the task does, it is easy to discover. It is also strongly recommended to avoid periods (full stops) at the end of a report fragment. Whilst report fragments tend to be complete sentences, punctuation like this is distracting and reports are seldom presented as paragraphs of prose.

PerformAsAsync(ICanPerform, CancellationToken)

Performs the action(s) are represented by the current instance.

public ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)

Parameters

actor ICanPerform

The actor that is performing.

cancellationToken CancellationToken

An optional cancellation token by which to abort the performable.

Returns

ValueTask

A task which completes when the performable represented by the current instance is complete.

See Also

WaitUntil(IBuildsElementPredicates)

WaitUntil(Func<IWebDriver, bool>)

UseADefaultWaitTime