Table of Contents

Class FindElements

Namespace
CSF.Screenplay.Selenium.Questions
Assembly
CSF.Screenplay.Selenium.dll

A question which searches for HTML elements that matche some criteria, optionally within a specified target, returning the results as a SeleniumElementCollection.

public class FindElements : IPerformableWithResult<SeleniumElementCollection>, ICanReport
Inheritance
FindElements
Implements
Inherited Members

Examples

This example gets a SeleniumElementCollection which contains every element in the list which has the ID todo, which also the class low_priority. 

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

readonly ITarget todoList = new CssSelector("ul#todo", "the to-do list");
readonly Locator lowPriority = new ClassName("low_priority", "the low priority items");


// Within the logic of a custom task, deriving from IPerformableWithResult<SeleniumElementCollection>
public async ValueTask<SeleniumElementCollection> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
// ... other performance logic
var elements = await actor.PerformAsync(FindElementsWithin(todoList).WhichMatch(lowPriority), cancellationToken);
// ... other performance logic
return elements;
}

Remarks

Use this question via either of the builder methods FindElementsWithin(Locator), FindElementsWithin(IHasSearchContext) or FindElementsOnThePage(). The first two search within a specified target, the third searches within the whole page <body>. This question returns a collection of elements but that collection could be empty if the search does not find any matching elements. If you are looking for a single element and a 'nothing found' result should raise an exception then consider using the FindElement question instead.

The criteria by which an element is searched by this question is a class that derives from Locator. Particularly useful are the CssSelector, ClassName and XPath locators. ElementId is less likely to be useful, as it should only ever match a single element per web page.

This class is not a complete performable, as it relies upon shared logic to retrieve the SeleniumElement which it queries. It has this in common with a number of Screenplay questions in the Selenium Plugin which observe a single element, those which derive from ISingleElementPerformableWithResult<TResult>. In order for this class to be used as a full-fledged performable, an instance of this type must be wrapped within an instance of SingleElementPerformableWithResultAdapter<TResult>. The adapter class provides the shared boilerplate logic which provides access to the Selenium Element. Note that the builder method(s) which create instances of this type include the 'wrap within an adapter' logic. Normal usage of this performable, when creating it from a builder, does not need to be concerned with this factor.

Constructors

FindElements(IHasSearchContext, string, Locator)

Initializes a new instance of the FindElements class.

public FindElements(IHasSearchContext searchContext, string elementsName = null, Locator locatorBasedMatcher = null)

Parameters

searchContext IHasSearchContext

An object which provides a search context, within which we can find elements

elementsName string

An optional short, descriptive, human-readable name to give to the collection of elements which are found.

locatorBasedMatcher Locator

An optional Locator which should be used to filter the elements which are returned.

FindElements(ITarget, string, Locator)

Initializes a new instance of the FindElements class.

public FindElements(ITarget target, string elementsName = null, Locator locatorBasedMatcher = null)

Parameters

target ITarget

A target which describes an element

elementsName string

An optional short, descriptive, human-readable name to give to the collection of elements which are found.

locatorBasedMatcher Locator

An optional Locator which should be used to filter the elements which are returned.

Methods

GetHumanReadableTypeName() 

public string GetHumanReadableTypeName()

Returns

string

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<SeleniumElementCollection> 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<SeleniumElementCollection>

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

See Also

FindElementsOnThePage()
FindElementsWithin(Locator)
FindElementsWithin(IHasSearchContext)
Edit this page