Documentation versions (currently viewingVaadin 8)

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

Creating a Test Case

Test Setup

Test configuration is done in a method annotated with @Before. The method is executed before each test case.

The basic configuration tasks are:

  • Set TestBench parameters

  • Create the web driver

  • Do any other initialization

TestBench Parameters

TestBench parameters are defined with static methods in the com.vaadin.testbench.Parameters class. The parameters are mainly for screenshots and documented in "Taking and Comparing Screenshots".

Basic Test Case Structure

A typical test case does the following:

  1. Open the URL

  2. Navigate to desired state .. Find a HTML element ( WebElement) for interaction

    1. Use click() and other commands to interact with the element

    2. Repeat with different elements until desired state is reached

  3. Find a HTML element ( WebElement) to check

  4. Get and assert the value of the HTML element

  5. Get a screenshot

The WebDriver allows finding HTML elements in a page in various ways, for example, with XPath expressions. The access methods are defined statically in the By class.

These tasks are realized in the following test code:

public void basic() throws Exception {

    // Find an element to interact upon
    ButtonElement button =

    // Click the button;

    // Check that the label text is correct
    LabelElement label = $(LabelElement.class).first();
    assertEquals("Thanks!", label.getText());

You can also use URI fragments in the URL to open the application at a specific state.

For information about URI fragments, see "Managing URI Fragments".

You should use the JUnit assertion commands. They are static methods defined in the org.junit.Assert class, which you can import (for example) with:

import static org.junit.Assert.assertEquals;

Please see the Selenium API documentation for a complete reference of the element search methods in the WebDriver and By classes and for the interaction commands in the WebElement class.

TestBench has a collection of its own commands, defined in the TestBenchCommands interface. You can get a command object that you can use by calling testBench(driver) in a test case.

While you can develop tests simply with test cases as described above, for the sake of maintainability it is often best to modularize the test code further, such as to separate testing at the levels of business logic and the page layout. See "Creating Maintainable Tests" for information about using page objects for this purpose.

Creating and Closing a Web Driver

Vaadin TestBench uses Selenium WebDriver to execute tests in a browser. The WebDriver instance is created with the static createDriver() method in the TestBench class. It takes the driver as the parameter and returns it after registering it. The test cases must extend the TestBenchTestCase class, which manages the TestBench-specific features. You need to store the driver in the test case with setDriver().

The basic way is to create the driver in a method annotated with the JUnit @Before annotation and close it in a method annotated with @After.

public class AdvancedTest extends TestBenchTestCase {
    public void setUp() throws Exception {
        setDriver(TestBench.createDriver(new FirefoxDriver()));
    public void tearDown() throws Exception {

This creates the driver for each test you have in the test class, causing a new browser instance to be opened and closed. If you want to keep the browser open between the tests, you can use @BeforeClass and @AfterClass methods to create and quit the driver. In that case, the methods as well as the driver instance have to be static and you need to set the driver in a @Before method.

public class AdvancedTest extends TestBenchTestCase {
    static private WebDriver driver;

    static public void createDriver() throws Exception {
        driver = TestBench.createDriver(new FirefoxDriver());

    public void setUp() throws Exception {
    static public void tearDown() throws Exception {

Browser Drivers

Please see the API documentation of the WebDriver interface for a complete list of supported drivers, that is, classes implementing the interface.

All supported browsers require a special driver, as was noted in "Installing Browser Drivers".