Integration Testing in Flow

Sometimes creating unit tests is not enough. It might be important to test that the given functionality works end-to-end in an application. This is specially important for features and bugs that depend on the browser functionality. Integration testing in Flow is being done with a View & Integration Test combination.

The integration tests are in flow-tests module. Most of the integration tests for the core part are under flow-test-core module. Descriptions about integration test modules are inside the README.md file in /flow-tests.

The integration tests use TestBench, for information see Vaadin TestBench. TestBench is a commercial tool, but you need the license for it to only run the tests locally. It is possible to get a free license to the TestBench product if you contribute to the Vaadin projects frequently. You can contact us in discord if you feel you deserve the license - we’re happy to give it to contributors.

Creating the View Class

First you should start by looking if there is already a suitable test view that you can reuse. One way to do it is by seeing if the code related to the test is being called from any of the existing test views.

The view @Route value should be the fully qualified name of the view class like com.vaadin.flow.uitest.ui.YourTestClassNameView. For example:

Show code

Example of a test view

Expand code

@Route(value = "com.vaadin.flow.uitest.ui.CompositeView", layout = ViewTestLayout.class)
public class CompositeView extends AbstractDivView {
    // ...
}

Opening the View Class in the Browser

You can open the test view in the browser by first starting up the jetty server for that module. You can trigger the jetty:run Maven task for the module through your IDE, or by running the command mvn jetty:run -pl <test-module-name> like mvn jetty:run -pl flow-test-core.

You can then open the view in the browser for example from http://localhost:8888/view/com.vaadin.flow.uitest.ui.CompositeView (depending on the route used).

Creating the Integration Test Class

The integration test class should be named the same as the View class that it tests. For example, PageView gets the test class PageIT. This enables the open() method to find the correct test view path automatically.

The integration test class should extend ChromeBrowserTest. Some test classes extend an Abstract* class that provides common functionality to be reused in the tests.

Show code

Example of a integration test class

Expand code

public class CompositeIT extends ChromeBrowserTest {
    @Test
    public void changeOnClient() {
        open();
        // ...
    }
}

When writing a lot of integration tests, you should use the Page Object pattern where the interaction between the browser is handled through an API that is reused for all the tests. You can read more about it from the TestBench documentation.

Running the Integration Tests

Running all the integration tests takes a while, so it is more efficient to only compile the modules that changed, and then run the specific ITs written for the changes. Before running integration tests locally, install the following modules mvn install -pl flow-test-util -pl flow-tests/test-resources -pl flow-tests/test-common.

Running all integration tests for a single module mvn verify -pl <test-module-folder-name>. Running all the integration tests mvn verify -pl flow-tests.

You can execute tests for single class by running the mvn -Dit.test=<it-test-class-name> verify -pl <module-folder-name>. Also, for running a single inside a class you can execute mvn -Dit.test=<test-class-name>#<test-method-name> test -pl <module-folder-name>.

To reduce the chance your IT test is flaky, run it several times before publishing it out.