Running tests in JUnit 5


Learn how to run tests in JUnit 5 in this tutorial by Boni García, an active member on the free open source software (FOSS) community, who owns the open source projects WebDriverManager and selenium-jupiter (JUnit 5 extension for Selenium).

JUnit 5 was designed to be modern (that is, using Java 8 and Java 9 compliant from the very beginning) and modular. The three major components within JUnit 5 are Jupiter, Platform (foundation for any testing framework executed in the JVM), and Vintage (integration with legacy JUnit 3 and 4 tests).

Jupiter tests can be executed in several ways:

  • Using a build tool: Maven (implemented in the module junit-plaform-surefire-provider) or Gradle (implemented in the module junit-platform-gradle-plugin)
  • Using the Console Launcher: A command-line Java application that allows launching the JUnit Platform from the console
  • Using an IDE: IntelliJ (since version 2016.2) and Eclipse (since version 4.7, Oxygen)

Due to the modular architecture of JUnit 5, you need to include three dependencies in your projects: one for the Test API (to implement tests), another for the Test Engine (to run tests), and the last one of the Test Launcher (to discover tests).

Jupiter tests with Maven

In order to run Jupiter tests within a Maven project, you need to configure the pom.xml file. First, you need to include the junit-jupiter-api module as a dependency. This is needed to write your test with a test scope. In general, it is recommended to use the latest version of the dependencies. You can check out the version of your dependency on Maven Central (http://search.maven.org/).

<dependencies>

   <dependency>

      <groupId>org.junit.jupiter</groupId>

      <artifactId>junit-jupiter-api</artifactId>

      <version>${junit.jupiter.version}</version>

      <scope>test</scope>

   </dependency>

</dependencies>

Now, the maven-surefire-plugin has to be declared. Internally, this plugin needs two dependencies: the Test Launcher (junit-platform-surefire-provider) and the Test Engine (junit-jupiter-engine):

<build>

   <plugins>

      <plugin>

         <artifactId>maven-surefire-plugin</artifactId>

         <version>${maven-surefire-plugin.version}</version>

         <dependencies>

             <dependency>

                <groupId>org.junit.platform</groupId>

                <artifactId>junit-platform-surefire-provider</artifactId>

                <version>${junit.platform.version}</version>

            </dependency>

            <dependency>

               <groupId>org.junit.jupiter</groupId>

               <artifactId>junit-jupiter-engine</artifactId>

               <version>${junit.jupiter.version}</version>

            </dependency>

         </dependencies>

      </plugin>

   </plugins>

 </build>

Now you need to create a Jupiter test case. The test executed here is the simplest one to demonstrate the execution of the JUnit 5 framework. A Jupiter test, in its minimal expression, is just a Java class in which one (or more) of its methods are annotated with @Test (package org.junit.jupiter.api). The following snippet provides an example:

package io.github.bonigarcia;

 

import static org.junit.jupiter.api.Assertions.assertEquals;

 

import org.junit.jupiter.api.Test;

 

class MyFirstJUnit5Test {

 

   @Test

void myFirstTest() {

       String message = “1+1 should be equal to 2”;

       System.out.println(message);

assertEquals(2, 1 + 1, message);

   }

 

}

JUnit requires Java 8 (or higher) at runtime. However, you can still test code that has been compiled with the previous versions of Java. As shown in the next image, this test can be executed using the command mvn test:

Running tests in JUnit 5 1

Running Jupiter tests with Maven

Jupiter tests with Gradle

Now, you’ll study the same example but executed with Gradle. Therefore, you need to configure the build.gradle file. In this file, you’ll need to define:

  • The dependency for the Jupiter API (junit-jupiter-api).
  • The dependency for the Test Engine (junit-jupiter-engine).
  • The plugin for the Test Launcher (junit-platform-gradle-plugin).

The complete source of build.gradle is as follows:

buildscript {

   repositories {

      mavenCentral()

   }

   dependencies {

      classpath(“org.junit.platform:junit-platform-gradle-plugin:${junitPlatformVersion}”)

   }

}

repositories {

   mavenCentral()

}

 

apply plugin: ‘java’

apply plugin: ‘eclipse’

apply plugin: ‘idea’

apply plugin: ‘org.junit.platform.gradle.plugin’

 

compileTestJava {

   sourceCompatibility = 1.8

   targetCompatibility = 1.8

   options.compilerArgs += ‘-parameters’

}

 

dependencies {

   testCompile(“org.junit.jupiter:junit-jupiter-api:${junitJupiterVersion}”)

   testRuntime(“org.junit.jupiter:junit-jupiter-engine:${junitJupiterVersion}”)

}

Now, you can use the gradle test command to run your Jupiter test from the command line with Gradle:

Running tests in JUnit 5 2

Running Jupiter tests with Gradle

Legacy tests with Maven

You need to use the following code to run the legacy test (JUnit 4 in this case) in the JUnit Platform:

package io.github.bonigarcia;

 

import static org.junit.Assert.assertEquals;

 

import org.junit.Test;

 

public class LegacyJUnit4Test {

 

   @Test

public void myFirstTest() {

      String message = “1+1 should be equal to 2”;

      System.out.println(message);

assertEquals(message, 2, 1 + 1);

   }

 

}

In Maven, you first need to include the old JUnit 4 dependency in your pom.xml, as follows:

<dependencies>

   <dependency>

      <groupId>junit</groupId>

      <artifactId>junit</artifactId>

      <version>4.12</version>

      <scope>test</scope>

   </dependency>

</dependencies>

Then, you need to include maven-surefire-plugin, using the dependencies, Test Engine (junit-vintage-engine) and Test Launcher (junit-platform-surefire-provider) for the plugin:

<build>

   <plugins>

      <plugin>

         <artifactId>maven-surefire-plugin</artifactId>

         <version>${maven-surefire-plugin.version}</version>

         <dependencies>

            <dependency>

               <groupId>org.junit.platform</groupId>

               <artifactId>junit-platform-surefire-provider</artifactId>

               <version>${junit.platform.version}</version>

            </dependency>

            <dependency>

                <groupId>org.junit.vintage</groupId>

                <artifactId>junit-vintage-engine</artifactId>

                <version>${junit.vintage.version}</version>

            </dependency>

         </dependencies>

      </plugin>

   </plugins>

</build>

Now, you can use the mvn test command to run your Jupiter test from the command line with Maven:

Running tests in JUnit 5 3

Running legacy tests with Maven

Legacy tests with Gradle

If you want to execute the same test presented in the example before (io.github.bonigarcia.LegacyJUnit4Test) using Gradle, you need to include the following in your build.gradle file:

  • The dependency for JUnit 4.12
  • The dependency for the Test Engine (junit-vintage-engine)
  • The plugin for the Test Launcher (junit-platform-gradle-plugin)

Now, the complete source of build.gradle would be as follows:

buildscript {

   repositories {

      mavenCentral()

   }

   dependencies {

      classpath(“org.junit.platform:junit-platform-gradle-plugin:${junitPlatformVersion}”)

   }

}

 

repositories {

   mavenCentral()

}

 

apply plugin: ‘java’

apply plugin: ‘eclipse’

apply plugin: ‘idea’

apply plugin: ‘org.junit.platform.gradle.plugin’

 

compileTestJava {

   sourceCompatibility = 1.8

   targetCompatibility = 1.8

   options.compilerArgs += ‘-parameters’

}

 

dependencies {

   testCompile(“junit:junit:${junitLegacy}”)

   testRuntime(“org.junit.vintage:junit-vintage-engine:${junitVintageVersion}”)

}

The execution from the command line would be as follows:

Running tests in JUnit 5 4

Running Legacy tests with Gradle

The ConsoleLauncher

The ConsoleLauncher is a command-line Java application that allows launching the JUnit Platform from the console. For example, it can be used to run Vintage and Jupiter tests from the command line.

An executable JAR with all dependencies included is published in the central Maven repository under the junit-platform-console-standalone artifact. The standalone Console Launcher can be executed as follows:

java -jar junit-platform-console-standalone-version.jar <Options>

The example GitHub repository junit5-console-launcher contains a simple example for the use of the Console Launcher. As depicted in the following image, a run configuration entry has been created in Eclipse, running the main class, org.junit.platform.console.ConsoleLauncher. Then, the test class name is passed as an argument using the option –select-class and the qualified class name (in this example, io.github.bonigarcia.EmptyTest). After this, you can run the application obtaining the test result in the integrated console of Eclipse:

Running tests in JUnit 5 5

Example of ConsoleLauncher in Eclipse

Jupiter tests in JUnit 4

JUnit 5 has been designed to be forward and backward compatible. The Vintage component supports running of legacy code on JUnit 3 and 4. On the other hand, JUnit 5 provides a JUnit 4 runner that allows running JUnit 5 in IDEs and build systems that support JUnit 4 but does not support the new JUnit Platform 5 directly.

Here is an example. Suppose you want to run a Jupiter test in an IDE that does not support JUnit 5, for example, an old version of Eclipse. In this case, you need to annotate your Jupiter test with @RunWith(JUnitPlatform.class). The JUnitPlatform runner is a JUnit 4-based runner, which enables you to run any test whose programming model is supported on the JUnit Platform in a JUnit 4 environment. Therefore, your test would result as follows:

package io.github.bonigarcia;

 

import static org.junit.jupiter.api.Assertions.assertEquals;

 

import org.junit.jupiter.api.Test;

import org.junit.platform.runner.JUnitPlatform;

import org.junit.runner.RunWith;

 

@RunWith(JUnitPlatform.class)

public class JUnit5CompatibleTest {

 

   @Test

void myTest() {

      String message = “1+1 should be equal to 2”;

      System.out.println(message);

      assertEquals(2, 1 + 1, message);

   }

 

}

If this test is contained in a Maven project, your pom.xml should contain the following dependencies:

<dependencies>

   <dependency>

      <groupId>org.junit.jupiter</groupId>

      <artifactId>junit-jupiter-api</artifactId>

      <version>${junit.jupiter.version}</version>

      <scope>test</scope>

    </dependency>

    <dependency>

       <groupId>org.junit.jupiter</groupId>

       <artifactId>junit-jupiter-engine</artifactId>

       <version>${junit.jupiter.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>

 </dependencies>

On the other hand, for a Gradle project, your build.gradle should be as follows:

buildscript {

   repositories {

      mavenCentral()

   }

   dependencies {

      classpath(“org.junit.platform:junit-platform-gradle-plugin:${junitPlatformVersion}”)

   }

}

 

repositories {

   mavenCentral()

}

 

apply plugin: ‘java’

apply plugin: ‘eclipse’

apply plugin: ‘idea’

apply plugin: ‘org.junit.platform.gradle.plugin’

 

compileTestJava {

   sourceCompatibility = 1.8

   targetCompatibility = 1.8

   options.compilerArgs += ‘-parameters’

}

 

dependencies {

   testCompile(“org.junit.jupiter:junit-jupiter-api:${junitJupiterVersion}”)

   testRuntime(“org.junit.jupiter:junit-jupiter-engine:${junitJupiterVersion}”)

   testCompile(“org.junit.platform:junit-platform-runner:${junitPlatformVersion}”)

}

IntelliJ

IntelliJ 2016.2+ has been the first IDE, which supports the execution of Jupiter tests natively. As shown in the following screenshot, any Jupiter test can be executed using the integrated functions of the IDE:

Running tests in JUnit 5 6

Running a Jupiter test in IntelliJ 2016.2+

Eclipse

Eclipse 4.7 (Oxygen) has beta support for JUnit 5. Thanks to this, Eclipse provides the ability to run Jupiter tests directly in Eclipse, as shown in the following screenshot:

Running tests in JUnit 5 7

Running a Jupiter test in Eclipse 4.7+

Moreover, Eclipse 4.7 (Oxygen) provides a wizard to create Jupiter tests in a simple way, as shown in the following image:

Running tests in JUnit 5 9

Eclipse wizard to create Jupiter tests

If you found this article helpful, you can explore Boni García’s Mastering Software Testing with JUnit 5 to make use of the power of JUnit 5. This book is a hands-on guide on a unit testing framework for Java programming language.

Leave a comment

Your email address will not be published. Required fields are marked *