Docs

Docs

Configure a Browserless Test

Set Vaadin properties and feature flags for individual browserless tests while retaining the correct framework setup.

Use this guide after setting up a plain Java, Spring Boot, Quarkus, or Java EE/CDI test. An application context takes its Vaadin configuration from the code that creates it. Tests that extend a base class, including the AbstractCdiViewTest base class of the Java EE/CDI setup, declare it with an annotation instead.

Configure the Application Context

Pass a configurer to create() to enable a feature and set a Vaadin deployment property, together with the view packages to scan. For the plain Java setup:

Source code
ResponsiveFormLayoutTest.java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import com.vaadin.browserless.BrowserlessApplicationContext;
import com.vaadin.browserless.BrowserlessUIContext;
import com.vaadin.experimental.FeatureFlags;
import com.vaadin.flow.server.VaadinService;

class ResponsiveFormLayoutTest {

    private BrowserlessApplicationContext app;
    private BrowserlessUIContext window;

    @BeforeEach
    void setUp() {
        app = BrowserlessApplicationContext.create(builder -> builder
                .withViewPackages(ResponsiveFormView.class)
                .withApplicationProperty(
                        "devmode.sessionSerialization.enabled", "true")
                .withFeatureFlags("defaultAutoResponsiveFormLayout"));
        window = app.newUser().newWindow();
    }

    @AfterEach
    void tearDown() {
        app.close();
    }

    @Test
    void featureIsEnabled() {
        FeatureFlags flags = FeatureFlags.get(
                VaadinService.getCurrent().getContext());
        Assertions.assertTrue(
                flags.isEnabled("defaultAutoResponsiveFormLayout"));
    }
}

ResponsiveFormView stands for the view whose behavior depends on the setting. The Spring and Quarkus factories take the same configurer: SpringBrowserlessApplicationContext.create(applicationContext, builder → …​) and QuarkusBrowserlessApplicationContext.create(builder → …​). In Spring Boot, put the settings that every test needs in the configurer of the shared bean. A test class that needs different settings creates an application context of its own for each test, as described in Create an Application Context for Each Test. Choose an identifier from Feature Flags; an unknown identifier fails instead of silently enabling a new feature. The example checks the flag itself; in your tests, assert the application behavior that the setting changes. The settings are local to the application context, so the test doesn’t need to edit a feature-flags file or reset system properties afterwards.

Use a Different Setting in One Test

To test the same view with the feature disabled, the test needs an application context with a different configuration. Put such tests in a test class of their own, or create the application context in each test method with try-with-resources, instead of in a @BeforeEach method:

Source code
Java
@Test
void featureIsDisabled() {
    try (var app = BrowserlessApplicationContext.create(builder -> builder
            .withViewPackages(ResponsiveFormView.class)
            .withFeatureFlag("defaultAutoResponsiveFormLayout", false))) {
        var window = app.newUser().newWindow();
        window.navigate(ResponsiveFormView.class);

        FeatureFlags flags = FeatureFlags.get(
                VaadinService.getCurrent().getContext());
        Assertions.assertFalse(
                flags.isEnabled("defaultAutoResponsiveFormLayout"));
    }
}

The window stays active after it opens and after each window method, so static Vaadin APIs such as VaadinService.getCurrent() return its state.

Override a Spring-Defined Property

In a Spring Boot test, a Vaadin property already defined in the Spring environment takes precedence over the configuration of the application context. Use Spring’s @TestPropertySource on that test class to change it:

Source code
Java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.TestPropertySource;
import com.vaadin.browserless.BrowserlessApplicationContext;
import com.vaadin.browserless.BrowserlessUIContext;
import com.vaadin.flow.server.VaadinService;
import com.vaadin.flow.server.startup.ApplicationConfiguration;

@SpringBootTest
@TestPropertySource(properties =
        "vaadin.devmode.sessionSerialization.enabled=true")
class SessionSerializationTest {

    @Autowired
    private BrowserlessApplicationContext app;

    private BrowserlessUIContext window;

    @BeforeEach
    void openWindow() {
        window = app.newUser().newWindow();
    }

    @AfterEach
    void closeUser() {
        window.getUser().close();
    }

    @Test
    void sessionSerializationIsEnabled() {
        Assertions.assertTrue(ApplicationConfiguration
                .get(VaadinService.getCurrent().getContext())
                .isDevModeSessionSerializationEnabled());
    }
}

@TestPropertySource gives the test class a Spring application context of its own, and with it a shared browserless application context of its own, which applies the property.

Configure a Base Class or an Extension

A test that extends a base class declares the configuration with the @BrowserlessTestConfig annotation on the test class:

Source code
Java
@BrowserlessTestConfig(
        applicationProperties = "devmode.sessionSerialization.enabled=true",
        featureFlags = "defaultAutoResponsiveFormLayout")
class ResponsiveFormLayoutTest extends BrowserlessTest {
    // Test methods call navigate(), find(), and test() on the test itself.
}

The annotation works with every base class: BrowserlessTest, SpringBrowserlessTest, QuarkusBrowserlessTest, and AbstractCdiViewTest. To change a setting for one test method, annotate that method, for example with @BrowserlessTestConfig(featureFlags = "defaultAutoResponsiveFormLayout=false"). The method-level value replaces the class-level value of that flag; the class-level application property still applies. See Configuration Merging for inheritance and precedence rules.

For a plain Java JUnit extension, configure the instance that creates the environment:

Source code
Java
@RegisterExtension
BrowserlessExtension extension = new BrowserlessExtension()
        .withFeatureFlags("defaultAutoResponsiveFormLayout");

BrowserlessClassExtension shares one environment across the test class, so it rejects method-level configuration.

An application context doesn’t read @BrowserlessTestConfig. To reuse a configuration that a test class declares with the annotation, pass it to the builder with withConfiguration(BrowserlessConfiguration.from(getClass())). See Programmatic Configuration for importing a configuration, registering Lookup services, and combining programmatic settings with annotations.

C941CDE1-ACC5-47F3-82D9-90A3D1D0C1FC