Table of Contents

Class OpenUrlRespectingBase

Namespace
CSF.Screenplay.Selenium.Tasks
Assembly
CSF.Screenplay.Selenium.dll

A Screenplay task which navigates directly to a specified URL using the actor's WebDriver. If the specified Uri is relative then it is made absolute by basing it upon the Uri indicated by the UseABaseUri ability.

public class OpenUrlRespectingBase : IPerformable, ICanReport
Inheritance
OpenUrlRespectingBase
Implements
Inherited Members

Examples

This task is used in exactly the same way as OpenUrl. The example below shows the opening of the URL https://example.com/user/shoppingCart. Note that in a real performance, the actor would be granted the UseABaseUri ability at a far higher-level performable than the position in which they are performing navigation. This example is 'compressed' for brevity. 

using static CSF.Screenplay.Selenium.PerformableBuilder;

var examplePage = new NamedUri("user/shoppingCart", "the user's shopping cart");

// Within the logic of a custom task, deriving from IPerformable
public async ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    actor.IsAbleTo(new UseABaseUri(new Uri("https://example.com")));
    await actor.PerformAsync(OpenTheUrl(examplePage), cancellationToken);
}

Remarks

Use this task via the builder method OpenTheUrl(NamedUri), which automatically makes use of this task. This task behaves very similarly to the action OpenUrl, except for base-URI-replacement.

When this task is used, if the specified named Uri (constructor injected) is already absolute then this task has no effect beyond passing that same absolute Uri to OpenUrl. If the specified Uri is relative then the UseABaseUri ability is retrieved from the actor; this will throw if the actor does not possess the ability. If they do, then the Uri specified to this task will be rebased onto the BaseUri, via RebaseTo(Uri). The rebased Uri will then be used with OpenUrl.

The purpose of this task is to permit developers to specify NamedUri instances using relative Uri values instead of absolute ones. When doing so, the performance must grant the UseABaseUri ability to the actor who is making use of the WebDriver (via BrowseTheWeb). This allows the final absolute Uris for the functionality to be determined at runtime, via the combination of a base Uri and a relative part.

This is expected to be useful to developers, who may need their Screenplay logic to operate upon a specified environment (determined by a base Uri) at runtime. However, the relative Uri paths to pages within that environment remain identical regardless of the environment. The combination of the UseABaseUri ability and this task make such an architecture possible.

Constructors

OpenUrlRespectingBase(NamedUri)

Initializes a new instance of the OpenUrlRespectingBase class with the specified URL.

public OpenUrlRespectingBase(NamedUri uri)

Parameters

uri NamedUri

The URL to open.

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

UseABaseUri
OpenTheUrl(NamedUri)
OpenUrl
Edit this page