JUnit 5 provides a powerful extension model that lets you hook into the test lifecycle. Here’s a comprehensive guide to creating custom extensions.

1. Choose the Right Extension Interface

JUnit 5 offers several extension interfaces depending on what you want to do:

2. Basic Example: A Timing Extension

Here’s an extension that measures test execution time:

package com.example.testing;

import org.junit.jupiter.api.extension.AfterTestExecutionCallback;
import org.junit.jupiter.api.extension.BeforeTestExecutionCallback;
import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.api.extension.ExtensionContext.Namespace;
import org.junit.jupiter.api.extension.ExtensionContext.Store;

import java.lang.reflect.Method;

public class TimingExtension implements BeforeTestExecutionCallback, AfterTestExecutionCallback {

    private static final Namespace NAMESPACE = Namespace.create(TimingExtension.class);
    private static final String START_TIME = "start_time";

    @Override
    public void beforeTestExecution(ExtensionContext context) {
        getStore(context).put(START_TIME, System.currentTimeMillis());
    }

    @Override
    public void afterTestExecution(ExtensionContext context) {
        Method testMethod = context.getRequiredTestMethod();
        long startTime = getStore(context).remove(START_TIME, long.class);
        long duration = System.currentTimeMillis() - startTime;

        System.out.printf("Method [%s] took %d ms.%n", testMethod.getName(), duration);
    }

    private Store getStore(ExtensionContext context) {
        return context.getStore(NAMESPACE);
    }
}

3. Parameter Resolver Example

Injecting custom parameters into test methods:

package com.example.testing;

import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.api.extension.ParameterContext;
import org.junit.jupiter.api.extension.ParameterResolutionException;
import org.junit.jupiter.api.extension.ParameterResolver;

import java.util.UUID;

public class RandomUuidParameterResolver implements ParameterResolver {

    @Override
    public boolean supportsParameter(ParameterContext parameterContext,
                                     ExtensionContext extensionContext)
            throws ParameterResolutionException {
        return parameterContext.getParameter().getType() == UUID.class;
    }

    @Override
    public Object resolveParameter(ParameterContext parameterContext,
                                   ExtensionContext extensionContext)
            throws ParameterResolutionException {
        return UUID.randomUUID();
    }
}

4. TestWatcher Example

Observing test outcomes:

package com.example.testing;

import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.api.extension.TestWatcher;

import java.util.Optional;

public class TestResultLogger implements TestWatcher {

    @Override
    public void testSuccessful(ExtensionContext context) {
        System.out.println("✔ " + context.getDisplayName() + " passed");
    }

    @Override
    public void testFailed(ExtensionContext context, Throwable cause) {
        System.out.println("✘ " + context.getDisplayName() + " failed: " + cause.getMessage());
    }

    @Override
    public void testAborted(ExtensionContext context, Throwable cause) {
        System.out.println("⚠ " + context.getDisplayName() + " aborted");
    }

    @Override
    public void testDisabled(ExtensionContext context, Optional<String> reason) {
        System.out.println("⊘ " + context.getDisplayName() + " disabled: " + reason.orElse("no reason"));
    }
}

5. Registering the Extension

There are three ways to register your extension:

a) Declarative with @ExtendWith

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import java.util.UUID;

@ExtendWith({TimingExtension.class, RandomUuidParameterResolver.class})
class MyServiceTest {

    @Test
    void shouldDoSomething(UUID uniqueId) {
        System.out.println("Test running with ID: " + uniqueId);
    }
}

b) Programmatic with @RegisterExtension

Useful when the extension needs configuration:

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;

class MyServiceTest {

    @RegisterExtension
    static TimingExtension timingExtension = new TimingExtension();

    @Test
    void shouldDoSomething() {
        // ...
    }
}

c) Automatic Registration via ServiceLoader

Create the file src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension containing:

com.example.testing.TimingExtension

Then enable auto-detection in junit-platform.properties:

junit.jupiter.extensions.autodetection.enabled=true

6. Creating a Custom Annotation (Meta-Annotation)

You can bundle extensions into a custom annotation:

package com.example.testing;

import org.junit.jupiter.api.extension.ExtendWith;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith({TimingExtension.class, TestResultLogger.class})
public @interface IntegrationTest {
}

Usage:

@IntegrationTest
class MyIntegrationTest {
    @Test
    void something() { /* ... */ }
}

7. Sharing State with the Store

The ExtensionContext.Store lets you share state between callbacks safely across parallel tests. Always use a unique Namespace to avoid collisions:

Namespace ns = Namespace.create(MyExtension.class, context.getRequiredTestMethod());
Store store = context.getStore(ns);
store.put("key", value);

Key Tips

• Prefer composition — implement multiple interfaces on the same class if the concerns are related.
• Use Store for state rather than instance fields, because JUnit may create new instances or use the extension across parallel tests.
• Respect lifecycle order — class-level callbacks fire before method-level ones.
• Make extensions stateless when possible to be safe in parallel execution.