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)

NumberField

setValue(double)

Select

selectItem(String), selectItem(int)

ComboBox

selectItem(String), getSuggestionItems()

Grid

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

Notification

getText()

Dialog

open(), close()

ConfirmDialog

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

Upload

upload(File), uploadAll(File…​)
Tip
selectItem Takes String Labels

The selectItem() method on SelectTester and ComboBoxTester takes the display label as a String, not the typed item value. When using enums or other objects, pass the label that the user would see in the dropdown:

Source code
Java
// Enum-backed Select
Select<ExpenseCategory> categorySelect = new Select<>();
categorySelect.setItems(ExpenseCategory.values());
categorySelect.setItemLabelGenerator(ExpenseCategory::getLabel);

// In the test, use the display label, not the enum value
test(categorySelect).selectItem("Meals & Entertainment");

Constraint Enforcement

Testers enforce the same constraints that apply to user input in a browser. If a component has constraints like minimum or maximum values, required fields, or step intervals, the tester rejects values that violate them. This ensures your tests reflect actual user behavior.

For example, a NumberField with a minimum of 0 rejects negative values through the tester:

Source code
Java
NumberField amount = new NumberField("Amount");
amount.setMin(0);
amount.setStep(0.01);

// This throws an exception — the value violates the minimum constraint
test(amount).setValue(-5.0);

To test that your application handles invalid input correctly, set values directly through the component’s Java API instead of the tester:

Source code
Java
// Bypass tester constraints to test validation logic
amount.setValue(-5.0);
// Now verify that your application reacts appropriately

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

Updated –