Are you tired of writing tests which have a lot of boilerplate code? If so, get started with Spock Framework >>

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 these two dependencies to the test scope:

  • The junit-jupiter-api (version 5.4.0). This dependency provides the public API for writing tests and extensions.
  • The junit-jupiter-engine (version 5.4.0). This dependency contains the implementation of the JUnit Jupiter test engine that runs our unit tests.

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

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.4.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>5.4.0</version>
        <scope>test</scope>
    </dependency>
</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

Because we don’t want to specify the dependencies of the Maven Surefire Plugin, we have to use its native JUnit 5 support. This means that we have to use the Maven Surefire Plugin 2.22.0 (or newer).

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

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.22.1</version>
        </plugin>
    </plugins>
</build>
There are two things I want to point out:

First, 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. That’s why we added the junit-jupiter-engine dependency to the test scope when we configured the dependencies of our Maven build.

Second, if we use the default configuration of the Maven Surefire Plugin, it runs all test methods found from a test class if the name of the test class:

  • Starts or ends with the string: Test.
  • Ends with the string: Tests.
  • Ends with the string: TestCase.

Additional Reading:

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 created class. After we have written our test class, its source code looks as follows:

import org.junit.jupiter.api.Test;

class JUnit5ExampleTest {

    @Test
    void justAnExample() {

    }
}
If you want to get more information about JUnit 5 test classes, you should read this blog post. Also, it’s not a good idea to write empty test methods. I use this technique here because I want to only demonstrate that our test method is run by the Maven Surefire Plugin.

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.1: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 five 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 allows us to run tests which use JUnit 5.
  • The Maven Surefire Plugin 2.22.0 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.

11 comments… add one
  • Cheers! I got it working thanks to your article. :)

    Reply
    • Hi,

      It’s good to hear that this blog post was useful to you.

      Reply
  • Thanks! Your article helps me.

    Reply
    • You are welcome. I am happy to hear that this blog post was useful to you.

      Reply
  • Nice article, thanks!

    Reply
    • You are welcome!

      Reply
  • maven-surefire-plugin 2.22.0 now can run without dependency.
    Thank for article anyway

    ref : https://junit.org/junit5/docs/current/user-guide/#running-tests-build-maven

    Reply
    • Hi,

      Thanks for the tip. I will update this blog post when I update this tutorial to cover JUnit 5.3.0.

      Reply
      • As yook said, maven spits out a warning now

        +——————————————————————————-+
        | WARNING: |
        | The junit-platform-surefire-provider has been deprecated and is scheduled to |
        | be removed in JUnit Platform 1.4. Please use the built-in support in Maven |
        | Surefire >= 2.22.0 instead. |
        | » https://junit.org/junit5/docs/current/user-guide/#running-tests-build-maven |
        +——————————————————————————-+

        Reply
        • Hi,

          Thanks for the tip. I should probably update this tutorial as soon as possible, but I am afraid that I don’t have time to do it before the Christmas holiday.

          Reply

Leave a Comment