Maven with JUnit 5 + Cucumber project on a Github Repo

MAVEN_README.md

Maven Template

Here is a maven template file to :

• create JAR
• Javadoc
• execute Unit and Cucumber Tests
• build Shaded JAR
• generate epub+pdf from 'docs/' markdown files
• push github pages from 'docs/' markdown files

Prerequisit

Dependencies to :

• Junit5 5.9.0 (junit-platform 1.9.0),
• Cucumber 7.6.0,
• Pandoc,
• Codacy online service as SaaS,
• Cucumber.io report publishing,
• JDK 18 !

The project structure must stick to maven standard and add a docs/ dir :

MyProject
|_ docs
|_ src
|_ pom.xml

Usage

Replace the following placeholders with their right values in the file :

1. About the project :

• [ProjectGroupId] the maven group id
• [ProjectArtifactId] the maven artifact id
• [ProjectVersion] the versionfor you prokject X.Y.Z-[VARIANT]
• [ProjectDescription] a simple description sentence for the project
• [ProjectYear] the Project year

2. About the java code:

• [ApplicationMainClass] the main class to start with

3. About the author:

• [AuthorName] Name of the author (as a contributor)
• [AuthorEmail] Email of the author (as a contributor)
• [AuthorCompany] if company is needed, its name
• [AuthorCompanyUrl] if company is needed, its optional URL

4. About the repo:

