Learn to write tests which are easy to read and write: get started with Spock Framework.

JUnit 5 Tutorial: Running Unit Tests With Maven

This blog post describes how we can get the required dependencies with Maven, explains how we can configure the Maven Surefire Plugin, and demonstrates 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 declaring the junit-jupiter-api (version 5.0.1) dependency in our pom.xml file. This dependency provides the public API for writing tests and extensions.

We can add the required dependencies to our POM file by adding the following dependency to the dependencies section of our POM file:

<dependency>
	<groupId>org.junit.jupiter</groupId>
	<artifactId>junit-jupiter-api</artifactId>
	<version>5.0.1</version>
	<scope>test</scope>
</dependency>

If we are using an IDE that is bundled with an older JUnit 5 version, it throws an exception when we try to run our unit tests by using our IDE. We can fix this problem by adding the following dependencies to our POM file:

  • The junit-jupiter-engine (version 5.0.1) dependency contains the implementation of the JUnit Jupiter test engine. This dependency is required only at runtime.
  • The junit-vintage-engine (version 4.12.1) dependency adds support for unit tests that use JUnit 4 or JUnit 3. Again, this dependency is required only at runtime.
  • The junit-platform-launcher (version 1.0.1) dependency provides a public API for configuring and launching tests. This API is typically used by IDEs and build tools.
  • The junit-platform-runner (version 1.0.1) dependency allows us to run tests and test suites in a JUnit 4 environment.

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

<dependency>
	<groupId>org.junit.jupiter</groupId>
	<artifactId>junit-jupiter-api</artifactId>
	<version>5.0.1</version>
	<scope>test</scope>
</dependency>
	<dependency>
	<groupId>org.junit.jupiter</groupId>
	<artifactId>junit-jupiter-engine</artifactId>
	<version>5.0.1</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.junit.vintage</groupId>
	<artifactId>junit-vintage-engine</artifactId>
	<version>4.12.1</version>
	<scope>test</scope>
	</dependency>
<dependency>
	<groupId>org.junit.platform</groupId>
	<artifactId>junit-platform-launcher</artifactId>
	<version>1.0.1</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.junit.platform</groupId>
	<artifactId>junit-platform-runner</artifactId>
	<version>1.0.1</version>
	<scope>test</scope>
</dependency>

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 have to declare the maven-surefire-plugin (version 2.19.1) in our pom.xml file and configure the dependencies of this plugin. We have to declare the following dependencies:

  • The junit-platform-surefire-provider (version 1.0.1) dependency allows us to run tests that use either the “old” JUnit (3 or 4) or JUnit 5.
  • If we want to run tests that use either JUnit 3 or 4, we have to declare the junit-vintage-engine (version 4.12.1) dependency.
  • If we want to run tests that use JUnit 5, we have to declare the junit-jupiter-engine (version 5.0.1) dependency.

Because we want to run only unit tests which use JUnit 5, we have to add the following snippet to the plugins section of our POM file:

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-surefire-plugin</artifactId>
	<version>2.19.1</version>
	<dependencies>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-surefire-provider</artifactId>
			<version>1.0.1</version>
		</dependency>
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-engine</artifactId>
			<version>5.0.1</version>
		</dependency>
	</dependencies>
</plugin>
There are two things I want to point out:

  • The junit-platform-surefire-provider doesn’t work with the Maven Surefire Plugin 2.20 because the Maven Surefire Plugin 2.20 has a memory leak.
  • I think that we should configure the runtime dependencies when we declare the dependencies of the Maven Surefire Plugin. This allows us to separate the compile-time and runtime dependencies. However, if our IDE is bundled with an older JUnit 5 version, we don’t have to declare these dependencies for the second time.

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 Tests

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 one test method to created class. This test method simply writes a message to System.out. The source code of our test class looks as follows:

import org.junit.jupiter.api.Test;

class JUnit5ExampleTest {

    @Test
    void justAnExample() {
        System.out.println("This test method should be run");
    }
}
I won’t describe this test class in this blog post because my upcoming blog posts will provide introduction to JUnit 5 test classes.

Also, we shouldn’t write tests which write messages to System.out. I use this technique here only because it is an easy to way see that our test method is run.

Let’s move on and find out how we can run our unit tests.

Running Unit Tests With Maven

We can run our unit tests with Maven by running the following command at command prompt:

mvn clean test

When we run our unit tests, we should see the following output:

$ mvn clean test

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running net.petrikainulainen.junit5.JUnit5ExampleTest
This test method should be run
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] ------------------------------------------------------------------------

As we can see, the Maven Surefire Plugin runs our unit test. Let’s summarize what we learned from this blog post.

Summary

This blog post has taught us five things:

  • The junit-jupiter-api dependency allows us to write tests and extensions which use JUnit 5.
  • The junit-platform-surefire-provider module allows us to run our tests with the Maven Surefire Plugin.
  • The junit-jupiter-engine dependency allows us to run tests which use JUnit 5.
  • The junit-vintage-engine dependency allows us to run tests which use JUnit 3 or 4.
  • We have to ensure that the required test engines are in the classpath when we run our tests. This means that we have to configure them when we declare the dependencies of the Maven Surefire Plugin.

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

About the Author

Petri Kainulainen is passionate about software development and continuous improvement. He is specialized in software development with the Spring Framework and is the author of Spring Data book.

About Petri Kainulainen →

1 comment… add one

    Leave a Comment