Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Vaadin 8 TestBench Quickstart

This section walks you through the steps needed to add a TestBench test to your Vaadin application. We use Maven to set up the project and handle the dependencies. If you do not have a Vaadin application, you can generate it using Maven archetype:

 $ mvn -B archetype:generate \
    -DarchetypeGroupId=com.vaadin \
    -DarchetypeArtifactId=vaadin-archetype-application \
    -DarchetypeVersion=8.14.3 \
    -DgroupId=org.test \
    -DartifactId=vaadin-app \
    -Dversion=0.1 \

Running tests on different browsers requires a web driver for the browser to be installed, see "Installing Browser Drivers".

Before TestBench version 5.0.0, Firefox did not require a web driver setup. Since TestBench version 5.0.0, Geckodriver is used to run tests on Firefox. Geckodriver requires a separate installation. You can run your tests using other browsers. All supported browsers require a special driver and some additional setup, see "Installing Browser Drivers".
Geckodriver used for the latest Firefox versions (48 and newer) does not support actions API. In practice, meaning that you can not simulate context click and double click in tests. It also means that some parts of the Element API just will not work. It is recommended you use Firefox 45 ESR to execute tests on Firefox, before this is fixed. See "Known Issues" for details.

Adding the Maven Dependency

Let us add the Vaadin TestBench dependency to the project. Open the pom.xml file and find the dependencies tag. Add the following dependency declaration just before the end tag (/dependencies):


Installing License Key

Before running tests, you need to install a license key. You can purchase a license or obtain a free trial key from the Vaadin TestBench download page in Vaadin Directory. The easiest way to install the license key is to copy and paste it to a .vaadin.testbench.developer.license file in your home directory. Other options of installing license key are described "here".

Create a Sample Test Class

In the Maven world, all test classes and resources live in the src/test directory, so create that directory. Continue by creating a java directory under that so that you end up with an src/test/java directory structure. Create a new file called in the src/test/java directory.

To create a TestBench test, you need to perform the following steps:

  • Set the browser driver and open the tested web page.

  • Simulate user actions by using TestbenchElement classes.

  • Compare expected and actual results.

  • Close the browser window.

To give an example, we create a test that clicks the button in the UI and checks that the value of the label has changed:

import org.junit.Assert;
import org.junit.Test;

public class MyAppTest extends ParallelTest {

    private static final String URL="http://localhost";
    private static final String PORT="8080";

    public void setup() throws Exception {
        setDriver(new FirefoxDriver());
        //Open the web page

    public void tearDown() throws Exception {
        //close the browser window

    public void test() {
        //Get a reference to the button
        ButtonElement button = $(ButtonElement.class).first();

        //Simulate button click;;

        //Get text field value;
        String actualValue = $(LabelElement.class).first().getText();

        //Check that the value is not empty

Now you have your first TestBench test case ready.

Running Tests

Before running the test, you should start your Vaadin application under test.

mvn jetty:run

You can now run the test by issuing Maven command line:

mvn test

or run it as a Junit Test from you IDE.