Class ClickAndWaitForDocumentReady

Namespace

CSF.Screenplay.Selenium.Tasks

Assembly

CSF.Screenplay.Selenium.dll

A Screenplay task which combines a Click action with cross-browser waiting logic, for navigating to a new web page.

public class ClickAndWaitForDocumentReady : ISingleElementPerformable, ICanReportForElement

Inheritance

object

ClickAndWaitForDocumentReady

Implements

ISingleElementPerformable

ICanReportForElement

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

This example demonstrates clicking a link to a settings page and waiting for the page to be ready.

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

readonly ITarget settingsLink = new CssSelector("nav#app_navigation .settings a", "the link to the settings page");

// Within the logic of a custom task, deriving from IPerformable
public async ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    await actor.PerformAsync(ClickOn(settingsLink).AndWaitForANewPageToLoad(), cancellationToken);
    // regardless of WebDriver implementation, further performables here will not execute
    // until the settings page has completely loaded.
}

Remarks

Use this task in performance logic using the builder method ClickOn(ITarget), following this up with the AndWaitForANewPageToLoad(TimeSpan?) method. That builder functionality differentiates the returned performable from the normal Click action.

The rationale for this task's existence is primarily to deal with web browsers which are affected by the quirk NeedsToWaitAfterPageLoad. See the documentation for that quirk for more information on what it means for web browser.

This task deals with browsers affected by that quirk by extending the click behaviour. When the WebDriver is affected by this quirk, as well as clicking upon an element, a reference to that element is saved. The WebDriver is then polled until the element clicked has become stale. A stale element is one which is no longer present in the web browser. The staleness of the clicked element is used as a proxy for the unloading of the 'outgoing' web page. Once the mechanism describe above has determined that the outgoing web page has unloaded, this task begins a second waiting process. The second wait executes the JavaScript GetTheDocumentReadyState repeatedly until it returns the result complete. At that point, the waiting is over and the performance may continue.

The mechanism described above also includes an optional (constructor injected) timeout. The timeout is used twice; it applies both to the unloading of the old page the ready-state of the new page returning complete. Thus in a theoretical worst-case scenario, this task could lead to a wait of twice the specified timeout value. If the timeout is not specified then it will use the value from UseADefaultWaitTime if the actor has that ability. If not then the hardcoded fall-back DefaultTimeout of 5 seconds will be used.

Constructors

ClickAndWaitForDocumentReady(TimeSpan?)

Initializes a new instance of the ClickAndWaitForDocumentReady class.

public ClickAndWaitForDocumentReady(TimeSpan? waitTimeout)

Parameters

waitTimeout TimeSpan?

The timeout duration for both the page-unload and document-ready waits. See the remarks on this class for more info.

Methods

GetReportFragment(Actor, Lazy<SeleniumElement>, IFormatsReportFragment)

Counterpart to GetReportFragment(Actor, IFormatsReportFragment) except that this method also offers a Selenium element.

public ReportFragment GetReportFragment(Actor actor, Lazy<SeleniumElement> element, IFormatsReportFragment formatter)

Parameters

actor Actor

An actor for whom to write the report fragment

element Lazy<SeleniumElement>

The Selenium element for which the report is being written

formatter IFormatsReportFragment

A report-formatting service

Returns

ReportFragment

A human-readable report fragment.

Remarks

Please see the documentation for GetReportFragment(Actor, IFormatsReportFragment) for more information.

PerformAsAsync(ICanPerform, IWebDriver, Lazy<SeleniumElement>, CancellationToken)

Counterpart to PerformAsAsync(ICanPerform, CancellationToken) except that this method also offers a Selenium WebDriver and element.

public ValueTask PerformAsAsync(ICanPerform actor, IWebDriver webDriver, Lazy<SeleniumElement> element, CancellationToken cancellationToken = default)

Parameters

actor ICanPerform

The actor that is performing.

webDriver IWebDriver

The Selenium WebDriver provided from the actor's abilities.

element Lazy<SeleniumElement>

The single Selenium Element upon which this method should operate.

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

NeedsToWaitAfterPageLoad

ClickOn(ITarget)

AndWaitForANewPageToLoad(TimeSpan?)

UseADefaultWaitTime

DefaultTimeout