@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.
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.
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
.
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 ... } }
ExtendWith
,
Extension