@Target(value=FIELD) @Retention(value=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 ... } }
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, annotate each
@RegisterExtension
field with @Order
.
Any @RegisterExtension
field not annotated with @Order
will
appear at the end of the sorted list.
@ExtendWith
,
Extension
,
@Order
Copyright © 2021. All rights reserved.