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, andTestInstancePostProcessoras 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, 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.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
- Since:
- 5.1
- See Also:
ExtendWith,Extension