Improve maven setting up section in the user guide

[raniejade]

We only have this there:

Maven

JUnit provides support for Maven.

...
<dependency>
  <groupId>org.jetbrains.spek</groupId>
  <artifactId>spek-api</artifactId>
  <version>1.1.5</version>
  <type>pom</type>
</dependency>

[pemistahl]

I recently had the same problem that the existing documentation is not enough to get a working Maven build, in my case combining it with Kluent as assertion library. After discovering a blog post from 2016, I could finally come up with a working POM file.

The missing key points are the following:

• The test classes are named ...Spec.kt or ...Spek.kt and not ...Test.kt as would usually be the case when you work with JUnit. Therefore, you need to provide a configuration for the Maven surefire plugin so that the differently named test classes are recognized when executing mvn test. Otherwise, they are simply ignored.
• The JUnit 5 platform engine is not directly supported by the surefire plugin. So one needs to add the junit-platform-surefire-provider dependency to the surefire plugin.
• The newest surefire plugin version 2.20.1 has a bug and does not work. It simply ignores all tests and returns a BUILD SUCCESS at the end. Switching to 2.20.0 solves the problem. You don't wanna know how much time I needed to figure this out. ;-)

So, the relevant parts of a working POM file that works for me are the following:

<properties>
    <kotlin.version>1.2.21</kotlin.version>
    <spek.version>1.1.5</spek.version>
    <kluent.version>1.34</kluent.version>
    <!-- Surefire plugin version 2.20.1 does not recognize tests, must use 2.20.0 -->
    <maven.surfire.plugin.version>2.20</maven.surfire.plugin.version>
    <junit.platform.surefire.provider.version>1.0.3</junit.platform.surefire.provider.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-stdlib-jdk8</artifactId>
        <version>${kotlin.version}</version>
    </dependency>
    <!-- explicit dependency on kotlin-reflect due to runtime version conflicts -->
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-reflect</artifactId>
        <version>${kotlin.version}</version>
    </dependency>
    <dependency>
        <groupId>org.jetbrains.spek</groupId>
        <artifactId>spek-api</artifactId>
        <version>${spek.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.jetbrains.spek</groupId>
        <artifactId>spek-junit-platform-engine</artifactId>
        <version>${spek.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.amshove.kluent</groupId>
        <artifactId>kluent</artifactId>
        <version>${kluent.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
    <testSourceDirectory>${project.basedir}/src/test/kotlin</testSourceDirectory>

    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>compile</id>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
                <execution>
                    <id>test-compile</id>
                    <goals>
                        <goal>test-compile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${maven.surfire.plugin.version}</version>
            <configuration>
                <includes>
                    <!-- change this pattern to however you name your test classes -->
                    <include>**/*Spec*</include>
                </includes>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.junit.platform</groupId>
                    <artifactId>junit-platform-surefire-provider</artifactId>
                    <version>${junit.platform.surefire.provider.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

<repositories>
    <repository>
        <id>jcenter</id>
        <name>JCenter</name>
        <url>https://jcenter.bintray.com/</url>
    </repository>
</repositories>

You can see the entire POM file from my project here. Hope this helps.

[piacenti]

For more recent versions of the surefire plugin you will see that junit-platform-surefire-provider is deprecated and will be removed. I got this to work without warnings.

<plugin>
	<artifactId>maven-surefire-plugin</artifactId>
	<version>2.22.1</version>
	<dependencies>
		<dependency>
			<groupId>org.apache.maven.surefire</groupId>
			<artifactId>surefire-junit-platform</artifactId>
			<version>2.22.1</version>
		</dependency>
	</dependencies>
</plugin>