Writing Templates for Test Cases Using JUnit 5

1. Overview

The JUnit 5 library offers many new features over its previous versions. One such feature is test templates. In short, test templates are a powerful generalization of JUnit 5’s parameterized and repeated tests.

In this tutorial, we’re going to learn how to create a test template using JUnit 5.

2. Maven Dependencies

Let’s start by adding the dependencies to our pom.xml.

We need to add the main JUnit 5  junit-jupiter-engine dependency:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.9.2</version>
</dependency>

In addition to this, we’ll also need to add the junit-jupiter-api dependency:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.9.2</version>
</dependency>

Likewise, we can add the necessary dependencies to our build.gradle file:

testCompile group: 'org.junit.jupiter', name: 'junit-jupiter-engine', version: '5.9.2'
testCompile group: 'org.junit.jupiter', name: 'junit-jupiter-api', version: '5.9.2'

3. The Problem Statement

Before looking at test templates, let’s briefly take a look at JUnit 5’s parameterized tests. Parameterized tests allow us to inject different parameters into the test method. As a result, when using parameterized tests, we can execute a single test method multiple times with different parameters.

Let’s assume that we would now like to run our test method multiple times — not just with different parameters, but also under a different invocation context each time.

In other words, we would like the test method to be executed multiple times, with each invocation using a different combination of configurations such as:

• using different parameters
• preparing the test class instance differently — that is, injecting different dependencies into the test instance
• running the test under different conditions, such as enabling/disabling a subset of invocations if the environment is “QA“
• running with a different lifecycle callback behavior — perhaps we want to set up and tear down a database before and after a subset of invocations

Using parameterized tests quickly proves limited in this case. Thankfully, JUnit 5 offers a powerful solution for this scenario in the form of test templates.

4. Test Templates

Test templates themselves are not test cases. Instead, as their name suggests, they are just templates for given test cases. They are a powerful generalization of parameterized and repeated tests.

Test templates are invoked once for each invocation context provided to them by the invocation context provider(s).

Let’s now look at an example of the test templates. As we established above, the main actors are:

• a test target method
• a test template method
• one or more invocation context providers registered with the template method
• one or more invocation contexts provided by each invocation context provider

4.1. The Test Target Method

For this example, we’re going to use a simple UserIdGeneratorImpl.generate method as our test target.

Let’s define the UserIdGeneratorImpl class:

public class UserIdGeneratorImpl implements UserIdGenerator {
    private boolean isFeatureEnabled;

    public UserIdGeneratorImpl(boolean isFeatureEnabled) {
        this.isFeatureEnabled = isFeatureEnabled;
    }

    public String generate(String firstName, String lastName) {
        String initialAndLastName = firstName.substring(0, 1).concat(lastName);
        return isFeatureEnabled ? "bael".concat(initialAndLastName) : initialAndLastName;
    }
}

The generate method, which is our test target, takes the firstName and lastName as parameters and generates a user id. The format of the user id varies, depending on whether a feature switch is enabled or not.

Let’s see how this looks:

Given feature switch is disabled When firstName = "John" and lastName = "Smith" Then "JSmith" is returned
Given feature switch is enabled When firstName = "John" and lastName = "Smith" Then "baelJSmith" is returned

Next, let’s write the test template method.

4.2. The Test Template Method

Here is a test template for our test target method UserIdGeneratorImpl.generate:

public class UserIdGeneratorImplUnitTest {
    @TestTemplate
    @ExtendWith(UserIdGeneratorTestInvocationContextProvider.class)
    public void whenUserIdRequested_thenUserIdIsReturnedInCorrectFormat(UserIdGeneratorTestCase testCase) {
        UserIdGenerator userIdGenerator = new UserIdGeneratorImpl(testCase.isFeatureEnabled());

        String actualUserId = userIdGenerator.generate(testCase.getFirstName(), testCase.getLastName());

        assertThat(actualUserId).isEqualTo(testCase.getExpectedUserId());
    }
}

Let’s take a closer look at the test template method.

To begin with, we create our test template method by marking it with the JUnit 5 @TestTemplate annotation.

Following that, we register a context provider, UserIdGeneratorTestInvocationContextProvider, using the @ExtendWith annotation. We can register multiple context providers with the test template. However, for the purpose of this example, we register a single provider.

Also, the template method receives an instance of the UserIdGeneratorTestCase as a parameter. This is simply a wrapper class for the inputs and the expected result of the test case:

public class UserIdGeneratorTestCase {
    private boolean isFeatureEnabled;
    private String firstName;
    private String lastName;
    private String expectedUserId;

    // Standard setters and getters
}

Finally, we invoke the test target method and assert that that result is as expected

Now, it’s time to define our invocation context provider.

4.3. The Invocation Context Provider

We need to register at least one TestTemplateInvocationContextProvider with our test template. Each registered TestTemplateInvocationContextProvider provides a Stream of TestTemplateInvocationContext instances.

Previously, using the @ExtendWith annotation, we registered UserIdGeneratorTestInvocationContextProvider as our invocation provider.

Let’s define this class now:

public class UserIdGeneratorTestInvocationContextProvider implements TestTemplateInvocationContextProvider {
    //...
}

Our invocation context implements the TestTemplateInvocationContextProvider interface, which has two methods:

