Docs

Docs

Migrate UI Unit Tests to Browserless Tests

Update UI Unit Testing dependencies and base classes, handle Spring support, and migrate existing JUnit tests.

Browserless testing replaces the older UI Unit Testing module. The testing API is the same; only the dependency and base class names have changed.

Update Dependencies

Replace your existing UI Unit Testing dependency with browserless-test-junit6. Depending on your project, the old artifact may be either vaadin-testbench-unit (JUnit 4) or vaadin-testbench-unit-junit5:

Source code
Before (JUnit 4)
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-testbench-unit</artifactId>
    <scope>test</scope>
</dependency>
Source code
Before (JUnit 5)
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-testbench-unit-junit5</artifactId>
    <scope>test</scope>
</dependency>
Source code
After
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>browserless-test-junit6</artifactId>
    <scope>test</scope>
</dependency>

For Quarkus-based projects, also add browserless-test-quarkus. See Set Up Browserless Tests with Quarkus for details.

Spring Support Moved to a Separate Artifact

Spring-specific classes — SpringBrowserlessTest and the Spring mock infrastructure — previously shipped inside the browserless-test and browserless-test-junit6 artifacts. They now live in a dedicated browserless-test-spring artifact, mirroring the Quarkus module, so that non-Spring projects no longer compile against Spring APIs that fail at runtime.

If you’re upgrading a Spring project from an earlier release and your tests extend SpringBrowserlessTest, add the new dependency — the build fails to compile the tests until you do:

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

No code changes are needed; class names and packages are unchanged. Non-Spring projects are unaffected.

Replace Base Classes

Select the base class matching your application framework. Java EE/CDI tests need the custom initialization in the CDI setup; the plain BrowserlessTest replacement alone does not enable CDI.

Rename the test base classes as follows:

Old Class (JUnit 4) Old Class (JUnit 5) New Class

UIUnit4Test

UIUnitTest

BrowserlessTest

SpringUIUnit4Test

SpringUIUnitTest

SpringBrowserlessTest

QuarkusUIUnit4Test

QuarkusUIUnitTest

QuarkusBrowserlessTest

If you’re migrating from JUnit 5 (vaadin-testbench-unit-junit5), no other code changes are needed. The test API — including navigate(), test(), and the component query methods (find() and findInView(), previously $() and $view()) — remains the same.

If you’re migrating from JUnit 4 (vaadin-testbench-unit), you also need to update JUnit annotations and imports (e.g., @Before → @BeforeEach, Assert → Assertions). See the JUnit 5 migration guide for details.

TestBench End-to-End Coexistence

Browserless tests and TestBench end-to-end tests can coexist in the same project. The two modules use separate Java packages, so having both browserless-test-junit6 and vaadin-testbench on the test classpath doesn’t cause conflicts.

Keeping JUnit 4 Tests

If you have existing JUnit 4 tests that extend UIUnit4Test, you don’t have to migrate them immediately. Keep the vaadin-testbench-unit dependency alongside browserless-test-junit6 and add the JUnit Vintage engine so that JUnit 5 can run JUnit 4 tests:

Source code
XML
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <scope>test</scope>
</dependency>

New tests should use browserless-test-junit6 with BrowserlessTest.

migration-ui-unit-to-browserless

Updated –