Documentation versions (currently viewingVaadin 8)

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

Installing Vaadin TestBench

As with most Vaadin add-ons, you can install Vaadin TestBench as a Maven or Ivy dependency in your project, or from an installation package. The installation package contains some extra material, such as documentation, as well as the standalone library, which you use for testing in a grid.

The component element classes are Vaadin version specific and they are packaged in a vaadin-testbench-api library JAR, separately from the vaadin-testbench-core runtime library, which is needed for executing the tests.

Additionally, you may need to install drivers for the browsers you are using as described in Installing Browser Drivers.

Test Development Setup

In a typical test development setup, you develop tests in a Java project and run them on the development workstation. You can run the same tests in a dedicated test server, such as a continuous integration system.

In a test development setup, you do not need a grid hub or nodes. However, if you develop tests for a grid, you can run the tests, the grid hub, and one node all in your development workstation. A distributed setup is described later.

Maven Dependency

Add to the Vaadin TestBench dependency to your pom.xml. Remember to use the test scope as you don’t want the testing libraries to be deployed with your application.


You also need to define the Vaadin add-ons repository if not already defined:


The vaadin-archetype-application archetype includes the repository declarations.

Ivy Dependency

The Ivy dependency, to be defined in ivy.xml, would be as follows:

<dependency org="com.vaadin" name="vaadin-testbench"
   rev="latest.release" conf="nodeploy->default"/>

The optional nodeploy->default configuration mapping requires a nodeploy configuration in the Ivy module; it is automatically created for new Vaadin projects.

A new Vaadin project created with the Vaadin Plugin for Eclipse includes the dependency.

Code Organization

We generally recommend developing tests in a project or module separate from the web application to be tested to avoid library problems. If the tests are part of the same project, you should at least arrange the source code and dependencies so that the test classes, the TestBench library, and their dependencies would not be deployed unnecessarily with the web application.

A Distributed Testing Environment

Vaadin TestBench supports distributed execution of tests in a grid. See "Running Tests in a Distributed Environment".

Installing Browser Drivers

Each browser requires a browser specific web driver to be setup before tests can be run.

  1. Download the latest browser driver

  2. Add the driver executable to user PATH. In a distributed testing environment, give it as a command-line parameter to the grid node service, as described in "Starting a Grid Node".

Adding Web Driver to System Path

The driver executable must be included in the operating system PATH or be given with a driver-specific system Java property:

  • Google Chrome:

  • Mozilla Firefox: webdriver.gecko.driver

  • Microsoft Edge: webdriver.edge.driver

  • Internet Explorer:

  • PhantomJS: phantomjs.ghostdriver.path and phantomjs.binary.path

You can set the property in Java with System.setProperty(prop, key)) or pass it as a command-line parameter to the Java executable with

If you use an ESR version of Firefox, which is recommended for test stability, you need refer to the binary when creating the driver as follows:

FirefoxBinary binary =
    new FirefoxBinary(new File("/path/to/firefox_ESR_45"));
driver = TestBench.createDriver(
    new FirefoxDriver(binary, new FirefoxProfile()));

Installing ChromeDriver for Ubuntu Chromium

While you can install Google Chrome in Ubuntu, it also has its own Chromium Browser, which is based on the Google Chrome. Chromium has its own version of ChromeDriver, which requires some additional installation steps to be usable.

Install the ChromeDriver:

$ sudo apt-get install chromium-chromedriver

Add the driver executable to path, such as:

$ sudo ln -s /usr/lib/chromium-browser/chromedriver /usr/local/bin/chromedriver

The Chromium libraries need to be included in the system library path:

$ sudo sh -c 'echo "/usr/lib/chromium-browser/libs" > /etc/'
$ sudo ldconfig