• [GitUser] github user
• [GitRepo] github project repo

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>[ProjectGroupId]</groupId>
    <artifactId>[ProjectArtifactId]</artifactId>
    <version>[ProjectVersion]</version>
    <name>[ProjectName]</name>
    <description>[ProjectDescription]</description>
    <inceptionYear>[ProjectYear]</inceptionYear>

    <!-- Project License -->
    <licenses>
        <license>
            <name>MIT</name>
            <url>https://raw.githubusercontent.com/[GitUser]/[GitRepo]/main/LICENSE</url>
        </license>
    </licenses>

    <!-- Authors and Designers -->
    <contributors>
        <contributor>
            <name>[AuthorName]</name>
            <email>[AuthorEmail]</email>
            <organization>[AuthorCompany]</organization>
            <organizationUrl>[AuthorCompanyUrl]</organizationUrl>
            <timezone>Europe/Paris</timezone>
            <roles>
                <role>Developer</role>
            </roles>
        </contributor>
    </contributors>

    <!-- Project eco-system definition -->
    <organization>
        <url>http://[AuthorCompany].github.io</url>
        <name>[AuthorCompany]</name>
    </organization>
    <scm>
        <url>https://github.com/[GitUser]/[GitRepo]</url>
        <connection>scm:git:git@github.com:[GitUser]/[GitRepo].git</connection>
        <developerConnection>scm:git:https://github.com/[GitUser]/[GitRepo].git</developerConnection>
        <tag>v${project.version}</tag>
    </scm>
    <issueManagement>
        <system>GitHub</system>
        <url>https://github.com/[GitUser]/[GitRepo]/issues</url>
    </issueManagement>
    <ciManagement>
        <url>https://github.com/[GitUser]/[GitRepo]/actions/</url>
        <system>github-actions</system>
    </ciManagement>

    <distributionManagement>
        <repository>
            <id>github</id>
            <name>GitHub Packages</name>
            <url>https://maven.pkg.github.com/[GitUser]/[GitRepo]</url>
        </repository>
    </distributionManagement>

    <properties>
        <mainClass>[ApplicationMainClass]</mainClass>
        <maven.compiler.source>18</maven.compiler.source>
        <maven.compiler.target>18</maven.compiler.target>
        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
        <project.scm.id>github</project.scm.id>
        <cucumber.version>7.6.0</cucumber.version>
        <junit.version>5.9.0</junit.version>
        <junit-platform.version>1.9.0</junit-platform.version>
    </properties>

    <!-- Project Dependencies -->

    <dependencies>
        <!-- tests things -->
        <!-- https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter-api -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-suite</artifactId>
            <version>${junit-platform.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-junit-platform-engine</artifactId>
            <version>${cucumber.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-java8</artifactId>
            <version>${cucumber.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-core</artifactId>
            <version>${cucumber.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>${project.artifactId}-${project.version}</finalName>
        <plugins>
            <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-compiler-plugin -->
            <!-- Compilation -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>
                <configuration>
                    <release>${maven.compiler.source}</release>
                    <enablePreview>true</enablePreview>
                    <source>18</source>
                    <target>18</target>
                    <encoding>UTF-8</encoding>
                    <compilerArgs>--enable-preview</compilerArgs>
                </configuration>
            </plugin>

            <!-- Resource parsing -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>

            <!-- Compute coverage -->
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.7</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>report</id>
                        <phase>test</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Sources -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <version>3.2.1</version>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>jar-no-fork</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Javadoc -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <encoding>utf-8</encoding>
                    <stylesheet>maven</stylesheet>
                    <source>${maven.compiler.source}</source>
                    <show>public</show>
                    <failOnError>false</failOnError>
                    <failOnWarnings>false</failOnWarnings>
                    <useStandardDocletOptions>false</useStandardDocletOptions>
                    <linksource>false</linksource>
                    <show>private</show>
                    <nohelp>true</nohelp>
                    <overview>${project.basedir}/README.md</overview>
                    <bottom>
                        <![CDATA[<em>Copyright © \${project.inceptionYear} - [AuthorCompany].</em>]]>
                    </bottom>
                    <!--links>
                        <link>${project.issueManagement.url}</link>
                        <link>${project.ciManagement.url}</link>
                        <link>https://docs.oracle.com/en/java/javase/11/docs/api/</link>
                    </links-->
                    <!--doclet>ch.raffael.mddoclet.MarkdownDoclet</doclet>
                    <docletArtifact>
                        <groupId>ch.raffael.markdown-doclet</groupId>
                        <artifactId>markdown-doclet</artifactId>
                        <version>1.4</version>
                    </docletArtifact-->
                    <useStandardDocletOptions>true</useStandardDocletOptions>
                    <additionalOptions>--enable-preview</additionalOptions>
                </configuration>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Build the minimalist JAR without dependencies (Normal Edition) -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.2</version>
                <configuration>
                    <archive>
                        <index>true</index>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <mainClass>${project.mainClass}</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>

            <!-- Shaded jar with all dependencies -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.4</version>
                <configuration>
                    <!-- put your configurations here -->
                    <shadedArtifactAttached>true</shadedArtifactAttached>
                    <shadedClassifierName>shaded</shadedClassifierName>
                    <transformers>
                        <transformer
                                implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                            <mainClass>${project.mainClass}</mainClass>
                        </transformer>
                        <transformer
                                implementation="org.apache.maven.plugins.shade.resource.IncludeResourceTransformer">
                            <resource>src/main/resources/</resource>
                        </transformer>
                    </transformers>
                    <!-- end of config -->
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Release -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-release-plugin</artifactId>
                <version>2.5.3</version>
                <configuration>
                    <useReleaseProfile>false</useReleaseProfile>
                    <releaseProfiles>github</releaseProfiles>
                    <tagNameFormat>v${project.version}</tagNameFormat>
                    <autoVersionSubmodules>true</autoVersionSubmodules>
                </configuration>
            </plugin>

            <!-- Execution -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.0.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>java</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <mainClass>${project.mainClass}</mainClass>
                </configuration>
            </plugin>
            <!-- Surefire configuration -->
            <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-surefire-plugin -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.0.0-M7</version>
                <configuration>
                    <testFailureIgnore>true</testFailureIgnore>
                    <argLine>
                        --illegal-access=permit
                    </argLine>
                    <argLine>
                        --enable-preview
                    </argLine>

                    <properties>
                        <configurationParameters>
                            cucumber.junit-platform.naming-strategy=long
                        </configurationParameters>
                    </properties>
                </configuration>
            </plugin>
            <!-- Cucumber reporting -->
            <plugin>
                <groupId>net.masterthought</groupId>
                <artifactId>maven-cucumber-reporting</artifactId>
                <version>5.6.2</version>
                <executions>
                    <execution>
                        <id>execution</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <projectName>${project.name}</projectName>
                            <outputDirectory>${project.build.directory}/site/cucumber-reports</outputDirectory>
                            <jsonFiles>
                                <!-- supports wildcard or name pattern -->
                                <param>**/*.json</param>
                            </jsonFiles>
                            <skip>true</skip>
                            <mergeFeaturesById>true</mergeFeaturesById>
                            <buildNumber>4</buildNumber>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-site-plugin -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-site-plugin</artifactId>
                <version>3.9.1</version>
            </plugin>
        </plugins>
    </build>

    <reporting>
        <plugins>
            <!-- Generate the tests report -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-report-plugin</artifactId>
                <version>3.0.0-M7</version>
            </plugin>
            <!-- Code coverage -->
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.7</version>
                <reportSets>
                    <reportSet>
                        <reports>
                            <!-- select non-aggregate reports -->
                            <report>report</report>
                        </reports>
                    </reportSet>
                </reportSets>
            </plugin>
            <!-- Javadoc reporting -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <stylesheetfile>${basedir}/docs/styles/javadoc.css</stylesheetfile>
                    <show>public</show>
                </configuration>
            </plugin>

            <!-- Generate the Release Notes for this version (linked to github issues
                      list) -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-changes-plugin</artifactId>
                <version>2.12.1</version>
                <configuration>
                    <includeOpenIssues>false</includeOpenIssues>
                    <onlyMilestoneIssues>false</onlyMilestoneIssues>
                    <columnNames>Id,Type,Key,Summary,Assignee,Status,Fix Version</columnNames>
                </configuration>
                <reportSets>
                    <reportSet>
                        <reports>
                            <report>github-report</report>
                            <report>changes-report</report>
                        </reports>
                    </reportSet>
                </reportSets>
            </plugin>
        </plugins>
    </reporting>

    <profiles>
        <profile>
            <id>codecoverage</id>
            <activation>
                <property>
                    <name>env.TRAVIS</name>
                </property>
            </activation>
            <build>
                <plugins>
                    <!-- Online Code Quality service verification -->
                    <plugin>
                        <groupId>com.gavinmogan</groupId>
                        <artifactId>codacy-maven-plugin</artifactId>
                        <version>1.2.0</version>
                        <configuration>
                            <!--suppress UnresolvedMavenProperty -->
                            <apiToken>${env.CODACY_API_TOKEN}</apiToken>
                            <!--suppress UnresolvedMavenProperty -->
                            <projectToken>${env.CODACY_PROJECT_TOKEN}</projectToken>
                            <coverageReportFile>target/site/jacoco/jacoco.xml</coverageReportFile>
                            <!--suppress UnresolvedMavenProperty -->
                            <commit>${env.TRAVIS_COMMIT}</commit>
                            <codacyApiBaseUrl>https://api.codacy.com</codacyApiBaseUrl>
                            <failOnMissingReportFile>false</failOnMissingReportFile>
                        </configuration>
                        <executions>
                            <execution>
                                <id>post-test</id>
                                <phase>post-integration-test</phase>
                                <goals>
                                    <goal>coverage</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
        <profile>
            <id>create-epub</id>
            <build>
                <plugins>
                    <!-- generate and ebook (EPUB) width docs/ documentation content -->
                    <plugin>
                        <groupId>org.codehaus.mojo</groupId>
                        <artifactId>exec-maven-plugin</artifactId>
                        <version>1.6.0</version>
                        <executions>
                            <execution>
                                <id>pandoc-epub</id>
                                <phase>site</phase>
                                <configuration>
                                    <executable>pandoc</executable>
                                    <workingDirectory/>
                                    <arguments>
                                        <argument>docs/epub-metadata.yml</argument>
                                        <argument>docs/00-index.md</argument>
                                        <arguents>docs/chapter-01-introduction.md</arguents>
                                        <arguents>docs/chapter-00-chapter_title.md</arguents>
                                        <argument>--resource-path=docs/</argument>
                                        <argument>--toc</argument>
                                        <argument>--toc-depth=2</argument>
                                        <argument>-t</argument>
                                        <argument>epub3</argument>
                                        <argument>-o</argument>
                                        <argument>target/${project.name}-doc-${project.version}.epub</argument>
                                    </arguments>
                                </configuration>
                                <goals>
                                    <goal>exec</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
        <profile>
            <id>create-pdf</id>
            <build>
                <plugins>
                    <!-- generate PDF width docs/ documentation content -->
                    <plugin>
                        <groupId>org.codehaus.mojo</groupId>
                        <artifactId>exec-maven-plugin</artifactId>
                        <version>1.6.0</version>
                        <executions>
                            <execution>
                                <id>pandoc-pdf</id>
                                <phase>package</phase>
                                <configuration>
                                    <executable>pandoc</executable>
                                    <workingDirectory/>
                                    <arguments>
                                        <argument>docs/epub-metadata.yml</argument>
                                        <argument>docs/00-index.md</argument>
                                        <arguents>docs/chapter-01-introduction.md</arguents>
                                        <arguents>docs/chapter-00-chapter_title.md</arguents>
                                        <argument>--resource-path=docs/</argument>
                                        <argument>--toc</argument>
                                        <argument>--toc-depth=2</argument>
                                        <argument>--pdf-engine=context</argument>
                                        <argument>-t</argument>
                                        <argument>pdf</argument>
                                        <argument>-o</argument>
                                        <argument>target/${project.name}-doc-${project.version}.pdf</argument>
                                        <argument>--template</argument>
                                        <argument>eisvogel</argument>
                                        <argument>--listings</argument>
                                    </arguments>
                                </configuration>
                                <goals>
                                    <goal>exec</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
        <profile>
            <id>create-exe</id>
            <build>
                <plugins>
                    <!-- create a Windows EXE -->
                    <!-- https://github.com/lukaszlenart/launch4j-maven-plugin/blob/master/src/main/resources/README.adoc -->
                    <!-- see http://launch4j.sourceforge.net/ -->
                    <plugin>
                        <groupId>com.akathist.maven.plugins.launch4j</groupId>
                        <artifactId>launch4j-maven-plugin</artifactId>
                        <version>1.7.25</version>
                        <executions>
                            <execution>
                                <id>l4j-clui</id>
                                <phase>package</phase>
                                <goals>
                                    <goal>launch4j</goal>
                                </goals>
                                <configuration>
                                    <headerType>gui</headerType>
                                    <jar>${project.build.directory}/${project.name}-${project.version}-shaded.jar</jar>
                                    <outfile>${project.build.directory}/${project.name}.exe</outfile>
                                    <downloadUrl>http://java.com/download</downloadUrl>
                                    <classPath>
                                        <mainClass>${mainClass}</mainClass>
                                        <preCp>anything</preCp>
                                    </classPath>
                                    <icon>src/main/resources/res/app-icon.ico</icon>
                                    <jre>
                                        <minVersion>${maven.compiler.source}</minVersion>
                                        <jdkPreference>preferJre</jdkPreference>
                                    </jre>
                                    <versionInfo>
                                        <fileVersion>1.0.0.0</fileVersion>
                                        <txtFileVersion>${project.version}</txtFileVersion>
                                        <fileDescription>${project.name}</fileDescription>
                                        <copyright>${project.inceptionYear} - [AuthorCompanyUrl]</copyright>
                                        <productVersion>1.0.0.0</productVersion>
                                        <txtProductVersion>1.0.0.0</txtProductVersion>
                                        <productName>${project.name}</productName>
                                        <companyName>[AuthorCompany]</companyName>
                                        <internalName>${project.name}</internalName>
                                        <originalFilename>${project.name}</originalFilename>
                                    </versionInfo>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>

</project>