Docs

Docs

Component Testers

Using built-in testers and building custom ones for your own components.

Component testers simulate user interactions in browserless tests. Each tester wraps a specific component type and provides methods that mirror what a real user can do — clicking, typing, and selecting items.

Testers focus on actions that simulate user behavior, such as setValue(), click(), and selectItem(). To read component state — like getting a value or checking visibility — use the component’s Java API directly. This separation keeps tester methods focused on simulating real user interactions that also perform usability checks.

Using Component Testers

Wrap any component with test() to get a tester for it:

Source code
Java
test(textField).setValue("Jane");
test(button).click();

// Reading state is done via the component API directly
String value = textField.getValue();

The test() method returns a tester matched to the component’s type. You can also request a specific tester type explicitly:

Source code
Java
TextFieldTester tester = test(TextFieldTester.class, textField);

Usability Checks

Before performing any action, testers verify that the component is in a usable state. An action fails with a clear error message if the component is:

  • Not visible

  • Not enabled

  • Not attached to the UI

  • Behind a modal overlay

This catches common issues where a test passes by calling the Java API directly, but the corresponding user action would be impossible in a browser.

Common Testers

The following table shows frequently used testers and their key methods:

Component Key Tester Methods

TextField

setValue(String), clear()

Button

click()

Checkbox

click() (toggles checked state)

ComboBox

selectItem(value), getSuggestionItems()

Grid

getRow(index), size(), getCellText(row, column)

Notification

getText()

Dialog

open(), close()

ConfirmDialog

open(), confirm(), cancel(), reject()

Upload

upload(File), uploadAll(File…​)

Base Methods

All testers inherit from ComponentTester, which provides methods useful across component types:

Method Description

click(), rightClick(), middleClick()

Click the component. All variants accept optional MetaKeys for modifier keys.

isUsable()

Returns true if the component is visible, enabled, and attached. Use this to check state without throwing an exception.

roundTrip()

Simulates a server round-trip, processing any pending client-server communication.

fireDomEvent(String)

Fires a DOM event on the component, such as "blur" or "focus".

find(Class)

Creates a component query scoped to the children of the wrapped component.

Building Custom Testers

When you create custom components, you can build testers for them too. Custom testers extend ComponentTester and use the @Tests annotation to declare which component they test.

Defining a Custom Tester

Source code
Java
// Tests defines the components this tester should be used for automatically
@Tests(PersonFormView.PhoneNumberField.class)
public class PhoneNumberFieldTester extends ComponentTester<PersonFormView.PhoneNumberField> {
    // Other testers can be used inside the custom tester
    final ComboBoxTester<ComboBox<String>, String> combo_;
    final TextFieldTester<TextField, String> number_;

    public PhoneNumberFieldWrap(PersonFormView.PhoneNumberField component) {
        super(component);
        combo_ = new ComboBoxTester<>(
                getComponent().countryCode);
        number_ = new TextFieldTester<>(getComponent().number);
    }

    public List<String> getCountryCodes() {
        return combo_.getSuggestionItems();
    }

    public void setCountryCode(String code) {
        ensureComponentIsUsable();
        if(!getCountryCodes().contains(code)) {
            throw new IllegalArgumentException("Given code isn't available for selection");
        }
        combo_.selectItem(code);
    }

    public void setNumber(String number) {
        ensureComponentIsUsable();
        number_.setValue(number);
    }

    public String getValue() {
        return getComponent().generateModelValue();
    }

}
Source code
PhoneNumberField.java
static class PhoneNumberField extends CustomField<String> {
    ComboBox<String> countryCode = new ComboBox<>();
    TextField number = new TextField();

    // ...
}

Custom testers can use other testers internally, as shown above with ComboBoxTester and TextFieldTester.

Tip
Generic Components
The @Tests annotation also has an fqn attribute that accepts fully qualified class names as strings. Use this when the component type uses generics that prevent it from being passed as a class literal: @Tests(fqn = "com.example.MyField").

Registering Custom Testers

By default, tester implementations are scanned from the com.vaadin.flow.component package, so adding a custom tester to that package makes it immediately available.

To place custom testers in another package, annotate the test class with @ComponentTesterPackages:

Source code
Java
@ComponentTesterPackages("com.example.application.views.personform")
class PersonFormViewTest extends BrowserlessTest {
}

A1B2C3D4-E5F6-7890-ABCD-EF1234567890