Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/khmarbaise/maven-it-extension
Experimental JUnit Jupiter Extension for writing integration tests for Maven plugins/Maven extensions/Maven Core
https://github.com/khmarbaise/maven-it-extension
apache-maven integration-testing junit-jupiter junit-jupiter-extension junit5-extension maven maven-plugins the-integration-testing-framework
Last synced: 3 days ago
JSON representation
Experimental JUnit Jupiter Extension for writing integration tests for Maven plugins/Maven extensions/Maven Core
- Host: GitHub
- URL: https://github.com/khmarbaise/maven-it-extension
- Owner: khmarbaise
- License: apache-2.0
- Created: 2019-10-29T20:23:09.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-22T19:05:05.000Z (4 months ago)
- Last Synced: 2024-05-22T19:41:03.967Z (4 months ago)
- Topics: apache-maven, integration-testing, junit-jupiter, junit-jupiter-extension, junit5-extension, maven, maven-plugins, the-integration-testing-framework
- Language: Java
- Homepage: https://khmarbaise.github.io/maven-it-extension/
- Size: 57.3 MB
- Stars: 86
- Watchers: 5
- Forks: 26
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Integration Testing Framework Extension
[][license]
[](https://github.com/khmarbaise/maven-it-extension/actions/workflows/push.yml)
[][published-site]
[](https://github.com/khmarbaise/maven-it-extension/issues)
[](https://github.com/khmarbaise/maven-it-extension/issues?q=is%3Aissue+is%3Aclosed)
[](https://codecov.io/gh/khmarbaise/maven-it-extension)
| Release | Maven Central | Release Notes | Users Guide |
|-----------------| --------------------------------------------------- | ----------------------------------------------------------------: | -------------------------------------------------------------: |
| 0.13.1 | [![Maven Central][shield-central]][central-search] | [![PDF][stable-pdf-releasenotes]][releasenotes-pdf] | [![PDF][stable-pdf-usersguide]][usersguide-pdf] |
| | | [![HTML][stable-html-release]][releasenotes-html] | [![HTML][stable-html-usersgude]][usersguide-html] |
| 0.14.0-SNAPSHOT | ![Maven Central][not-available-in-central] | [![PDF][unstable-pdf-releasenotes]][unstable-releasenotes-pdf] | [![PDF][unstable-pdf-usersguide]][unstable-usersguide-pdf] |
| | | [![HTML][unstable-html-releasenotes]][unstable-releasenotes-html] | [![HTML][unstable-html-usersguide]][unstable-usersguide-html] |
# 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][central-search] (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][background-html]. 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][junit-jupiter-extension]
for [JUnit Jupiter][junit-jupiter-extension] 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][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`:
```xml
...
org.junit.jupiter
junit-jupiter-engine
test
com.soebes.itf.jupiter.extension
itf-jupiter-extension
0.13.1
test
com.soebes.itf.jupiter.extension
itf-assertj
0.13.1
test
..
```
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][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:
```xml
..
..
com.soebes.itf.jupiter.extension
itf-maven-plugin
0.13.1
installing
pre-integration-test
install
resources-its
..
..
```
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][central-search].
Based on the concept we would like to run integration identified by the naming convention we have
to add the [maven-failsafe-plugin][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).
```xml
..
org.apache.maven.plugins
maven-failsafe-plugin
${maven.version}
${maven.home}
integration-test
verify
```
Details about the given configuration can be read in the [users guide][usersguide-html].
## 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:
```java
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][usersguide-html-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][usersguide-html]).
```text
.
└── 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:
```text
.
└──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](https://github.com/khmarbaise/maven-it-extension/blob/master/itf-examples/src/test/java/com/soebes/itf/examples/MavenProjectIT.java)
and of course I strongly recommend reading the [documentation][usersguide-html]
(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:
```bash
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][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.
* [][conceptguide-pdf]
* [][conceptguide-html]
The background guide is a conclusion about the reason why I have started this project.
* [][background-pdf]
* [][background-html]
# 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:
```bash
mvn clean verify org.jacoco:jacoco-maven-plugin:report
```
# Contributing
If you want to contribute, there is a [contribution guide](CONTRIBUTING.md) for you.
[food]: https://en.wikipedia.org/wiki/Eating_your_own_dog_food
[jdkbuilds]: https://github.com/khmarbaise/maven-it-extension/actions?query=workflow%3AJDKBuilds
[mainbuilds]: https://github.com/khmarbaise/maven-it-extension/actions?query=workflow%3AMain
[published-site]: https://khmarbaise.github.io/maven-it-extension/
[license]: https://www.apache.org/licenses/LICENSE-2.0
[junit-jupiter]: https://junit.org/junit5/
[junit-jupiter-extension]: https://junit.org/junit5/docs/current/user-guide/#extensions
[assertj]: https://assertj.github.io/doc/
[maven-failsafe-plugin]: https://maven.apache.org/surefire/maven-failsafe-plugin/
[usersguide-html]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/usersguide/usersguide.html
[usersguide-html-assertions]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/usersguide/usersguide.html#_assertions
[usersguide-pdf]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/usersguide/usersguide.pdf
[releasenotes-html]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/release-notes/release-notes.html
[releasenotes-pdf]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/release-notes/release-notes.pdf
[unstable-usersguide-html]: https://khmarbaise.github.io/maven-it-extension/snapshot/itf-documentation/usersguide/usersguide.html
[unstable-usersguide-pdf]: https://khmarbaise.github.io/maven-it-extension/snapshot/itf-documentation/usersguide/usersguide.pdf
[unstable-releasenotes-html]: https://khmarbaise.github.io/maven-it-extension/snapshot/itf-documentation/release-notes/release-notes.html
[unstable-releasenotes-pdf]: https://khmarbaise.github.io/maven-it-extension/snapshot/itf-documentation/release-notes/release-notes.pdf
[stable-html-release]: https://img.shields.io/badge/0.13.1-HTML--Releasenotes-green
[stable-html-usersgude]: https://img.shields.io/badge/0.13.1-HTML--Usersguide-green
[stable-pdf-releasenotes]: https://img.shields.io/badge/0.13.1-PDF--Releasenotes-green
[stable-pdf-usersguide]: https://img.shields.io/badge/0.13.1-PDF--Usersguide-green
[unstable-pdf-releasenotes]: https://img.shields.io/badge/0.14.0--SNAPSHOT-PDF--Releasenotes-orange
[unstable-html-releasenotes]: https://img.shields.io/badge/0.14.0--SNAPSHOT-HTML--Releasenotes-orange
[unstable-pdf-usersguide]: https://img.shields.io/badge/0.14.0--SNAPSHOT-PDF--Usersguide-orange
[unstable-html-usersguide]: https://img.shields.io/badge/0.14.0--SNAPSHOT-HTML--Usersguide-orange
[shield-central]: https://img.shields.io/maven-central/v/com.soebes.itf.jupiter.extension/itf-jupiter-extension.svg?label=Maven%20Central
[central-search]: https://central.sonatype.com/search?q=g%3Acom.soebes.itf.jupiter.extension
[not-available-in-central]: https://img.shields.io/badge/Maven%20Central-NOT_AVAILABLE-red
[conceptguide-html]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/concept/Concept.html
[conceptguide-pdf]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/concept/Concept.pdf
[background-html]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/background/background.html
[background-pdf]: https://khmarbaise.github.io/maven-it-extension/itf-documentation/background/background.pdf