Docs

Docs

Test Environment and Lifecycle

Browserless application contexts and base classes, environment lifecycle, route scanning, navigation, and simulated server round trips.

Browserless tests create the Vaadin service, session, and UI in the test JVM. An application context exists from its creation until it’s closed, so the test decides whether it lives for one test method, for a test class, or, as a Spring bean, for every test that shares the Spring application context. The base classes and the JUnit extensions initialize a new environment before each test method, or each test class, and tear it down afterwards. Custom setup, such as CDI integration, replaces the base-class initialization while retaining the JUnit lifecycle hooks. JUnit’s @TestInstance(PER_CLASS) changes the test-instance lifecycle; it does not share the Vaadin environment of a base class.

Entry Points and Framework Integration

The application context API is the main entry point. It creates any number of users and windows, and each window provides the testing methods described on these pages:

Application Context Factory

Integration

BrowserlessApplicationContext

Plain Java, provided by browserless-test-junit6.

SpringBrowserlessApplicationContext

Spring application context and dependency injection, provided by browserless-test-spring.

QuarkusBrowserlessApplicationContext

Quarkus test framework and dependency injection, provided by browserless-test-quarkus.

A base class creates one user with one window per test method, and provides the same testing methods on the test class itself:

Base Class

Integration

BrowserlessTest

Plain Java, provided by browserless-test-junit6.

An application-owned CDI subclass of BrowserlessTest

Weld and CdiVaadinServlet; see CDI Test Integration. The application context API does not apply this setup.

SpringBrowserlessTest

Spring application context and dependency injection, provided by browserless-test-spring.

QuarkusBrowserlessTest

Quarkus test framework and dependency injection, provided by browserless-test-quarkus.

The JUnit extensions provide the same single-window lifecycle for plain Java tests without inheritance.

Route Scanning

Browserless tests scan the classpath for routes and error views. An application context scans the packages passed to create() or to the builder’s withViewPackages(), and their sub-packages.

Base classes and extensions scan the whole classpath by default. @ViewPackages(classes = MyView.class) restricts scanning to the packages of the supplied classes and their sub-packages. @ViewPackages(packages = "com.example.views") accepts package names instead. Both attributes may be combined. An empty @ViewPackages restricts scanning to the test class’s package and its sub-packages.

In Spring tests, @SpringBootTest loads the full Spring application context; @SpringJUnitConfig or @ContextConfiguration selects a narrower configuration. See Spring Security Integration for access-control initialization when using a reduced context.

A new window, like the default base-class setup, opens the root view. The custom CDI setup registers routes after initialization and navigates explicitly in the test.

To navigate to another registered view, use the navigate() methods of the window, or of the base class or extension:

  • For a normal view with only a path defined

    navigate(MyView.class)

    navigate("myView", MyView.class)

  • For a view with HasUrlParameter

    navigate(MyParam.class, "parameter")

    navigate("myParam/parameter", MyParam.class)

  • For a view with URL template @Route("template/:param")

    navigate(Template.class, Collections.singletonMap("param", PARAMETER))

    navigate("template/myParam", Template.class)

  • For a location that carries a query string, a fragment, or both

    navigate("myParam/parameter?tab=history&page=2", MyParam.class)

    The location is split up the same way the browser address bar does it, so the query parameters reach the view through the navigation event. A location consisting only of a fragment, such as "#details", identifies a place within the current page rather than a route, so it leaves the current view in place.

All navigation methods return the instantiated view, so that its fields can be used directly for testing.

Note
 Navigation by location string takes in the view class, so that the initialized view can be automatically validated to be the expected one.

You can also retrieve the current view at any time with getCurrentView():

Source code
Java
HasElement view = window.getCurrentView();

Simulating Keyboard Shortcuts

Use fireShortcut() to simulate keyboard shortcuts registered with Vaadin’s shortcut API:

Source code
Java
// Simulate pressing Enter
window.fireShortcut(Key.ENTER);

// Simulate Ctrl+S
window.fireShortcut(Key.KEY_S, KeyModifier.CONTROL);

Components That Don’t Exist Yet

Queries traverse the server-side component tree. Per-item renderer components may not exist until rendering is requested, and closed overlay content is detached. See Components a Query Cannot Find for renderer and overlay semantics.

Server Round Trips

roundTrip() processes pending client-server communication in the simulated environment. It does not start a browser or execute client-side JavaScript. Signal task processing is described separately in Signal Test Environment.

For worked examples, choose your framework in Browserless Testing.

Framework-Specific Timing and Configuration

See Spring Test Lifecycle for Spring injection, session-scoped beans, and authentication timing. See CDI Test Integration for the custom Weld lifecycle. For standard per-test properties, feature flags, and Lookup services, see Test Configuration and the configuration guide.

0262B190-4113-4A35-BD70-F727FB2F2AD5