> Markdown version of [Getting Started](https://vaadin.com/docs/next/flow/testing/end-to-end/getting-started). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# Getting Started with End-to-End Testing

It’s easy to get started with end-to-end testing with Vaadin. If you want to test TestBench and see how tests are run, the easiest way is to clone the example project at <https://github.com/vaadin/testbench-demo>. The tests are automatically executed on your local Chrome when you run `mvn verify`.

## <a id="setting-up-your-project"></a>Setting Up Your Project

To start using TestBench in an existing project, you need to add the TestBench dependency (`com.vaadin`/`vaadin-testbench`) with a `test` scope. Assuming you have imported the Vaadin Bill-of-Materials (BOM) and have a Maven project, all you need to do is add the following:

**JUnit 4**

```xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-testbench</artifactId>
    <scope>test</scope>
</dependency>
<!-- Required for Vaadin 25+ with Spring Boot 4 (JUnit 6) -->
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <scope>test</scope>
</dependency>
```

**JUnit 5/6 (JUnit 6 since Vaadin 25.0)**

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

> **Note:** Starting with Vaadin 25 and Spring Boot 4, the default test framework is JUnit 6 (JUnit Platform). JUnit 6 maintains API compatibility with JUnit 5, so `vaadin-testbench-junit5` and `vaadin-testbench-junit6` work with both, but have transitive JUnit dependencies aligned with the respective versions.
>
> For JUnit 4 tests using `TestBenchTestCase`, the `junit-vintage-engine` dependency is required because JUnit 6 doesn’t natively execute JUnit 4 tests. Without it, tests won’t be detected or executed.

The `test` scope and version number are predefined by the Vaadin BOM.

To be able to run tests locally, you might need to install a WebDriver for your browser. See [Installing WebDrivers](https://vaadin.com/docs/next/flow/testing/end-to-end/installing-webdrivers.md) for more details.

## <a id="creating-a-simple-test"></a>Creating a Simple Test

There are a few fundamental parts of any TestBench test. Below are the steps to follow:

- Create an instance of the browser driver for the browser you want to use. By default, TestBench uses Chrome browser driver.

- Open the URL containing the application you want to test.

- Perform test logic and assert that the result was the expected one.

- Close the driver instance to close the browser.

The following test example performs all of the above tasks with the test logic consisting of clicking the first available button and checking that the text of the button changes when clicked. If you’re adding this test to your own custom application, it fails unless you modify it.

In the Maven world, all test classes are located in the `src/test/java` directory. Create a new class called `SimpleIT` in that directory. Incidentally, `IT` stands for **integration test** and Maven automatically runs all `*IT` classes. Below is an example of how to create this class:

**JUnit 4**

```java
import org.junit.After;
import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;

public class SimpleIT extends TestBenchTestCase {

    @Before
    public void setup() throws Exception {
        // Create a new browser instance
        setDriver(new ChromeDriver());
        // Open the application
        getDriver().get("http://localhost:8080/");
    }

    @Test
    public void clickButton() {
        // Find the first button (<vaadin-button>) on the page
        ButtonElement button = $(ButtonElement.class).first();

        // Click it
        button.click();

        // Check the the value of the button is "Clicked"
        Assert.assertEquals("Clicked", button.getText());
    }

    @After
    public void tearDown() throws Exception {
        // close the browser instance when all tests are done
        getDriver().quit();
    }

}
```

JUnit 5 support is added in Vaadin 24.

**JUnit 5**

```java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.BeforeEach;

import com.vaadin.testbench.BrowserTest;
import com.vaadin.testbench.BrowserTestBase;

public class SimpleIT extends BrowserTestBase {

    @BeforeEach
    public void setup() throws Exception {
        // Open the application
        getDriver().get("http://localhost:8080/");
    }

    // Please note that since TestBench 9 test methods
    // must be annotated with helper @BrowserTest annotation.
    @BrowserTest
    public void clickButton() {
        // Find the first button (<vaadin-button>) on the page
        ButtonElement button = $(ButtonElement.class).first();

        // Click it
        button.click();

        // Check that text of the button is "Clicked"
        Assertions.assertEquals("Clicked", button.getText());
    }

}
```

This is all that’s needed to verify that the button text is "Clicked" after clicking on it.

> **Note:** WebComponents hide their content in the Shadow DOM. This is why elements inside a WebComponent can’t be found without specifying a search context. For example, `$(TestBenchElement.class).id("content").$(LabelElement.class).first()`, which means a label should be found inside the element with `id="content"`, which should be found on the page or current context. To write real tests, use the [Page or View Objects](https://vaadin.com/docs/next/flow/testing/end-to-end/page-objects.md), which improve code readability.

> **Tip:** Don’t place your tests in the root package, as in this example. Structure them logically according to your application structure.

## <a id="running-tests"></a>Running Tests

The server hosting your application needs to be running at the given URL before you launch your test. If the server is already running and the application is deployed, you only need to ensure that the URL in the test is correct.

If you’re using the Spring Boot starter at <https://start.vaadin.com>, you can launch the application using the following:

```
mvn spring-boot:run
```

If you’re using a plain Java Servlet starter, you can launch the application using this:

```
mvn jetty:run
```

You can now launch your test in your IDE (run as JUnit test) or in another terminal like so:

```
mvn verify
```

You should see a browser window opening, doing something, and then closing. If the test fails, put a breakpoint in the `clickButton()` method so you can see what happens in the browser before it closes.

> **Tip:** Because the test name ends in `IT`, the Maven failsafe plugin recognizes the test as an integration test and is able to start automatically and deploy your application before the test and shut down the server after all tests have been run (tie the server to the `pre-integration-test` and `post-integration-test` phases). See <https://github.com/vaadin/testbench-demo> for an example.

\+ Running `mvn test` only runs unit tests (`*Test`) by default, whereas `mvn verify` also runs integration tests (`*IT`).

`547F7BA4-9832-4DCB-8900-6E29260D9800`