JUnit 5 Tutorial: Running Unit Tests With Maven

If you want to learn how you can work smarter and save time when you are writing tests with JUnit 5, you should take a look at my Introduction to JUnit 5 course. It has 24 lessons, 47 exercises, and 13 quizzes.

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:

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.8.2</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

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:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.22.2</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 ensured that the junit-jupiter-engine dependency is found from the classpath 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 the 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 only because I want to 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.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.

If you want to get access to up-to-date material which helps you to work smarter and save time when you are writing tests with JUnit 5, you should take a look at my Introduction to JUnit 5 course. It has 24 lessons, 47 exercises, and 13 quizzes.

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.

35 comments… add one
  • Brecht Mar 22, 2018 @ 15:06

    Cheers! I got it working thanks to your article. :)

    • Petri Mar 23, 2018 @ 9:52

      Hi,

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

    • Milind Jun 8, 2020 @ 19:34

      I have added surefire dependency still it's not detecting and running test cases

      • Petri Jun 8, 2020 @ 22:07

        Hi,

        It's kind hard to figure out what's wrong without seeing your POM file and your test code. That said, I would check the following things:

        • If you use the default configuration of the Maven Surefire plugin, make sure that the names of your test classes follow the naming convention which I mentioned earlier on this blog post.
        • Make sure that your tests use the correct imports (in other words, they import org.junit.jupiter.Test instead of org.junit.Test). This might sound stupid but I have made this mistake several times and that's why this is one of the first things I check when my tests aren't run.

        If you can share a link to a sample project that helps me to reproduce your problem, I am more than happy to take a look at it.

  • Tong Apr 21, 2018 @ 4:49

    Thanks! Your article helps me.

    • Petri May 2, 2018 @ 21:13

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

  • Pete Jul 1, 2018 @ 5:40

    Nice article, thanks!

    • Petri Jul 3, 2018 @ 21:47

      You are welcome!

  • Yook Sep 7, 2018 @ 12:06

    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

    • Petri Sep 7, 2018 @ 14:28

      Hi,

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

      • John Oct 28, 2018 @ 1:41

        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 |
        +-------------------------------------------------------------------------------+

        • Petri Nov 14, 2018 @ 21:10

          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.

  • Pramod Yadav Mar 8, 2019 @ 18:47

    Thank you for this article. I added Junit5 in my tests and saw that none of them were running from mvn command line. I added the dependencies that you mentioned about the engine "junit-jupiter-engine" and surefire plugin "maven-surefire-plugin" in the build section; and the tests were successful from the command line.
    A big thanks for this post!

    • Petri Kainulainen Mar 10, 2019 @ 20:50

      You are welcome!

  • Anonymous Mar 13, 2019 @ 12:25

    Thank u very much!

  • GradedJestRisk Apr 7, 2019 @ 20:41

    Good job. Please note I had to correct some lowercase to uppercase to make it work.
    Should work on Windows anyway, this issue shows up for Linux users only

    • Petri Apr 8, 2019 @ 12:12

      Hi,

      When you mentioned that you had to change some lowercase letters to uppercase, were you talking about the example application of this blog post? If so, could you list your changes here so that I can make the same changes to the example application?

      • GradedJestRisk Apr 8, 2019 @ 15:03

        Hi Petri,
        I'm sorry about that, your script is perfectly okay.
        GitHub Wiki, when using markup in MeadiWiki, alter the case.
        Pierre

        • Petri Apr 9, 2019 @ 16:40

          Hi Pierre,

          No problem. I was just wondering if I have made a mistake because I am using OS X with case insensitive file system (I have to use a few old programs which won't work if I use the case sensitive file system).

  • Gopal Jun 7, 2019 @ 3:03

    This helped immensely to configure my Junit properly (I did not know about the engine dependency and was getting "no test runner found" errors). I have not configured surefire maven plugin yet. In eclipse, I am able to run the junit tests for now.

    One thing I'm still confused about ... eclipse comes with an embedded maven plugin. So do I still need to install maven (i.e apt-get install maven) and will this play nicely with eclipses' maven or will the two conflict with each other.

    • Petri Jun 7, 2019 @ 17:31

      Hi Gopal,

      First, I am happy to that this blog post was useful to you!

      Second, I have no experience from Eclipse, but I assume that the embedded Maven works only if you launch your Maven build inside Eclipse. In other words, you cannot use it at command prompt. If you need to run Maven at command prompt, you have to install Maven. Unfortunately, this means that something that's working at command prompt might not work in Eclipse (and vice versa). However, I assume these conflicts are quite rare, especially if your build doesn't require "heavy customization".

  • Marcos Apr 10, 2020 @ 1:06

    Thanks, it worked!

    Greetings from Argentina.

    • Petri Jun 3, 2020 @ 23:35

      You are welcome!

  • Katie Jun 3, 2020 @ 16:13

    This was extremely helpful, thank you very much.

    • Petri Jun 3, 2020 @ 23:35

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

  • Antonio Jan 19, 2022 @ 20:56

    Great article. It helps me a lot!. Thank you

    • Petri Jan 19, 2022 @ 22:12

      You are welcome!

  • Developeronthego Jun 30, 2022 @ 17:43

    In my opinion, Spock framework today destroys junit 5 simplicity and speed of writing tests

  • EsteBusta Aug 12, 2022 @ 5:29

    Hi, i have a silly question, if we are using a lower version of the maven surefire plugin than the suggested, can we still use the junit5 runner while compiling with maven?

    • Petri Aug 12, 2022 @ 15:13

      Hi,

      If you are using the Maven Surefire Plugin 2.21.0 or older and you want to run tests which use JUnit 5, you have to make some changes to the configuration of the Maven Surefire Plugin. If you want to get more information about these configuration changes, you should read this blog post.

      • EsteBusta Aug 12, 2022 @ 16:00

        Thank you Petri, really useful blogs

        • Petri Aug 12, 2022 @ 18:13

          You are welcome!

  • Ahmet Oct 29, 2023 @ 0:09

    This helped me. Thank you.

    • Petri Oct 29, 2023 @ 18:07

      You are welcome.

Leave a Reply