Class QuestionQueryBuilder

Namespace

CSF.Screenplay.Selenium.Builders

Assembly

CSF.Screenplay.Selenium.dll

Provides methods to build performable questions for a Selenium element, which are based upon querying/interrogating values from that element.

public class QuestionQueryBuilder

Inheritance

object

QuestionQueryBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

All the usages of SingleElementQuery<TResult> or ElementCollectionQuery<TResult> follow the same pattern, as demonstrated below. This example reads the background-color from a list item.

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

readonly ITarget warningItem = new CssSelector("li.warning", "the warning item");

// Within the logic of a custom task, deriving from IPerformableWithResult<string>
public async ValueTask<string> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    // ... other performance logic
    var bgColor = await actor.PerformAsync(ReadFromTheElement(warningItem).TheCssProperty("background-color"), cancellationToken);
    // ... other performance logic
    return bgColor;
}

Remarks

This class is used with the Screenplay questions SingleElementQuery<TResult> and/or ElementCollectionQuery<TResult>. The builder methods for these questions, ReadFromTheElement(ITarget) and ReadFromTheCollectionOfElements(ITarget) respectively, return an instance of this builder type. From this type, the developer should select what it is that they wish to read from the element(s).

For more information about queries and their usage, see Queries.

Constructors

QuestionQueryBuilder(ITarget)

Initializes a new instance of the QuestionQueryBuilder class with the specified Selenium element.

public QuestionQueryBuilder(ITarget target)

Parameters

target ITarget

The Selenium element to be used by the query builder.

Methods

AllOptions()

Gets a performable question which reads all of the available options (whether selected or not) from a <select> element.

public IPerformableWithResult<IReadOnlyList<Option>> AllOptions()

Returns

IPerformableWithResult<IReadOnlyList<Option>>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

This question is only valid for <select> elements. For any other type of element, the behaviour is undefined.

SelectedOptions()

Gets a performable question which reads the selected options from a <select> element.

public IPerformableWithResult<IReadOnlyList<Option>> SelectedOptions()

Returns

IPerformableWithResult<IReadOnlyList<Option>>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

This question is only valid for <select> elements. For any other type of element, the behaviour is undefined.

TheAttribute(string)

Gets a performable question which reads the value of the specified attribute from the element.

public IPerformableWithResult<string> TheAttribute(string attributeName)

Parameters

attributeName string

The name of the attribute from which to read the value

Returns

IPerformableWithResult<string>

A performable question

Examples

This example shows how to use the SingleElementQuery<TResult> question to read the title attribute from a button.

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

readonly ITarget cancelButton = new CssSelector("button.cancel", "the cancel button");

// Within the logic of a custom task, deriving from IPerformableWithResult<string>
public async ValueTask<string> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    // ... other performance logic
    var title = await actor.PerformAsync(ReadFromTheElement(cancelButton).TheAttribute("title"), cancellationToken);
    // ... other performance logic
    return title;
}

TheClickability()

Gets a performable question which checks the clickability of the element.

public IPerformableWithResult<bool> TheClickability()

Returns

IPerformableWithResult<bool>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

An element is considered 'clickable' if it is both visible in the web browser and it is not disabled.

TheCssProperty(string)

Gets a performable question which reads the value of the specified CSS property from the element.

public IPerformableWithResult<string> TheCssProperty(string propertyName)

Parameters

propertyName string

The name of the CSS property from which to read the value

Returns

IPerformableWithResult<string>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

Note that this is not limited to reading the styling of an element/elements as it was defined in a stylesheet. It reads the live styling of the element as it is when the question executes. Thus, if JavaScript or a class change has altered the styling of the element since it was first rendered on-screen, its up-to-date styling information will be returned by this query.

TheLocation()

Gets a performable question which reads the pixel location (top-left corner) of the element.

public IPerformableWithResult<Point> TheLocation()

Returns

IPerformableWithResult<Point>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

TheSize()

Gets a performable question which reads the pixel size (width and height) of the element.

public IPerformableWithResult<Size> TheSize()

Returns

IPerformableWithResult<Size>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

TheText()

Gets a performable question which reads the text content of the element.

public IPerformableWithResult<string> TheText()

Returns

IPerformableWithResult<string>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

When reading text from the web browser, this query will trim leading/trailing whitespace. This is because some browsers (Safari) include whitespace at the beginning/end of text read from the browser, which isn't visible to the end user. This is typically the space which is inherent in the markup, but which browsers ignore when actually displaying content.

Trimming it by default ensures that Screenplay reproduces functionality reliably cross-browser. If this causes an issue and you would like the leading/trailing whitespace included then use TheTextWithoutTrimmingWhitespace() instead.

TheTextWithoutTrimmingWhitespace()

Gets a performable question which reads the text content of the element, preserving leading/trailing whitespace if present.

public IPerformableWithResult<string> TheTextWithoutTrimmingWhitespace()

Returns

IPerformableWithResult<string>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

Unlike TheText(), this method will not trim any leading/trailing whitespace. Be aware that some browsers (Safari) may include leading/trailing whitespace when reading text, which other WebDriver implementations do not. This can result in inconsistent results when operating cross-browser. If cross-browser consistency is important then consider using TheText() instead.

TheValue()

Gets a performable question which reads the value of the element.

public IPerformableWithResult<string> TheValue()

Returns

IPerformableWithResult<string>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

This query is only meaningful for elements which may have a value. Examples of these include <input>, <textarea> or <select> elements.

TheVisibility()

Gets a performable question which checks the visibility of the element.

public IPerformableWithResult<bool> TheVisibility()

Returns

IPerformableWithResult<bool>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

UnselectedOptions()

Gets a performable question which reads the unselected options from a <select> element.

public IPerformableWithResult<IReadOnlyList<Option>> UnselectedOptions()

Returns

IPerformableWithResult<IReadOnlyList<Option>>

A performable question

Examples

See the class QuestionQueryBuilder for an example; all the methods to this class follow the same pattern.

Remarks

This question is only valid for <select> elements. For any other type of element, the behaviour is undefined.

See Also

SingleElementQuery<TResult>

ElementCollectionQuery<TResult>