• supportsTestTemplate
• provideTestTemplateInvocationContexts

Let’s start by implementing the supportsTestTemplate method:

@Override
public boolean supportsTestTemplate(ExtensionContext extensionContext) {
    return true;
}

The JUnit 5 execution engine calls the supportsTestTemplate method first to validate if the provider is applicable for the given ExecutionContext. In this case, we simply return true.

Now, let’s implement the provideTestTemplateInvocationContexts method:

@Override
public Stream<TestTemplateInvocationContext> provideTestTemplateInvocationContexts(
  ExtensionContext extensionContext) {
    boolean featureDisabled = false;
    boolean featureEnabled = true;
 
    return Stream.of(
      featureDisabledContext(
        new UserIdGeneratorTestCase(
          "Given feature switch disabled When user name is John Smith Then generated userid is JSmith",
          featureDisabled,
          "John",
          "Smith",
          "JSmith")),
      featureEnabledContext(
        new UserIdGeneratorTestCase(
          "Given feature switch enabled When user name is John Smith Then generated userid is baelJSmith",
          featureEnabled,
          "John",
          "Smith",
          "baelJSmith"))
    );
}

The purpose of the provideTestTemplateInvocationContexts method is to provide a Stream of TestTemplateInvocationContext instances. For our example, it returns two instances, provided by the methods featureDisabledContext and featureEnabledContext. Consequently, our test template will run twice.

Next, let’s look at the two TestTemplateInvocationContext instances returned by these methods.

4.4. The Invocation Context Instances

The invocation contexts are implementations of the TestTemplateInvocationContext interface and implement the following methods:

• getDisplayName – provide a test display name
• getAdditionalExtensions – return additional extensions for the invocation context

Let’s define the featureDisabledContext method that returns our first invocation context instance:

private TestTemplateInvocationContext featureDisabledContext(
  UserIdGeneratorTestCase userIdGeneratorTestCase) {
    return new TestTemplateInvocationContext() {
        @Override
        public String getDisplayName(int invocationIndex) {
            return userIdGeneratorTestCase.getDisplayName();
        }

        @Override
        public List<Extension> getAdditionalExtensions() {
            return asList(
              new GenericTypedParameterResolver(userIdGeneratorTestCase), 
              new BeforeTestExecutionCallback() {
                  @Override
                  public void beforeTestExecution(ExtensionContext extensionContext) {
                      System.out.println("BeforeTestExecutionCallback:Disabled context");
                  }
              }, 
              new AfterTestExecutionCallback() {
                  @Override
                  public void afterTestExecution(ExtensionContext extensionContext) {
                      System.out.println("AfterTestExecutionCallback:Disabled context");
                  }
              }
            );
        }
    };
}

Firstly, for the invocation context returned by the featureDisabledContext method, the extensions that we register are:

• GenericTypedParameterResolver – a parameter resolver extension
• BeforeTestExecutionCallback – a lifecycle callback extension that runs immediately before the test execution
• AfterTestExecutionCallback – a lifecycle callback extension that runs immediately after the test execution

However, for the second invocation context, returned by the featureEnabledContext method, let’s register a different set of extensions (keeping the GenericTypedParameterResolver):

private TestTemplateInvocationContext featureEnabledContext(
  UserIdGeneratorTestCase userIdGeneratorTestCase) {
    return new TestTemplateInvocationContext() {
        @Override
        public String getDisplayName(int invocationIndex) {
            return userIdGeneratorTestCase.getDisplayName();
        }
    
        @Override
        public List<Extension> getAdditionalExtensions() {
            return asList(
              new GenericTypedParameterResolver(userIdGeneratorTestCase), 
              new DisabledOnQAEnvironmentExtension(), 
              new BeforeEachCallback() {
                  @Override
                  public void beforeEach(ExtensionContext extensionContext) {
                      System.out.println("BeforeEachCallback:Enabled context");
                  }
              }, 
              new AfterEachCallback() {
                  @Override
                  public void afterEach(ExtensionContext extensionContext) {
                      System.out.println("AfterEachCallback:Enabled context");
                  }
              }
            );
        }
    };
}

For the second invocation context, the extensions that we register are:

• GenericTypedParameterResolver – a parameter resolver extension
• DisabledOnQAEnvironmentExtension – an execution condition to disable the test if the environment property (loaded from the application.properties file) is “qa“
• BeforeEachCallback – a lifecycle callback extension that runs before each test method execution
• AfterEachCallback – a lifecycle callback extension that runs after each test method execution

From the above example, it is clear to see that:

• the same test method is run under multiple invocation contexts
• each invocation context uses its own set of extensions that differ both in number and nature from the extensions in other invocation contexts

As a result, a test method can be invoked multiple times under a completely different invocation context each time. And by registering multiple context providers, we can provide even more additional layers of invocation contexts under which to run the test.

5. Conclusion

In this article, we looked at how JUnit 5’s test templates are a powerful generalization of parameterized and repeated tests.

To begin with, we looked at some limitations of the parameterized tests. Next, we discussed how test templates overcome the limitations by allowing a test to be run under a different context for each invocation.

Finally, we looked at an example of creating a new test template. We broke the example down to understand how templates work in conjunction with the invocation context providers and invocation contexts.

As always, the source code for the examples used in this article is available over on GitHub.