Annotation Type RegisterExtension
-
@Target(FIELD) @Retention(RUNTIME) @Documented @API(status=STABLE, since="5.1") public @interface RegisterExtension@RegisterExtensionis used to register anExtensionvia a field in a test class.In contrast to
@ExtendWithwhich is used to register extensions declaratively,@RegisterExtensioncan be used to register an extension programmatically — for example, in order to pass arguments to the extension's constructor,staticfactory method, or builder API.@RegisterExtensionfields must not beprivateornull(when evaluated) but may be eitherstaticor non-static.Static Fields
If a
@RegisterExtensionfield isstatic, 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 asBeforeAllCallback,AfterAllCallback,TestInstanceFactory,TestInstancePostProcessorandTestInstancePreDestroyCallbackas well as method-level extension APIs such asBeforeEachCallback, etc.Instance Fields
If a
@RegisterExtensionfield is non-static (i.e., an instance field), the extension will be registered after the test class has been instantiated and after allTestInstancePostProcessorshave 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 asBeforeAllCallback,AfterAllCallback,TestInstanceFactory, orTestInstancePostProcessorthose 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.Inheritance
@RegisterExtensionfields are inherited from superclasses as long as they are not hidden or overridden. Furthermore,@RegisterExtensionfields from superclasses will be registered before@RegisterExtensionfields in subclasses.Registration Order
By default, if multiple extensions are registered via
@RegisterExtension, they will be ordered using an algorithm that is deterministic but intentionally nonobvious. This ensures that subsequent runs of a test suite execute extensions in the same order, thereby allowing for repeatable builds. However, there are times when extensions need to be registered in an explicit order. To achieve that, you can annotate@RegisterExtensionfields with@Order. Any@RegisterExtensionfield not annotated with@Orderwill be ordered using thedefaultorder value.Example Usage
In the following example, the
docsfield in the test class is initialized programmatically by supplying a customlookUpDocsDir()method to astaticfactory method in theDocumentationExtension. The configuredDocumentationExtensionwill be automatically registered as an extension. In addition, test methods can access the instance of the extension via thedocsfield 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
ExecutionConditionInvocationInterceptorBeforeAllCallbackAfterAllCallbackBeforeEachCallbackAfterEachCallbackBeforeTestExecutionCallbackAfterTestExecutionCallbackTestInstanceFactoryTestInstancePostProcessorTestInstancePreDestroyCallbackParameterResolverTestExecutionExceptionHandlerTestTemplateInvocationContextProviderTestWatcher
- Since:
- 5.1
- See Also:
@ExtendWith,Extension,@Order