Class FilterElements

Namespace

CSF.Screenplay.Selenium.Questions

Assembly

CSF.Screenplay.Selenium.dll

A question which filters a collection of elements by specified criteria, getting a new collection which contains only those which match.

public class FilterElements : IPerformableWithResult<SeleniumElementCollection>, ICanReport

Inheritance

object

FilterElements

Implements

IPerformableWithResult<SeleniumElementCollection>

ICanReport

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

This example filters a collection of items in a todo list, only for those with red background colors.

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

readonly ITarget todoListItems = new CssSelector("ul#todo li", "the to-do list items");

// Within the logic of a custom task, deriving from IPerformableWithResult<SeleniumElementCollection>
public async ValueTask<SeleniumElementCollection> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    var elements = await actor.PerformAsync(FindElementsOnThePage().WhichMatch(todoListItems), cancellationToken);
    var redElements = await actor.PerformAsync(Filter(elements)
                                                .ForThoseWhich(q => q.CssProperty("background-color",
                                                                                  x => x == Colors.RED)),
                                               cancellationToken);
    return redElements;
}

Remarks

Use this question via the builder method Filter(SeleniumElementCollection). The builder will then guide you through specifying the criteria by which you wish to filter those elements. There are two primary routes by which to do this, which depend upon which overload of ForThoseWhich you choose.

You may specify the criteria within a Specification class. That is a class which implements ISpecificationFunction<SeleniumElement>, from the CSF.Specifications package. This allows you to pass just a variable into the builder, containing an instance of that specification. This is the recommended technique, as the specification class becomes a reusable and first-class named part of the Screenplay. When using this technique, use the ForThoseWhich(ISpecificationFunction<SeleniumElement>) overload.

Alternatively, you may specify the criteria ad-hoc within the filter-elements builder. To use this technique, use the ForThoseWhich(Func<QueryPredicatePrototypeBuilder, IBuildsElementPredicates>) overload. You must specify a function which interrogates one or more aspects of the element, specifying each criterion individually. This approach allows fast specification of criteria, but at the cost of reusability.

Note that this question is evaluated with an already-in-memory collection of SeleniumElement. However, each criterion that is evaluated may cause communication with the WebDriver, for each element in the source collection. This nested loop could lead to unexpected impacts upon performance, particularly with larger collections of elements or where the WebDriver is hosted remotely. If you are able to find the elements you want using an implementation of Locator, then prefer using FindElements instead. Finding elements performs far better than this question. On the other hand, this question offers far greater power in the creation of custom criteria.

Constructors

FilterElements(IReadOnlyCollection<SeleniumElement>, ISpecificationFunction<SeleniumElement>, string)

Initializes a new instance of the FilterElements class.

public FilterElements(IReadOnlyCollection<SeleniumElement> elements, ISpecificationFunction<SeleniumElement> specification, string resultsName = null)

Parameters

elements IReadOnlyCollection<SeleniumElement>

The collection of elements to be filtered.

specification ISpecificationFunction<SeleniumElement>

The specification function to filter the elements.

resultsName string

An optional short, descriptive, human-readable name which summarizes the elements matched by the filter.

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

Filter(SeleniumElementCollection)