JUnit 5 Tutorial: Running Unit Tests With Maven

This blog post describes how we can create a Maven project that can compile and run unit tests which use JUnit 5. After we have finished this blog post, we:

• Can get the required dependencies with Maven.
• Understand how we can configure the Maven Surefire Plugin.
• Know how we can run our unit tests with Maven.

Let’s start by getting the required dependencies.

Getting the Required Dependencies

We can get the required dependencies by adding the junit-jupiter (version 5.8.2) dependency to the test scope. This is an aggregator artifact which simplifies the dependency management because it has the following transitive dependencies:

• The junit-jupiter-api dependency (compile scope) provides the public API for writing tests and extensions.
• The junit-jupiter-params dependency (compile scope) provides support for writing parameterized tests.
• The junit-jupiter-engine dependency (runtime scope) contains the implementation of the JUnit Jupiter test engine that runs our unit tests. If we add this dependency to our classpath, the Maven Surefire and Failsafe plugins (version 2.22.0 or newer) can run tests which use JUnit 5.

After we have added the required dependency to our POM file, its dependencies section looks as follows:

1<dependencies>
2    <dependency>
3        <groupId>org.junit.jupiter</groupId>
4        <artifactId>junit-jupiter</artifactId>
5        <version>5.8.2</version>
6        <scope>test</scope>
7    </dependency>
8</dependencies>

After we have declared the required dependencies, we have to configure the Maven Surefire Plugin. Let’s find out how we can do it.

Configuring the Maven Surefire Plugin

We can run our unit tests by using the Maven Surefire Plugin. Because we want to use its native JUnit 5 support, we have to use the version 2.22.0 (or newer).

After we have ensured that our unit tests are run by the Maven Surefire Plugin 2.22.2, the build section of our POM file looks as follows:

1<build>
2    <plugins>
3        <plugin>
4            <groupId>org.apache.maven.plugins</groupId>
5            <artifactId>maven-surefire-plugin</artifactId>
6            <version>2.22.2</version>
7        </plugin>
8    </plugins>
9</build>

We have now created a Maven project that can run unit tests which use JUnit 5. Let’s move on and write a simple unit test with JUnit 5.

Writing a Simple Unit Test

Before we can write unit tests which use JUnit 5, we have to know these two things:

• The src/test/java directory contains the source code of our unit tests.
• The src/test/resources directory contains the resources of our unit tests.

Let’s create a new test class and add an empty test method to the created class. After we have written our test class, its source code looks as follows:

1import org.junit.jupiter.api.Test;
2
3class JUnit5ExampleTest {
4
5    @Test
6    void justAnExample() {
7
8    }
9}

Next, we will find out how we can run our unit tests.

Running Unit Tests With Maven

We can run our unit tests with Maven by using the command: mvn clean test. When we run this command at command prompt, we should see that the Maven Surefire Plugin runs our unit tests.

[INFO]
[INFO] --- maven-surefire-plugin:2.22.2:test (default-test) @ running-unit-tests ---
[INFO]
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running net.petrikainulainen.junit5.JUnit5ExampleTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.033 sec -
in net.petrikainulainen.junit5.JUnit5ExampleTest

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

We can now create a Maven project that compiles and runs unit tests which use JUnit 5. Also, we know how we can run our unit tests with Maven. Let’s summarize what we learned from this blog post.

Summary

This blog post has taught us six things:

• The junit-jupiter-api dependency provides the public API that allows us to write tests and extensions which use JUnit 5.
• The junit-jupiter-engine dependency ensures that the Maven Surefire Plugin can run tests which use JUnit 5.
• The junit-jupiter dependency is an aggregator artifact which simplifies the dependency management because it ensures that the required dependencies are found from the classpath.
• The Maven Surefire Plugin 2.22.0 (or newer) provides native support for JUnit 5.
• If we want to use the native JUnit 5 support of the Maven Surefire Plugin, we must ensure that at least one test engine implementation is found from the classpath.
• We can run our unit tests by using the command: mvn clean test.

P.S. You can get the example application of this blog post from Github.