Docs

Docs

Migrating from UI Unit Testing

Steps for migrating existing tests from the old UI Unit Testing module to the new Browserless Testing module.

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 Browserless Testing in Quarkus-based Projects for details.

Replace Base Classes

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 $() query methods — 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 package namespaces, 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