Annotation 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 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
,
TestInstanceFactory
, TestInstancePostProcessor
and
TestInstancePreDestroyCallback
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
,
TestInstanceFactory
, 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
.
Inheritance
@RegisterExtension
fields are inherited from superclasses as long
as they are not hidden or overridden. Furthermore,
@RegisterExtension
fields from superclasses will be registered before
@RegisterExtension
fields 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
@RegisterExtension
fields with @Order
.
Any @RegisterExtension
field not annotated with @Order
will be
ordered using the default
order
value. Note that @ExtendWith
fields can also be ordered with
@Order
, relative to @RegisterExtension
fields and other
@ExtendWith
fields.
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
InvocationInterceptor
BeforeAllCallback
AfterAllCallback
BeforeEachCallback
AfterEachCallback
BeforeTestExecutionCallback
AfterTestExecutionCallback
TestInstanceFactory
TestInstancePostProcessor
TestInstancePreDestroyCallback
ParameterResolver
TestExecutionExceptionHandler
TestTemplateInvocationContextProvider
TestWatcher
- Since:
- 5.1
- See Also:
@ExtendWith
,Extension
,@Order