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

Remove your existing UI Unit Testing dependency. 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>

Then add the browserless artifact for your application framework. The Vaadin BOM manages their versions.

Application Browserless Artifacts

Spring Boot

browserless-test-spring

Quarkus

browserless-test-junit6 and browserless-test-quarkus

Plain Java, or Java EE/CDI

browserless-test-junit6

For example, a Spring Boot project replaces the old dependency with this one:

Source code
After (Spring Boot)
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>browserless-test-spring</artifactId>
    <scope>test</scope>
</dependency>

Other projects use browserless-test-junit6:

Source code
After (Plain Java, Java EE/CDI, or Quarkus)
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>browserless-test-junit6</artifactId>
    <scope>test</scope>
</dependency>

Quarkus projects also add browserless-test-quarkus. See the setup guide for your framework, such as Spring Boot or Quarkus, for the other test dependencies it needs.

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 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.

This section applies if you’re upgrading a Spring project from an earlier browserless testing release, which used browserless-test-junit6 for Spring tests. If you’re migrating from UI Unit Testing, you already added browserless-test-spring as described in Update Dependencies.

If 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.

Renaming the base class is the quickest way to migrate existing tests. Write new tests with an application context instead, as the setup guides show; see Base Classes for the differences.

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