JUnit 5 Tutorial

1. Overview

In this post, we will create a simple Maven project to demonstrate how to create JUnit 5 test cases. We will see how to run a JUnit 5 example with Maven and also learn new JUnit 5 features.

JUnit 5 supports JDK 8 and above so make sure that the minimum JDK 8 is installed.

2. Create Simple Maven Project

Let's create a simple maven project with the following below command:

mvn archetype:generate -DgroupId=org.yourcompany.project -DartifactId=junit5-maven

Once the Maven build is successful then it will create a below default folder structure.

src/main

src/main/java – Java Source code packages and classes
src/main/resources – NON-Java Resources, such as property files and Spring configuration

test

src/test/java – Test Source code packages and classes
src/test/resources – NON-Java Resources, such as property files and Spring configuration

Create package structure as given below:

── pom.xml
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── javadevelopersguide
    │   │           └── junit
    │   │               └── BasicSalaryCalculator.java
    │   ├── resources
    └── test
        ├── java
        │   └── com
        │       └── javadevelopersguide
        │           └── junit
        │               └── BasicSalaryCalculatorTest.java
        └── resources

3. JUnit 5 Maven Dependency

There are 2 dependencies we need to specify in the pom.xml file in order to run JUnit 5 with Maven.

3.1. JUnit 5 Library Dependency

The minimum JUnit 5 Maven dependency is: junit-jupiter-engine

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.0.0</version>
    <scope>test</scope>
</dependency>

3.2. JUnit 5 Maven Surefire Provider

<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.19</version>
    <dependencies>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-surefire-provider</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>

3.3. The Full pom.xml File

Here is the complete pom.xml for your reference:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
 
   <groupId>com.mycompany</groupId>
   <artifactId>junit5-maven</artifactId>
   <version>1.0-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <java.version>1.8</java.version>
      <junit.version>4.12</junit.version>
      <junit.jupiter.version>5.0.0</junit.jupiter.version>
      <junit.vintage.version>${junit.version}.0</junit.vintage.version>
      <junit.jupiter.version>5.0.0</junit.jupiter.version>
      <junit.platform.version>1.0.0</junit.platform.version>
   </properties>
 
   <build>
      <plugins>
         <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.1</version>
            <configuration>
               <source>${java.version}</source>
               <target>${java.version}</target>
            </configuration>
         </plugin>
         <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.19</version>
            <dependencies>
               <dependency>
                  <groupId>org.junit.platform</groupId>
                  <artifactId>junit-platform-surefire-provider</artifactId>
                  <version>${junit.platform.version}</version>
               </dependency> 
            </dependencies>
         </plugin>
      </plugins>
   </build>
 
   <dependencies>
      <dependency>
         <groupId>org.junit.jupiter</groupId>
         <artifactId>junit-jupiter-engine</artifactId>
         <version>${junit.jupiter.version}</version>
         <scope>test</scope>
      </dependency>
      <!-- To run tests on IDE such as Eclipse, Intellij -->
      <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>${junit.version}</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.junit.platform</groupId>
         <artifactId>junit-platform-runner</artifactId>
         <version>${junit.platform.version}</version>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.junit.vintage</groupId>
         <artifactId>junit-vintage-engine</artifactId>
         <version>${junit.vintage.version}</version>
         <scope>test</scope>
      </dependency>
   </dependencies>
 
</project>

4. Create BasicSalaryCalculator.java class

public class BasicSalaryCalculator {
	private double basicSalary;

	public double getBasicSalary() {
		return basicSalary;
	}

	public void setBasicSalary(double basicSalary) {
		if (basicSalary < 0) {
			throw new IllegalArgumentException("Negative salary is invalid.");
		}
		this.basicSalary = basicSalary;
	}

	public double getGrossSalary() {
		return this.basicSalary + getSocialInsurance() + getAdditionalBonus();
	}

	public double getSocialInsurance() {
		return this.basicSalary * 25 / 100;
	}

	public double getAdditionalBonus() {
		return this.basicSalary / 10;
	}
}

5. Create BasicSalaryCalculatorTest.java Class

Let's write unit test cases for BasicSalaryCalculator class:

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

public class BasicSalaryCalculatorTest {
	private BasicSalaryCalculator basicSalaryCalculator;

	@BeforeEach
	void init() {
		basicSalaryCalculator = new BasicSalaryCalculator();
	}

	@Test
	void testBasicSalaryWithValidSalary() {
		double basicSalary = 4000;
		basicSalaryCalculator.setBasicSalary(basicSalary);

		double expectedSocialInsurance = basicSalary * 0.25;
		assertEquals(expectedSocialInsurance, basicSalaryCalculator.getSocialInsurance());

		double expectedAddionalBonus = basicSalary * 0.1;
		assertEquals(expectedAddionalBonus, basicSalaryCalculator.getAdditionalBonus());

		double expectedGross = basicSalary + expectedSocialInsurance + expectedAddionalBonus;
		assertEquals(expectedGross, basicSalaryCalculator.getGrossSalary());

	}

	@DisplayName("Test BasicSalaryCalculator with invalid salary")
	@Test
	void testBasicSalaryWithInValidSalary() {

		double basicSalary = -100;
		assertThrows(IllegalArgumentException.class, () -> {
			basicSalaryCalculator.setBasicSalary(basicSalary);
		});

	}

	@AfterEach
	void tearDown() {
		basicSalaryCalculator = null;
	}
}