Integration Testing with Maven

Project Structure
Overview of Lifecycle
Overview of Configuration
Vaadin Plugin Configuration
Configuring Integration Testing
Configuring Test Server

TestBench is often used in Maven projects, where you want to run tests as part of the build lifecycle. While ordinary Java unit tests are usually executed in the test phase, TestBench tests are usually executed in the integration-test phase (to run the phase properly you need to invoke verify phase as explained later).

"Quick Start with Maven" describes how to use the Vaadin application archetype for Maven provides a TestBench setup. In this section, we largely go through that and also describe how to make such a setup also in Vaadin add-on projects.

Project Structure

In Vaadin Applications

In a typical Vaadin application, such as in the one created by the archetype, you only have one module and you run tests there. The application sources would normally be in src/main and test code, together with TestBench tests, in src/test.

In Libraries and Add-ons

In multi-module projects, you may have libraries in other modules, and the actual web application in another. Here you could do library unit tests in the library modules, and integration tests in the web application module.

The multi-module project structure is recommended for Vaadin add-ons, where you have the add-on library in one module and a demo in another.

Overview of Lifecycle

The Maven lifecycle phases relevant to TestBench execution are as follows:

compile
- Compile server-side
- Compile widget set
- Compile theme
test-compile
- Compile test classes (both unit and integration tests)
pre-integration-test
- Start web server (Jetty or other)
integration-test
- Execute TestBench tests
post-integration-test
- Stop web server
verify
- Verify the results of the integration tests

Overview of Configuration

The Maven configuration in the pom.xml should include the following parts, with our reference toolchain given in parentheses:

Integration test runner (Maven Failsafe Plugin)
Web server (Jetty)
Web server runner (Jetty Maven Plugin)
Vaadin compilation and deployment (Vaadin Maven Plugin)

Vaadin Plugin Configuration

The Vaadin Maven Plugin compiles the widget set with the Vaadin Client Compiler and the theme with the Vaadin Sass compiler in the compile phase. Its configuration should be as is normal for Vaadin projects. The default configuration is created by the Vaadin project archetype, as described in "Using Vaadin with Maven".

Configuring Integration Testing

Our reference toolchain uses the Maven Failsafe Plugin to execute integration tests with TestBench. The plugin executes tests (JUnit or other) defined in the test files included in the plugin configuration.

To run TestBench tests made with JUnit, you need that dependency in the <dependencies> section:

<!-- Needed for running TestBench tests -->
  <dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.12</version>
  <scope>test</scope>
</dependency>

Surefire requires the following plugin configuration (under <plugins>):

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>2.17</version>
  <configuration>
    <includes>
      <include>**⁄*Tests.java</include>
    </includes>
    <excludes>
      <!-- Here list files that might match to naming conventions unintentionally. We can ignore them from testing. -->
    </excludes>
  </configuration>
  <executions>
    <execution>
      <id>failsafe-integration-tests</id>
      <phase>integration-test</phase>
      <goals>
        <goal>integration-test</goal>
      </goals>
    </execution>
    <execution>
      <id>failsafe-verify</id>
      <phase>verify</phase>
      <goals>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Set the include and exclude patterns according to your naming convention. See Failsafe documentation for more details about the configuration, for example, if you want to use other test provider than JUnit.

Configuring Test Server

We use Jetty as our reference test server, as it is a light-weight server that is easy to configure with a Maven plugin.

The dependency for Jetty goes as follows:

<dependency>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-webapp</artifactId>
    <version>9.2.10.v20150310</version>
    <scope>test</scope>
</dependency>

The plugin configuration for running Jetty goes as follows:

<plugin>
    <groupId>org.mortbay.jetty</groupId>
    <artifactId>jetty-maven-plugin</artifactId>
    <version>8.1.16.v20140903</version>

    <configuration>
        <webApp>
            <contextPath>/myapp</contextPath>
        </webApp>
        <stopKey>STOP</stopKey>
        <stopPort>8005</stopPort>
    </configuration>

    <executions>
        <execution>
            <id>start-jetty</id>
            <phase>pre-integration-test</phase>
                <goals>
                <goal>start</goal>
            </goals>
            <configuration>
                <daemon>true</daemon>
                <scanIntervalSeconds>0</scanIntervalSeconds>
            </configuration>
        </execution>
        <execution>
            <id>stop-jetty</id>
            <phase>post-integration-test</phase>
            <goals>
                 <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Here you only need to configure the contextPath parameter, which is the context path to your web application.

Docs