@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