Browserless Testing
- Application, Users, and Windows
- Choose Your Framework
- Use the Examples with Your Framework
- Base Classes
- Guides
Browserless tests exercise Flow views and components in the test JVM, without a browser or a servlet container. A test creates an application context, opens a window for a simulated user, and drives the UI through that window. Choose the setup that matches your application’s dependency injection framework before writing a test.
Application, Users, and Windows
A browserless test models the application the way its users see it:
-
The application context plays the role of the deployed application. A test creates it and closes it when the test ends, or, in Spring Boot, a test configuration defines it once as a bean that the tests share.
-
A user, created with
newUser(), has its own Vaadin session and, in a secured application, its own credentials. -
A window, created with
newWindow(), is one browser window of that user. It opens the root route, and the test navigates, finds components, and simulates user actions through it.
Most tests need one user with one window. The same API covers several users and windows when the behavior under test depends on them.
Choose Your Framework
Application | Setup Guide | Application Context |
Spring Boot |
| |
Plain Java without a dependency injection container |
| |
Quarkus |
| |
Java EE / Jakarta EE with Vaadin CDI | None. Tests extend |
Quarkus has its own integration, even though it also uses CDI.
The Java EE/CDI guide uses the jakarta.* packages that current Vaadin versions require.
Use the Examples with Your Framework
The window methods that tests use to interact with the UI, such as navigate(), findButton(), and test(), work the same in every setup.
Only the code that creates the application context differs.
Most examples in the other guides use the plain Java setup, with a window field that a @BeforeEach method creates, as in the plain Java setup guide.
To use an example with another framework, keep the test methods, and create the application context as your framework’s setup guide does:
-
Spring Boot: annotate the class with
@SpringBootTest, and autowire theBrowserlessApplicationContextbean that the setup guide defines, instead of creating the context in the@BeforeEachmethod. Close the window’s user in the@AfterEachmethod instead of closing the context. Spring beans and Spring test configuration apply. -
Quarkus: annotate the class with
@QuarkusTest, and create the context withQuarkusBrowserlessApplicationContext.create(). Quarkus test profiles apply. -
Java EE/CDI: extend
AbstractCdiViewTest, add the tested view and its beans to its Weld archive, and register the view’s route in its setup method. Call the window methods on the test itself, for examplenavigate(…)instead ofwindow.navigate(…).
Base Classes
Tests can also extend a base class — BrowserlessTest, SpringBrowserlessTest, or QuarkusBrowserlessTest — that creates the Vaadin environment with one user and one window before each test method, and closes it afterwards.
The test then calls the window methods on itself, so window.navigate(…) becomes navigate(…); for the locator methods, such as findButton(), the test class also implements Locators.
Each setup guide also shows the base-class form of its test.
Use an application context for new tests.
A base class supports only one user and one window, and the test configures it with annotations, such as @ViewPackages, instead of in the code that creates the context.
Spring Security and Quarkus test annotations, such as @WithMockUser and @TestSecurity, apply to a base-class test; a secured application context takes the credentials of each user from newUser() instead.
Guides
- 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.
- Set Up Browserless Tests in Plain Java
- Configure browserless tests in a plain Java project with an application context, a base class, or a JUnit extension.
- Set Up Browserless Tests with Quarkus
- Configure Quarkus browserless tests, create a test class, and substitute services using test profiles.
- Set Up Browserless Tests with Java EE/CDI
- Use Weld and Vaadin CDI to inject dependencies into browserless view tests, select test alternatives, and manage the test lifecycle.
- Test User Interactions
- Learn how a browserless test works, then fill in forms, select Grid rows, confirm dialogs, and test navigation, shortcuts, and menus.
- Write Tests as User Stories
- Structure browserless tests as readable use cases, with actors for the users and page objects for the views.
- Debug a Failing Browserless Test
- Read the component tree of a failing browserless test, enable failure snapshots, and fix the test.
- Test View Access Control
- Verify anonymous, authorized, and unauthorized navigation in Spring and Quarkus browserless tests.
- Test a Custom Component
- Test a component without a route, add a component tester or locator, set values as a user would, and design gestures for testing.
- Test Signal-Based Views
- Assert changes to signal bindings, process background updates, and verify shared-signal write confirmation.
- Test Multiple Users and Windows
- Verify shared state, independent windows, and authentication isolation across several browserless user sessions.
- Configure a Browserless Test
- Set Vaadin properties and feature flags for individual browserless tests while retaining the correct framework setup.
- Speed Up Browserless Tests
- Reduce scanning and Spring context startup costs, and evaluate shared test environments without losing test isolation.
- Migrate UI Unit Tests to Browserless Tests
- Update UI Unit Testing dependencies and base classes, handle Spring support, and migrate existing JUnit tests.
E6858195-4B1D-43C8-8688-502531C6AC16