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 largely the same: the dependency and the base class names change, and two query methods have new names.

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.

Keep JUnit 4 Tests in a Separate Module

If you have existing JUnit 4 tests that extend UIUnit4Test, you don’t have to migrate them immediately, but they can’t share a test classpath with browserless tests. The vaadin-testbench-unit and browserless-test-junit6 artifacts both contain component testers with the same fully qualified class names, such as com.vaadin.flow.component.button.ButtonTester. With both artifacts on the classpath, the testers from the artifact listed first are used, and the tests of the other module fail.

Keep the JUnit 4 tests in a separate Maven module that depends on vaadin-testbench-unit but not on browserless-test-junit6. Write new tests with browserless-test-junit6 and BrowserlessTest in the modules that don’t contain JUnit 4 UI Unit tests.

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

Java EE/CDI tests extend the AbstractCdiViewTest base class from the CDI setup instead of BrowserlessTest.

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), the rest of the test API, including navigate() and test(), is unchanged. The component query methods $() and $view() are now find() and findInView(). The old names still compile, but they’re deprecated for removal, so replace them while migrating.

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.

migration-ui-unit-to-browserless