Getting Started with End-to-End Testing

Setting Up Your Project
Creating a Simple Test
Running Tests

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.

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:

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

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 for more details.

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:

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();
    }

}

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

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.

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

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

Documentation