Package org.junit.jupiter.api.extension

Annotation Type RegisterExtension

@Target(FIELD)
@Retention(RUNTIME)
@Documented
@API(status=STABLE,
     since="5.1")
public @interface RegisterExtension

@RegisterExtension is used to register an Extension via a field in a test class.

In contrast to @ExtendWith which is used to register extensions declaratively, @RegisterExtension can be used to register an extension programmatically — for example, in order to pass arguments to the extension's constructor, static factory method, or builder API.

@RegisterExtension fields must not be private or null (when evaluated) but may be either static or non-static.

Static Fields

If a @RegisterExtension field is static, the extension will be registered after extensions that are registered at the class level via @ExtendWith. Such static extensions are not limited in which extension APIs they can implement. Extensions registered via static fields may therefore implement class-level and instance-level extension APIs such as BeforeAllCallback, AfterAllCallback, and TestInstancePostProcessor as well as method-level extension APIs such as BeforeEachCallback, etc.

Instance Fields

If a @RegisterExtension field is non-static (i.e., an instance field), the extension will be registered after the test class has been instantiated and after all TestInstancePostProcessors have been given a chance to post-process the test instance (potentially injecting the instance of the extension to be used into the annotated field). Thus, if such an instance extension implements class-level or instance-level extension APIs such as BeforeAllCallback, AfterAllCallback, or TestInstancePostProcessor those APIs will not be honored. By default, an instance extension will be registered after extensions that are registered at the method level via @ExtendWith; however, if the test class is configured with @TestInstance(Lifecycle.PER_CLASS) semantics, an instance extension will be registered before extensions that are registered at the method level via @ExtendWith.

Example Usage

In the following example, the docs field in the test class is initialized programmatically by supplying a custom lookUpDocsDir() method to a static factory method in the DocumentationExtension. The configured DocumentationExtension will be automatically registered as an extension. In addition, test methods can access the instance of the extension via the docs field if necessary.

 class DocumentationTests {

     static Path lookUpDocsDir() {
         // return path to docs dir
     }

     @RegisterExtension
     DocumentationExtension docs =
         DocumentationExtension.forPath(lookUpDocsDir());

     @Test
     void generateDocumentation() {
         // use docs ...
     }
 }

Supported Extension APIs

• ExecutionCondition
• BeforeAllCallback
• AfterAllCallback
• BeforeEachCallback
• AfterEachCallback
• BeforeTestExecutionCallback
• AfterTestExecutionCallback
• TestInstancePostProcessor
• ParameterResolver
• TestExecutionExceptionHandler
• TestTemplateInvocationContextProvider

Since:

5.1

See Also:

ExtendWith, Extension