> Markdown version of [Migrate UI Unit Tests to Browserless Tests](https://vaadin.com/docs/next/building-apps/testing/browserless/migrate-ui-unit-tests). Section index: [llms.txt](https://vaadin.com/docs/next/building-apps/llms.txt)

# Migrate UI Unit Tests to Browserless 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.

## <a id="update-dependencies"></a>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`:

Before (JUnit 4)

```xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-testbench-unit</artifactId>
    <scope>test</scope>
</dependency>
```

Before (JUnit 5)

```xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-testbench-unit-junit5</artifactId>
    <scope>test</scope>
</dependency>
```

After

```xml
<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](https://vaadin.com/docs/next/building-apps/testing/browserless/setup-quarkus.md) for details.

## <a id="keep-junit-4-tests-in-a-separate-module"></a>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.

## <a id="spring-support-moved-to-a-separate-artifact"></a>Spring Support Moved to a Separate Artifact (since V25.2)

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:

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

## <a id="replace-base-classes"></a>Replace Base Classes

Java EE/CDI tests extend the `AbstractCdiViewTest` base class from [the CDI setup](https://vaadin.com/docs/next/building-apps/testing/browserless/setup-cdi.md) 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](https://docs.junit.org/current/user-guide/migrating-from-junit4.html) for details.

## <a id="testbench-end-to-end-coexistence"></a>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`