A Guide to @ClassTemplate in Junit 5

1. Introduction

Some tests need to work across various environments. The @ClassTemplate annotation helps with this by running the entire test class multiple times, each time with a different configuration.

In this tutorial, we’ll explore why class templates exist and how JUnit runs them. Additionally, we’ll examine where they fit into the execution model. Finally, we’ll look at their structure, the provider behind them, and a practical example that runs one test class across multiple locale-specific environments without duplicating code.

2. What’s a @ClassTemplate

To briefly review, @ClassTemplate turns a test class into a template that runs once per invocation context. The providers supply contexts, and each one results in a separate execution with its own lifecycle and extensions.

In practice, this lets us run the same test class under different environments or configurations while keeping the test code simple. We can vary the runtime setup without duplicating test classes or introducing branching logic into individual tests.

2.1. How a Class Template Executes

A class template has two parts: the template class itself and the provider that supplies its invocation contexts. The template class looks like a standard JUnit test class, but the @ClassTemplate annotation instructs JUnit not to run it directly. Instead, JUnit waits for providers to define how to execute the class.

Once JUnit recognizes a class template, the provider returns one or more contexts, each of which defines a complete execution. For every context, JUnit creates a new test instance, applies its extensions, and runs the lifecycle and test methods. Therefore, the test can focus on logic while the provider shapes the setup.

2.2. Class Templates vs Method Templates

Before moving on, it’s worth noting how class templates differ from method templates. Both approaches allow repeated execution, but they work at different levels. A method template re-runs a single test method with varying inputs, while a class template re-runs the entire test class. This includes its lifecycle callbacks, extensions, and configuration.

As a result, class templates are more suitable when the variation concerns the overall environment—such as locales, feature flags, or system settings—rather than per-method parameters.

3. The Invocation Context Provider

Next, let’s look at the invocation context provider. This extension supplies the execution contexts for a class template. It implements the ClassTemplateInvocationContextProvider interface, which defines two central methods that determine how the provider participates in test execution.

Let’s examine them.

3.1. SupportsClassTemplate() Method

Before JUnit uses a provider, it first checks if the provider applies to the test class currently being discovered. This happens through the supportsClassTemplate() method:

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

JUnit calls this method for every registered provider. Consequently, only those that return true become active for the current class template. This mechanism prevents accidental activation, avoids running providers on unrelated tests, and allows multiple providers to coexist without interfering with each other.

3.2. ProvideClassTemplateInvocationContexts() Method

Once a provider becomes active, JUnit calls provideClassTemplateInvocationContexts() to obtain the contexts that describe how the template should be executed:

@Override
public Stream<ClassTemplateInvocationContext> provideClassTemplateInvocationContexts(ExtensionContext context) {
    return Stream.of(invocationContext("A"), invocationContext("B"));
}

Each context represents a complete execution of the test class. A provider can supply one or many, and if several providers are active, JUnit chains their streams. Each context may add its own extensions or configuration, giving the provider control over that run’s environment.

From there, JUnit creates a fresh instance of the test class for each context, applies the associated extensions, and runs the lifecycle and test methods exactly once for that execution.

4. Practical Example

To illustrate these concepts, let’s create a test that verifies date formatting under several JVM locales. Because the locale influences the entire execution environment, it’s a good fit for class templates. We keep one test class and let the provider run it multiple times with different configurations.

4.1. Date Formatting Logic

First, let’s start with a small class that formats dates using the JVM’s current default locale. Its output changes whenever the default locale changes:

class DateFormatter {

    public String format(LocalDate date) {
        DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG)
          .withLocale(Locale.getDefault());

        return date.format(formatter);
    }
}

With this in place, we’ll verify this behavior under several different configurations, each provided by the class template.

4.2. Provider and Extension

To support that, we first need an extension that sets the default locale for a single execution:

class LocaleExtension implements BeforeEachCallback, AfterEachCallback {

    private final Locale locale;
    private Locale previous;

    @Override
    public void beforeEach(ExtensionContext context) {
        previous = Locale.getDefault();
        Locale.setDefault(locale);
    }

    @Override
    public void afterEach(ExtensionContext context) {
        Locale.setDefault(previous);
    }
}

This extension temporarily replaces the JVM’s default value before each test and restores the original value afterwards. The only thing that changes between executions is the Locale instance passed to the extension.

Furthermore, the provider supplies the contexts through provideClassTemplateInvocationContexts(). Each context is created by invocationContext(), which assigns a display name using getDisplayName() and installs the LocaleExtension through getAdditionalExtensions():

class DateLocaleClassTemplateProvider implements ClassTemplateInvocationContextProvider {

    @Override
    public Stream<ClassTemplateInvocationContext> provideClassTemplateInvocationContexts(ExtensionContext context) {
        return Stream.of(Locale.US, Locale.GERMANY, Locale.ITALY, Locale.JAPAN)
          .map(this::invocationContext);
    }

    private ClassTemplateInvocationContext invocationContext(Locale locale) {
        return new ClassTemplateInvocationContext() {

            @Override
            public String getDisplayName(int invocationIndex) {
                return "Locale: " + locale.getDisplayName();
            }

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

This configuration produces distinct environments, leading to four independent executions of the same test class.

4.3. Class Template Test

At this point, the template setup allows us to focus on a single test method, which JUnit runs once per context through the configured provider:

private final DateFormatter formatter = new DateFormatter();

@Test
void givenDefaultLocale_whenFormattingDate_thenMatchesLocalizedOutput() {
    LocalDate date = LocalDate.of(2025, 9, 30);

    DateTimeFormatter expectedFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG)
      .withLocale(Locale.getDefault());

    String expected = date.format(expectedFormatter);
    String formatted = formatter.format(date);

    LOG.info("Locale: {}, Expected: {}, Formatted: {}", Locale.getDefault(), expected, formatted);

    assertEquals(expected, formatted);
}

During each execution, the test computes the expected value using the current default locale and compares it with the result from DateFormatter. The class template and provider handle changing the settings between executions, so the test itself remains simple and free of branching logic.

4.4. Test Output

Finally, when we run the tests, the same class is executed once per locale. The formatted output differs for each run:

Locale: en_US, Expected: September 30, 2025, Formatted: September 30, 2025
Locale: de_DE, Expected: 30. September 2025, Formatted: 30. September 2025
Locale: it_IT, Expected: 30 settembre 2025, Formatted: 30 settembre 2025
Locale: ja_JP, Expected: 2025年9月30日, Formatted: 2025年9月30日

Indeed, each line corresponds to one invocation context. The test code doesn’t change between these runs; only the environment configured by the provider and extension does.

5. Conclusion

In this article, we looked beyond the basics of @ClassTemplate and explored how providers supply multiple execution contexts for a single test class. By using locales as an example, we saw how a provider and extension can vary the test environment while the test code stays unchanged. This makes class templates a clean solution for testing behavior that depends on global or configuration-level settings.

As always, the complete source code is available over on GitHub.