Integration Testing Framework Extension

Release	Maven Central	Release Notes	Users Guide
0.13.1
0.14.0-SNAPSHOT

State

The project is in an early state but already being useful and can be used for real testing. The project release is available via Central repository (only the given version as show in above table) which makes it easy for you to use it out without the need to compile the code (You can of course do that if you like) yourself.

General Overview

The basic thing about integration testing of Maven Plugins / Maven Extensions etc. is currently that the existing solutions are not a very concise and comprehensive which is based on the long development history of the Apache Maven project. There are a lot of different approaches done over the time but from my perspective they all lack one thing: Simplicity. More detailed reasons etc. can be read in the Background Guide. This is the reason why I think it's time to come up with a more modern setup and started this project.

The Basic Idea

The basic idea rest upon the option to write custom extension with JUnit Jupiter for JUnit Jupiter testing framework which makes it very easy to get things done.

So in general the whole Integration Testing Framework in its core (itf-jupiter-extension) is a JUnit Jupiter extension which delivers supplemental support for a testing framework in general and in particular for using integration tests. Of course there is a lot of convenience integrated into it to make integration testing of Maven plugins easier.

Quick Start

The General Requirements

The requirements to write integration tests with the integration testing framework are the following:

• JDK8+
• Apache Maven 3.8.1 or above.

The Maven Configuration

The first thing before you can run integration tests is to add the following dependencies (as minimum) to your pom.xml:

<project..>
   ...
  <dependencies>
   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-engine</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.soebes.itf.jupiter.extension</groupId>
      <artifactId>itf-jupiter-extension</artifactId>
      <version>0.13.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
     <groupId>com.soebes.itf.jupiter.extension</groupId>
     <artifactId>itf-assertj</artifactId>
     <version>0.13.1</version>
     <scope>test</scope>
    </dependency>
  </dependencies>
  ..
</project..>

The first dependency org.junit.jupiter:junit-jupiter-engine is needed for JUnit Jupiter (We recommend the most recent version) working and the second one com.soebes.itf.jupiter.extension:itf-jupiter-extension is the extension to get support for running in general integration tests as described later. Finally, you have to add com.soebes.itf.jupiter.extension:itf-assertj which contains custom assertions based on AssertJ.

The next part is to add itf-maven-plugin in your pom.xml file like this which handles the first part which is involved:

<project...>
  ..
  <build>
    ..
    <plugin>
      <groupId>com.soebes.itf.jupiter.extension</groupId>
      <artifactId>itf-maven-plugin</artifactId>
      <version>0.13.1</version>
      <executions>
        <execution>
          <id>installing</id>
          <phase>pre-integration-test</phase>
          <goals>
            <goal>install</goal>
            <goal>resources-its</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    ..
  </build>
  ..
</project...>

The given version of itf-jupiter-extension as well as itf-maven-plugin should always be the most recent version which is available via Central repository.

Based on the concept we would like to run integration identified by the naming convention we have to add the maven-failsafe-plugin to the pom.xml like this (This will execute the integration tests which checks the functionality; The second part which is involved).

<project...>
  ..
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <configuration>
      <!--
       ! currently needed to run integration tests.
      -->
      <systemPropertyVariables>
        <maven.version>${maven.version}</maven.version>
        <maven.home>${maven.home}</maven.home>
      </systemPropertyVariables>
    </configuration>
    <executions>
      <execution>
        <goals>
          <goal>integration-test</goal>
          <goal>verify</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
</project...>

Details about the given configuration can be read in the users guide.

The Involved Parties

Writing an integration test for a Maven plugin means you have to have three parties:

1. The component you would like to test (typically a Maven plugin etc.).
2. The testing code where you check the functionality.
3. The Project you would like to test with (where your Maven plugin usually is configured in to be used.)

The Component code

The component you write is located in your project in the usual location. This is of course only an example of how it looks like in reality (usually more classes etc.):

.
└── src/
    └── main/
        └── java/
            └── org/
                └── plugin/
                    └── PluginMojo.java

The Testing Code

The structure for an integration tests follows of course the convention over configuration paradigm. Based on the conventions in Maven an integration test should be named like *IT.java and be located in the directory structure as follows:

.
└── src/
    └── test/
        └── java/
            └── org/
                └── it/
                    └── FirstMavenIT.java

So now the real a test code looks like this:

package org.it;

import static com.soebes.itf.extension.assertj.MavenITAssertions.assertThat;

import com.soebes.itf.jupiter.extension.MavenJupiterExtension;
import com.soebes.itf.jupiter.extension.MavenTest;
import com.soebes.itf.jupiter.maven.MavenExecutionResult;

import static com.soebes.itf.extension.assertj.MavenITAssertions.assertThat;

@MavenJupiterExtension // <1>
public class FirstMavenIT {

 @MavenTest // <2>
 void the_first_test_case(MavenExecutionResult result) { // <3>
  assertThat(result).isSuccessful(); // <4>
 }
 
}

1. Maven Integration test annotation.
2. Maven Test Annotation.
3. Injected execution result
4. Custom assertions to check the result of the build.

The Project to Test With

The project you would like to use as a foundation for your test of the plugin. This is located in a special location under src/test/resources-its/... This is needed to prevent the confusion with the usual src/test/resources in particular related to filtering etc. (details about the setup etc. in the users guide).

.
└── src/
    └── test/
        └── resources-its/
            └── org/
                └── it/
                    └── FirstMavenIT/
                        └── the_first_test_case/
                            ├── src/
                            └── pom.xml

The Executed Test

After execution of the integration test the result will look like this:

.
└──target/
   └── maven-it/
       └── org/
           └── it/
               └── FirstMavenIT/
                   └── the_first_test_case/
                       ├── .m2/
                       ├── project/
                       │   ├── src/
                       │   ├── target/
                       │   └── pom.xml
                       ├── mvn-stdout.log
                       ├── mvn-stderr.log
                       ├── mvn-arguments.log
                       └── other logs.

This gives you a first impression how an integration test can look like. There are a lot of example in this project available and of course I strongly recommend reading the documentation (I know I don't like reading documentation either).

Conclusion

If you like the framework don't hesitate to test and give feedback in particular if things don't work as described or as you expected them to work.

Building

If you like to build the project from source yourself you need the following:

• JDK 21+
• Apache Maven 3.9+

The whole project can be built via:

mvn clean verify

This will take some time cause there are already integration tests in the itf-examples project which are executed and real integration tests for the itf-maven-plugin which is a bootstrap (eat-your-own-dog-food) to use already parts of the framework (JUnit Jupiter extension) to make the development of the plugin easier.

Concept and Background Guide

The concept guide describe my ideas I have in mind (just not to forget them). It is neither a roadmap nor about future releases etc. It's only intended to keep my ideas at a central location.

• 
• 

The background guide is a conclusion about the reason why I have started this project.

• 
• 

GitHub Pages

Currently, we have two states of site:

• Release State of the generated Maven site https://khmarbaise.github.io/maven-it-extension/
• The SNAPSHOT State of the Maven site https://khmarbaise.github.io/maven-it-extension/snapshot/

Generate Code Coverage

Code coverage via:

mvn clean verify org.jacoco:jacoco-maven-plugin:report

Contributing

If you want to contribute, there is a contribution guide for you.