Docs

Docs

Querying Components in Browserless Tests

Details and examples on accessing components within a browserless test.

The BrowserlessTest base class can get the instantiated view, but child components may not always be directly accessible. For example, components may be stored in private fields or may not be referenced at all in the view class.

To overcome this limitation, BrowserlessTest provides a component query functionality that lets you search the component tree for the components you need to interact with in test methods.

Component Queries

You can get a ComponentQuery object by calling the $() method, specifying the type of the component you are searching for.

Once the query is ready with all conditions configured, use a terminal operator to retrieve the components that it found. Examples of terminal operators are single(), last(), atIndex(), all(), and id().

Source code
Java
// Get the TextField
TextField nameField = $(TextField.class).single();

Scoping Queries

You can also restrict search scope to the children of the current view by using the $view() method, or even to another component by using $(MyComponent.class, rootComponent).

Source code
Java
// Get the TextField in the current view
TextField nameField = $view(TextField.class).single();

// Get the TextField nested in a container
TextField nameField = $(TextField.class, view.formLayout).single();

The query object has many filtering methods that can be used to refine the search.

Source code
Java
// Get the TextField with the given label
TextField nameField = $view(TextField.class)
        .withPropertyValue(TextField::getLabel, "First name")
        .single();

// Get all TextFields in the view that satisfy the conditions
Predicate<TextField> fieldHasNotValue = field -> field.getOptionalValue().isEmpty();
Predicate<TextField> fieldIsInvalid = TextField::isInvalid;
List<TextField> textField = $view(TextField.class)
        .withCondition(fieldHasNotValue.or(fieldIsInvalid))
        .all();

Filtering Methods

The following table lists all available filter methods, grouped by category:

Method Description

Text & Caption

withText(String)

Matches components whose text content equals the given string exactly.

withTextContaining(String)

Matches components whose text content contains the given substring.

withCaption(String)

Matches components whose caption equals the given string exactly.

withCaptionContaining(String)

Matches components whose caption contains the given substring.

CSS Classes & Themes

withClassName(String…​)

Matches components that have all of the given CSS class names.

withoutClassName(String…​)

Excludes components that have any of the given CSS class names.

withTheme(String)

Matches components whose theme attribute contains the given value.

withoutTheme(String)

Excludes components whose theme attribute contains the given value.

Attributes

withAttribute(String)

Matches components that have the given attribute, regardless of value.

withAttribute(String, String)

Matches components that have the given attribute with the specified value.

withoutAttribute(String)

Excludes components that have the given attribute.

Value & Properties

withValue(V)

Matches HasValue components whose current value equals the given value.

withPropertyValue(Function, V)

Matches components where the given getter returns the expected value.

withCondition(Predicate)

Matches components that satisfy a custom predicate.

Identity

withId(String)

Matches the component with the given id.

Here are a few examples:

Source code
Java
// Find a button by its text
Button save = $(Button.class).withText("Save").single();

// Find a TextField by CSS class
TextField styled = $(TextField.class).withClassName("highlighted").single();

// Find checkboxes with a specific value
Checkbox checked = $(Checkbox.class).withValue(true).single();

Checking Existence

Use exists() to check whether a query has results without throwing an exception when none are found:

Source code
Java
if ($(Notification.class).exists()) {
    // A notification is open
}

Result Count Assertions

You can assert the number of results directly in the query chain:

Source code
Java
// Expect exactly 3 text fields
List<TextField> fields = $(TextField.class).withResultsSize(3).all();

// Expect between 1 and 5 results
List<Button> buttons = $(Button.class).withResultsSize(1, 5).all();

// Expect at least 1 result
List<Grid> grids = $(Grid.class).withMinResults(1).all();

Chaining Queries

You may sometimes need to do a query for components nested inside the UI, in a hierarchy composed of many different types of components. To simplify such situations, the query object offers methods to chain a new query starting with a found component, so that a complex query can be created in a fluent way. The thenOn() method and its variants, for example thenOnFirst(), provide you with a new query object for the given component type, setting the search scope to the component selected from the current query.

Source code
Chained Query Example
// Search for all 'VerticalLayout's in the view
TextField textField = $view(VerticalLayout.class)
        // take the second one and start searching for 'TextField's
        .thenOn(2, TextField.class)
        // filter for disabled 'TextField's
        .withCondition(tf -> !tf.isEnabled())
        // and get the last one
        .last();

DDC7D136-1A56-44FC-B256-C15DB7645EDC