Class GetShadowRoot

Namespace

CSF.Screenplay.Selenium.Tasks

Assembly

CSF.Screenplay.Selenium.dll

A Screenplay Task which gets the Shadow Root element from the specified Selenium Element, using the best available technique for the current web browser.

public class GetShadowRoot : IPerformableWithResult<ShadowRoot>, ICanReport

Inheritance

object

GetShadowRoot

Implements

IPerformableWithResult<ShadowRoot>

ICanReport

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This is used when working with web pages which use The Shadow DOM technique. This question allows Screenplay to 'pierce' the Shadow DOM and get the Shadow Root element, so that the Performance may continue and interact with elements which are inside the Shadow DOM.

Note that the SeleniumElement which is returned from this question is not a fully-fledged Selenium Element. It may be used only to get/find elements from inside the Shadow DOM. Use with any other performables will raise NotSupportedException.

The ITarget passed to this performable as a parameter must be the Shadow Host element.

This task will automatically select the best technique by which to get a Shadow Root. For modern Chromium or Firefox-based browsers, it will use the native technique: GetTheShadowRootNativelyFrom(ITarget). For older Chromium-based browsers, or any version of Safari it will use a JavaScript approach: GetTheShadowRootWithJavaScriptFrom(ITarget). For very old versions of Firefox, this performable will throw an exception, as there is no supported way to get a Shadow Root.

Constructors

GetShadowRoot(ITarget)

Initializes a new instance of GetShadowRoot.

public GetShadowRoot(ITarget element)

Parameters

element ITarget

The Shadow Host element

Exceptions

ArgumentNullException

If element is null

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 and returns a strongly-typed value.

public ValueTask<ShadowRoot> 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<ShadowRoot>

A task which exposes a strongly-typed 'result' value when the performable represented by the current instance is complete.