Creating Tests

Element Query Methods
Writing Tests

The test logic in TestBench tests typically consists of two things:

Find an element (component) to interact with
Interact with an element (component)

For this, TestBench offers the Element and ElementQuery API.

An Element class is a representation of an element on the web page / in the web application. The represented element can be a built-in HTML element such as <div> or <span>, or it can be a custom element such as <vaadin-button> or <vaadin-grid>. An Element class offers methods to interact with the element in the same way that a user of the application could interact with the element. A <vaadin-button> element can for instance be clicked, and you can check what the text on the button says. A <vaadin-grid> element has more complex methods for scrolling, checking the visible contents, headers etc. Low level methods applicable to all elements such as sendKeys() and getSize() are also available when needed.

Tip	`Element` classes are provided for all Vaadin components. If an element class is not availble or some functionality is missing, you can create your own version from scratch or by extending an existing one. See Extending a Page Object.

Tip	An element class is in practice the same as a page object, see Creating a Page Object for more details.

An ElementQuery is what is used to find a given Element (component) on the page so that you can interact with it. The high-level ElementQuery API allows querying Vaadin components in the browser according to their component class type, hierarchy, caption, and other properties. An ElementQuery is constructed using a builder like pattern and in the end returns a single element or a list of matching elements. Further queries can be performed on the returned element(s) to find the desired element.

Consider the following query:

List<ButtonElement> buttons = $(ButtonElement.class).all();

The query returns a list of HTML elements of all the Button components in the UI. The buttons found by the query could be controlled, for example, by clicking them as:

for (ButtonElement button : buttons)
    button.click();

Element Query Methods

The $ method creates an ElementQuery that looks for the given element class. The method is available both for TestBenchTestCase (searches the whole current page) and in TestBenchElement (searches inside the given element).

// Find the button with id="ok"
ButtonElement button = $(ButtonElement.class).id("ok");

// Find the first label inside the layout with id="content"
VerticalLayoutElement layout = $(VerticalLayoutElement.class).id("content");
LabelElement label = layout.$(LabelElement.class).first();

Note	If there is no suitable element class available, you can also use the `$("tag-name")` method to find an element of a given type.

You can use the ElementQuery instance returned by $() to refine the search query using one of the available methods:

id("some-id") Returns the element with the given id
attribute("attributeName", "attributeValue") Adds a filter to only include elements with the given attribute set to the given value
onPage() Redefines the search context to cover the whole page
first() Returns the first matching element
waitForFirst() Returns the first maching element. If no matches are found, keeps waiting until there is a matching element.
last() Returns the last matching element
get(N) Returns the Nth matching element
exists() Returns true if the query matches at least one element
all() Returns a list of all matching elements

Writing Tests

Using Element Queries and Elements you can now compose test methods like:

@Test
public void fillForm() {
    $(TextFieldElement.class).id("firstName").setValue("John");
    $(TextFieldElement.class).id("lastName").setValue("Doe");
    $(ButtonElement.class).id("ok").click();
    Assert.assertEquals("Thank you for submitting the form", $(DivElement.class).id("result"))
}

Do be aware that if you write tests in this manner, you will have a hard time maintaining the tests. A good way to stucture tests is to have only the high level logic in the test itself (your manager should be able to read and understand the test method) and extract the ElementQuery parts to a separate Page Object class. See Creating Maintainble Tests using Page Objects for more information.

F076961F-1A43-451C-B497-91A9C3637A83

Docs