A Guide to @RepeatedTest and @ParametrizedTest in JUnit 5

In this guide, you will learn to use @RepeatedTest and @ParametrizedTest annotations introduced in JUnit 5. We’ll look at the capability that lets us run a test a certain number of times.  We’ll also look at interfaces that will allow us to retrieve information about the repeated tests.  Moreover, we will also look at a feature that allows us to repeat the same test with different parameters and learn how to use different types of argument sources. So, let’s begin!

For video lessons, check “Testing Java with JUnit and Mockito” page.

Introduction of JUnit 5

The JUnit framework is a popular test automation framework for unit testing in Java. The JUnit 5 also known as Jupiter, the most recent version of JUnit has many enhancements over JUnit 4. Among the many, new and helpful annotations in JUnit 5, @RepeatedTest and @ParametrizedTest are the most powerful.

With this, we know that both of these annotations are a “must know” for any Java software engineers, as well as Automation Engineers working on web applications because they make it easier to test your application code.

Let’s assume you have a Maven, Spring Boot Project. Refer to this article for more details.

To begin with, add the following dependencies into your Maven project:

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

The above-mentioned dependency imports the @RepeatedTest annotation and supporting classes.

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-params</artifactId>
    <version>5.8.2</version>
    <scope>test</scope>
</dependency>

The above-mentioned dependency imports the @ParametrizedTest annotation and supporting classes.

@RepeatedTest Annotation

As per the official documentation:

“JUnit Jupiter provides the ability to repeat a test a specified number of times by annotating a method with @RepeatedTest and specifying the total number of repetitions desired.”

Since each invocation of the test case is treated as a regular @Test method in JUnit 5, it supports the same lifecycle callbacks and extensions.

Usage of @RepeatedTest Annotation Based on a Scenario

Consider the case of an online live streaming platform. When a user logs in to the web application and selects the “Channels” tab, an exception is thrown with the message “Web page not available.”

The user repeats the steps three times and encounters the same error, but on the fourth attempt, it works. The development team and the client are both aware of this environmental issue. In such a case, we could make use of the @RepeatedTest annotation to handle clicking on the Channel page four times and then proceed with other tests without failing. This was one of the examples but in the same way, we often encounter use-cases in different software applications to utilize @RepeatedTest annotation.

Syntax

@RepeatedTest(10)
void repeatedTest() {
// ...
}

• Mark a test with @RepeatedTest annotation instead of a @Test annotation.
• Pass a number as an input argument to the annotation that represents the number of executions of the test.

Rules

• The methods with the @RepeatedTest annotation cannot be static.
• The methods with the @RepeatedTest annotation cannot be private.
• The return type of the methods annotated with the @RepeatedTest should be void.

Examples

1. With Integer Value as an Argument

The simplest way of using the annotation is to pass an integer value as an argument.  The following example demonstrates the usage of the annotation:

@RepeatedTest(5)
public void testRepeatedTest() {
    System.out.println("Hello World");
}

As per expectations, the output of the above test shows that the annotated method runs 5 times:

Hello World
Hello World
Hello World
Hello World
Hello World

The following snapshot displays the execution of the method five times:

2. With Display Name Pattern as an Argument

The @RepeatedTest annotation also supports another argument to configure a custom display name. To understand the usage better, let’s try to understand the following three placeholders supported:

1. {displayName}: It displays the annotated method name.
2. {currentRepetition}: It returns the current repetition count.
3. {totalRepetitions}: It returns the total number of repetitions.

The following examples demonstrate the usage of the display name patterns:

1. SHORT_DISPLAY_NAME

Annotation uses SHORT_DISPLAY_NAME as the default placeholder. The default display name for repetition is determined by the pattern:

 "repetition {currentRepetition} of {totalRepetitions}."

The following code snippet shows how to set a short display name pattern in the @RepeatedTest:

@RepeatedTest(value = 5, name = SHORT_DISPLAY_NAME)
public void repeatedTestWithShortDisplayName() {
    System.out.println("Hello World");
}

The output window snapshot is shown below:

