> Markdown version of [Creating Tests](https://vaadin.com/docs/next/flow/testing/end-to-end/creating-tests). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# Creating Tests

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](https://vaadin.com/docs/next/flow/testing/end-to-end/page-objects.md#extending)). An element class is in practice the same as a *page object* (see [Creating a Page Object](https://vaadin.com/docs/next/flow/testing/end-to-end/page-objects.md#creating) 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:

```java
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:

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

## <a id="element-query-methods"></a>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).

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

```java
// 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.

## <a id="writing-tests"></a>Writing Tests

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

**JUnit 4**

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

JUnit 5 support is added in Vaadin 24.

**JUnit 5**

```java
@BrowserTest
public void fillForm() {
    $(TextFieldElement.class).id("firstName").setValue("John");
    $(TextFieldElement.class).id("lastName").setValue("Doe");
    $(ButtonElement.class).id("ok").click();
    Assertions.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](https://vaadin.com/docs/next/flow/testing/end-to-end/page-objects.md) for more information.

`25C2F30D-0C20-4994-B50D-B7C4B5E09FBB`