Docs

Docs

Creating Tests

How to create tests using TestBench.

The test logic in TestBench tests consist typically of two things: find an element or component with which to interact; and interact with an element or component.

For this, TestBench offers the Element and ElementQuery API.

An Element class is a representation of an element on the web page or 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 isn’t available or some functionality is missing, you can create your own version from the beginning or by extending an existing one (see Extending a Page Object). An element class is in practice the same as a page object (see Creating a Page Object for more details).

An ElementQuery is what’s 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 returns a single element or a list of matching elements.

Further queries can be performed on the returned elements to find the desired element. Related to this, consider the following query:

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

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

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

Element Query Methods

The $() method creates an ElementQuery that looks for the given element class. This method is available both for TestBenchTestCase (i.e., searches the whole current page) and in TestBenchElement (i.e., 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 include only 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 matching element — if no matches are found, it 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; and

  • all() Returns a list of all matching elements.

Writing Tests

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

@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"))
}

Be aware that if you write tests in this manner, you can have difficulty maintaining the tests. A good way to structure 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 Maintainable Tests using Page Objects for more information.

25C2F30D-0C20-4994-B50D-B7C4B5E09FBB