Docs

Docs

Set Up Browserless Tests with Spring Boot

Set up a Spring Boot project, write a browserless test for a Flow view, and run it from your IDE or Maven.

To start creating browserless tests in an existing Spring Boot project, add the browserless-test-spring dependency with a test scope. Spring Boot’s test starter must also be present — it’s typically already on the classpath in Spring Boot projects.

This guide uses Spring Boot, SpringBrowserlessTest, and the Spring application context. For another application framework, choose its guide in Browserless Testing.

Assuming you’ve imported the Vaadin Bill-of-Materials (BOM) and have a Maven project, add the following:

Source code
XML
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>browserless-test-spring</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

Create a Test

In Spring Boot projects, views typically use dependency injection for services and other components. To handle this correctly, browserless testing provides a specialized base class: SpringBrowserlessTest. Annotate your test class with @SpringBootTest so that the full application context is available.

Given a simple view like this:

Source code
HelloWorldView.java
@Route("")
public class HelloWorldView extends HorizontalLayout {

    TextField name;
    Button sayHello;

    public HelloWorldView() {
        name = new TextField("Your name");
        sayHello = new Button("Say hello");
        sayHello.addClickListener(e -> {
            Notification.show("Hello " + name.getValue());
        });
        add(name, sayHello);
    }
}

A browserless test for it looks like this:

Source code
HelloWorldViewTest.java
@SpringBootTest
class HelloWorldViewTest extends SpringBrowserlessTest {

    @Test
    public void setText_clickButton_notificationIsShown() {
        final HelloWorldView helloView = navigate(HelloWorldView.class);

        test(helloView.name).setValue("Test");
        test(helloView.sayHello).click();

        Notification notification = find(Notification.class).single();
        Assertions.assertEquals("Hello Test", test(notification).getText());
    }

}

Place the test in src/test/java, in the same Java package as the view. The following sections break down what this test does.

The navigate() method opens a view, as a user would navigate to it in the browser. It returns the view instance so you can interact with it directly.

Source code
Java
final HelloWorldView helloView = navigate(HelloWorldView.class);

Using the Java API Directly

Since you’re running on the server side, you have direct access to the Java component API. In the example above, the TextField and Button fields are package-protected. This means the test class can access them directly, as long as it’s in the same Java package — for example, if the view is in src/main/java/com/example/app/, put the test in src/test/java/com/example/app/.

Source code
Java
// Read a component's value directly
String currentValue = helloView.name.getValue();

// Check component state
boolean isEnabled = helloView.sayHello.isEnabled();
boolean isVisible = helloView.name.isVisible();

Simulating User Actions with Testers

To simulate how a user interacts with a component, wrap it with test(). This returns a component-specific tester that provides methods like setValue(), click(), and getText(). Unlike calling the Java API directly, tester methods also verify that the component is in a usable state — visible, enabled, and attached to the UI.

Source code
Java
// Simulate typing into a text field
test(helloView.name).setValue("Test");

// Simulate clicking a button
test(helloView.sayHello).click();

// Read the text a user would see
String text = test(notification).getText();

Each Vaadin component has a tester tailored to its behavior. For example, a CheckboxTester uses click() to toggle checked state, a ComboBoxTester has selectItem(), and a GridTester has getRow(). See Component Testers for supported operations and Test a Custom Component to build your own tester.

Finding Components

Not every component is stored in a view field. For example, the Notification in the test above is created inside a click listener and isn’t referenced anywhere in the view. Use the find() query method to find components in the UI by their type:

Source code
Java
// Find the single Notification currently open
Notification notification = find(Notification.class).single();

The query API supports filtering by properties, predicates, and scoping to specific parts of the component tree. See Querying Components for details.

Running Tests

Testing with SpringBrowserlessTest doesn’t require any particular setup beyond the dependencies above. Run the test directly from your IDE or use Maven, for example by typing mvn test in the terminal.

The test passes when entering a name and clicking the button produces the expected notification.

Next Steps

Use Test User Interactions to cover more complex views. If the test fails, see Debug a Failing Browserless Test. For the environment lifecycle and navigation API, see Test Environment and Lifecycle.

Access Session-Scoped Beans

A Spring test field is injected before the browserless Vaadin session exists. If a test needs an application bean with @VaadinSessionScope or Spring’s @SessionScope, inject an ObjectProvider and resolve the bean after environment setup:

Source code
Java
@SpringBootTest
class CartViewTest extends SpringBrowserlessTest {

    @Autowired
    private ObjectProvider<Cart> cartProvider;

    @Test
    void addItem_cartContainsItem() {
        CartView view = navigate(CartView.class);
        Cart cart = cartProvider.getObject();

        test(view.addButton).click();

        Assertions.assertEquals(1, cart.getItems().size());
    }
}

This example assumes a session-scoped Cart service and a CartView whose addButton adds an item. Import org.springframework.beans.factory.ObjectProvider and org.springframework.beans.factory.annotation.Autowired for the test fields. Resolve the bean in the test method, or in a subclass @BeforeEach method after the inherited environment setup. See Spring Session-Scoped Beans for scope guarantees and other deferred-lookup options.

This is Spring configuration. For CDI session beans, retain the scope activation and bean archive in the Java EE/CDI guide.

7F423DA0-1C41-44BA-B832-55C269FA9311

Updated –