Intro to @ClassTemplate Annotation in JUnit

1. Overview

JUnit Jupiter recently introduced the @ClassTemplate annotation, which allows us to execute an entire test class multiple times in different invocation contexts. Rather than repeating setup code or scattering parameters across many methods, we can perform whole-class executions with custom contexts returned by the registered provider.

In this tutorial, we’ll walk through a minimal, practical example that runs the same test class in two contexts: one for English and one for Italian. This approach keeps the code tidy and reveals its purpose.

2. Prerequisites

Java 17 or above is required.

We must keep in mind that the @ClassTemplate annotation was introduced in JUnit 5.13.x only recently, so we must use the latest versions of JUnit Jupiter, JUnit Launcher, and Maven Surefire. This pom.xml file shows how to do that:

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.13.4</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.platform</groupId>
        <artifactId>junit-platform-launcher</artifactId>
        <version>1.13.4</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.5.3</version>
        </plugin>
    </plugins>
</build>

We can check the Maven Repository to see if there are newer versions.

3. Building a Class Template

Marking a test class with @ClassTemplate informs JUnit that the class isn’t a traditional test container. Rather, it’s a template that will be executed as many times as there are invocation contexts supplied by one or more registered ClassTemplateInvocationContextProvider classes. If no provider is registered, the tests will fail, so we must always pair a class template with at least one provider.

But first, let’s start with the domain class.

3.1. Domain Class

Our domain class is simply a Greeter that returns a localized greeting based on a language code:

public class Greeter {
    public String greet(String name, String language) {
        return "it".equals(language) ? "Ciao " + name : "Hello " + name;
    }
}

This will help us clearly see the differences between the English and Italian parameterizations.

3.2. Invocation Context Provider

Under the hood, the provider interface exposes two key methods:

• supportsClassTemplate(ExtensionContext …), which determines whether the template should be handled
• provideClassTemplateInvocationContexts(ExtensionContext …), which provides a stream of ClassTemplateInvocationContext objects, one per execution

Each ClassTemplateInvocationContext provides a ParameterResolver, which injects the language code into the GreeterClassTemplateUnitTest constructor and sets a descriptive name for the test:

public class GreeterClassTemplateInvocationContextProvider
  implements ClassTemplateInvocationContextProvider {
    @Override
    public boolean supportsClassTemplate(ExtensionContext context) {
        return context.getTestClass()
          .map(c -> c.isAnnotationPresent(ClassTemplate.class))
          .orElse(false);
    }

    @Override
    public Stream<ClassTemplateInvocationContext> provideClassTemplateInvocationContexts(
      ExtensionContext context) {
        return Stream.of(contextFor("en"), contextFor("it"));
    }

    private ClassTemplateInvocationContext contextFor(String language) {
        ParameterResolver resolver = new ParameterResolver() {
            @Override
            public boolean supportsParameter(ParameterContext pc, ExtensionContext ec) {
                return pc.getParameter().getType() == String.class;
            }

            @Override
            public Object resolveParameter(ParameterContext pc, ExtensionContext ec) {
                return language;
            }
        };

        return new ClassTemplateInvocationContext() {
            @Override
            public String getDisplayName(int invocationIndex) {
                return "Language-" + language;
            }

            @Override
            public List<Extension> getAdditionalExtensions() {
                return List.of(resolver);
            }
        };
    }
}

As a side note, the getDisplayName(…) method isn’t currently taken into account by mvn test. As a workaround, we can insert an explicit log in GreeterClassTemplateUnitTest to be aware of the tested context.

3.3. Class Template Test

Now, let’s look at the test class. Let’s mark it as a class template with @ClassTemplate and register the provider with @ExtendWith(…). The class accepts a language code as a parameter in its constructor, and the provider injects this value with each invocation:

@ClassTemplate
@ExtendWith(GreeterClassTemplateInvocationContextProvider.class)
class GreeterClassTemplateUnitTest {
    private static final Logger LOG =
      System.getLogger("GreeterClassTemplateUnitTest");

    private final String language;

    GreeterClassTemplateUnitTest(String language) {
        this.language = language;
    }

    @BeforeEach
    void logContext() {
        LOG.log(Level.INFO, () -> ">> Context: Language-" + language);
    }

    @Test
    void whenGreet_thenLocalizedMessage() {
        Greeter greeter = new Greeter();
        String actual = greeter.greet("Baeldung", language);

        assertEquals(
          "it".equals(language) ? "Ciao Baeldung" : "Hello Baeldung",
          actual
        );
    }
}

The optional @BeforeEach method clarifies the log by indicating the context.

Now, let’s look at some advantages of the @ClassTemplate approach:

• Class-wide variation: the constructor receives the language code, so every test in the class runs in that locale
• No duplication: a single test class yields multiple runs, one per context, without copying and pasting classes or relying on global state
• Clear scope: @ClassTemplate indicates our intention to run the class multiple times via contexts, keeping code and reports tidy

By default, invocations run sequentially, one context at a time on a single thread. Within each context, JUnit uses the PER_METHOD lifecycle, creating a fresh test instance for every test method. However, we can enable parallel execution via the JUnit Platform settings.

3.4. Running the Tests

Let’s check that the tests work as expected:

$ mvn clean test
[...]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.baeldung.classtemplate.GreeterClassTemplateUnitTest
[INFO] Running com.baeldung.classtemplate.GreeterClassTemplateUnitTest
INFO: >> Context: Language-en
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.046 s -- in com.baeldung.classtemplate.GreeterClassTemplateUnitTest
[INFO] Running com.baeldung.classtemplate.GreeterClassTemplateUnitTest
INFO: >> Context: Language-it
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.011 s -- in com.baeldung.classtemplate.GreeterClassTemplateUnitTest
[INFO] Tests run: 0, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.104 s -- in com.baeldung.classtemplate.GreeterClassTemplateUnitTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[...]

The output is correct, but not very readable. In addition, we added a @BeforeEach method to supplement the Maven Surefire Plugin log: it’s a simple workaround, but not an ideal solution.

An alternative approach is to use the JUnit Console Launcher, a standalone command-line tool that runs tests directly on the JUnit Platform. Its tree view is more readable, and we can remove our @BeforeEach method:

$ mvn dependency:get -Dartifact=org.junit.platform:junit-platform-console-standalone:1.13.4
[...]
$ mvn clean -DskipTests package
[...]
$ java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.13.4/junit-platform-console-standalone-1.13.4.jar \
    --class-path target/test-classes:target/classes \
    --scan-classpath \
    --details tree
[...]
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│  └─ GreeterClassTemplateUnitTest ✔
│     ├─ Language-en ✔
│     │  └─ whenGreet_thenLocalizedMessage() ✔
│     └─ Language-it ✔
│        └─ whenGreet_thenLocalizedMessage() ✔
└─ JUnit Vintage ✔
[...]

These commands target Linux and macOS. On Windows, we use %USERPROFILE%\.m2\repository, replace : with ; in –class-path, and run it on one line or use ^ to continue lines.

4. Conclusion

In this article, we created a simple yet comprehensive example that uses the @ClassTemplate annotation to execute a test class twice in two different locales.

We observed how a ClassTemplateInvocationContextProvider supplies multiple contexts, injects parameters via a ParameterResolver, and assigns readable display names to each invocation. The result is clear reports and class-wide variation without duplication.

In short, @ClassTemplate lets us run the entire test class under different configurations and still keep tests simple and expressive.