Table of Contents

Class FindElement

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

A question which searches for an HTML element that matches some criteria, optionally within a specified target, returning the element it finds as a SeleniumElement.

public class FindElement : ISingleElementPerformableWithResult<SeleniumElement>, ICanReportForElement
Inheritance
FindElement
Implements
Inherited Members

Examples

This example gets a SeleniumElement within the list which has the ID todo which has the class urgent. 

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

readonly ITarget todoList = new CssSelector("ul#todo", "the to-do list");
readonly Locator urgent = new ClassName("urgent", "the urgent item");

// Within the logic of a custom task, deriving from IPerformableWithResult<SeleniumElement>
public async ValueTask<SeleniumElement> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    // ... other performance logic
    var element = await actor.PerformAsync(FindAnElementWithin(todoList).WhichMatches(urgent), cancellationToken);
    // ... other performance logic
    return element;
}

Remarks

Use this question via either of the builder methods FindAnElementWithin(ITarget) or FindAnElementOnThePage(). The first searches within a specified target, the second searches within the whole page <body>. This question will only ever return a single SeleniumElement, or it will raise an exception if the search does not find any matching elements. If multiple elements are found which match the criteria then this question will return only the first. If you are expecting to find multiple elements, then consider using the FindElements 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

FindElement(string, Locator)

Initializes a new instance of the FindElement class.

public FindElement(string elementsName = null, Locator locatorBasedMatcher = null)

Parameters

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

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

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

See Also

FindAnElementOnThePage()
FindAnElementWithin(ITarget)
Edit this page