2. LONG_DISPLAY_NAME

JUnit displays the following pattern when it is used:

repetition 'currentRepetition' of 'totalRepetitions' (displayName)

The following code snippet shows how to set a long display name pattern in the @RepeatedTest:

@RepeatedTest(value = 5, name = LONG_DISPLAY_NAME)
public void repeatedTestWithLongDisplayName() {
    System.out.println("Hello World");
}

The output window snapshot is shown below:

3. Custom Display Name

We can customize the display patterns by using the placeholders defined earlier. The following example demonstrates the usage:

@RepeatedTest(value = 5, name = "{displayName} {currentRepetition}/{totalRepetitions}")
@DisplayName("Repeating..")
void repeatedTestWithCustomDisplayName() {
   System.out.println("Hello World");
}

In the above example, we have used @DisplayName annotation to override the default method name by the name provided in the annotation @DisplayName(“Repeating..”).

The JUnit tab displays the following output as shown in the snapshot below:

Interfaces supported by @RepeatedTest

TestInfo

TestInfo is an interface that retrieves information about a test method, whether it’s a @Test, @RepeatedTest, parameterized test, or a lifecycle callback function marked with @BeforeEach, @AfterEach, @BeforeAll, @AfterAll annotation.

It supports the following methods:

• TestInfo.getDisplayName(): It returns the display name of the test which is invoked.
• TestInfo.getTags(): It returns the associated tags with the test method.
• TestInfo.getTestClass(): It returns the name of the class inside which the test method is placed.
• TestInfo.getTestMethod(): It returns the name of the test method.

The following code demonstrates the usage of the methods discussed above:

@RepeatedTest(value = 1)
public void testInfo(TestInfo testInfo) {
    System.out.println("Test Info Details:");
    System.out.println("Display name:  " + testInfo.getDisplayName());
    System.out.println("Tag:" + testInfo.getTags());
    System.out.println("Test method  name: " + testInfo.getTestMethod().get().getName());
    System.out.println("Test class  name: " + testInfo.getTestClass().get().getName());
}

The output of the above test is as follows:

Test Info Details:
Display name: repetition 1 of 1
Tag:[]
Test method name: testInfo
Test class name: demoTestClass

RepetitionInfo

RepetitionInfo is an interface that retrieves information about the test method’s repetition. The interface comes with the following two methods:

1. RepetitionInfo.getCurrentRepetition() : It returns the current repetition of the @RepeatedTest method.
2. RepetitionInfo.getTotalRepetitions() : It returns the total count of repetitions of @RepeatedTest method.

The following code demonstrates how we can use functions provided by the interface:

@RepeatedTest(value = 1)
public void repeationInfo(RepetitionInfo repetitionInfo) {
    System.out.println("Repetition Info Details:");
    System.out.println("Current Repetition:  " + repetitionInfo.getCurrentRepetition());
    System.out.println("Total Repetitions:" + repetitionInfo.getTotalRepetitions());
}

The output of the above test is as follows:

Repetition Info Details:
Current Repetition:  1
Total Repetitions:1

@ParameterizedTest

As per the official documentation:

“Parameterized tests run a test multiple times with different arguments.”

Usage of @Parametrized annotation based on a scenario

When we wish to run the same test with different sets of parameters, we may use the @ParametrizedTest annotation. To see if a student passes an exam, we have created a test method that evaluates the criteria for passing an exam. To compile results, we need to run the same test for all the students of a particular class. In this case, we can pass a list of Students as an argument to a single test, which will run for all students. This was one of the examples, but we see a wide range of applications of the @ParametrizedTest annotation for all software applications as it gives us leverage to test flow with a wide range of input values.

Possible Sources of Arguments

As per the definition, we pass different input values as arguments to the test method. JUnit offers a variety of ways to pass arguments to the method body. Let’s have a look at them:

@ValueSource

It is the simplest form of providing value source to the @ParametrizedMethod. It only allows you to provide a single argument per parameterized test invocation and allows you to specify a single array of literal values.  The following types of literal values are supported by the annotation @ValueSource: