[[extensions]] == Extension Model [[extensions-overview]] === Overview In contrast to the competing `Runner`, `TestRule`, and `MethodRule` extension points in JUnit 4, the JUnit Jupiter extension model consists of a single, coherent concept: the `Extension` API. Note, however, that `Extension` itself is just a marker interface. [[extensions-registration]] === Registering Extensions Extensions can be registered _declaratively_ via <>, _programmatically_ via <>, or _automatically_ via Java's <> mechanism. [[extensions-registration-declarative]] ==== Declarative Extension Registration Developers can register one or more extensions _declaratively_ by annotating a test interface, test class, test method, or custom _<>_ with `@ExtendWith(...)` and supplying class references for the extensions to register. As of JUnit Jupiter 5.8, `@ExtendWith` may also be declared on fields or on parameters in test class constructors, in test methods, and in `@BeforeAll`, `@AfterAll`, `@BeforeEach`, and `@AfterEach` lifecycle methods. For example, to register a `WebServerExtension` for a particular test method, you would annotate the test method as follows. We assume the `WebServerExtension` starts a local web server and injects the server's URL into parameters annotated with `@WebServerUrl`. [source,java,indent=0] ---- @Test @ExtendWith(WebServerExtension.class) void getProductList(@WebServerUrl String serverUrl) { WebClient webClient = new WebClient(); // Use WebClient to connect to web server using serverUrl and verify response assertEquals(200, webClient.get(serverUrl + "/products").getResponseStatus()); } ---- To register the `WebServerExtension` for all tests in a particular class and its subclasses, you would annotate the test class as follows. [source,java,indent=0] ---- @ExtendWith(WebServerExtension.class) class MyTests { // ... } ---- Multiple extensions can be registered together like this: [source,java,indent=0] ---- @ExtendWith({ DatabaseExtension.class, WebServerExtension.class }) class MyFirstTests { // ... } ---- As an alternative, multiple extensions can be registered separately like this: [source,java,indent=0] ---- @ExtendWith(DatabaseExtension.class) @ExtendWith(WebServerExtension.class) class MySecondTests { // ... } ---- [TIP] .Extension Registration Order ==== Extensions registered declaratively via `@ExtendWith` at the class level, method level, or parameter level will be executed in the order in which they are declared in the source code. For example, the execution of tests in both `MyFirstTests` and `MySecondTests` will be extended by the `DatabaseExtension` and `WebServerExtension`, **in exactly that order**. ==== If you wish to combine multiple extensions in a reusable way, you can define a custom _<>_ and use `@ExtendWith` as a _meta-annotation_ as in the following code listing. Then `@DatabaseAndWebServerExtension` can be used in place of `@ExtendWith({ DatabaseExtension.class, WebServerExtension.class })`. [source,java,indent=0] ---- @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @ExtendWith({ DatabaseExtension.class, WebServerExtension.class }) public @interface DatabaseAndWebServerExtension { } ---- The above examples demonstrate how `@ExtendWith` can be applied at the class level or at the method level; however, for certain use cases it makes sense for an extension to be registered declaratively at the field or parameter level. Consider a `RandomNumberExtension` which generates random numbers that can be injected into a field or via a parameter in a constructor, test method, or lifecycle method. If the extension provides a `@Random` annotation that is meta-annotated with `@ExtendWith(RandomNumberExtension.class)` (see listing below), the extension can be used transparently as in the following `RandomNumberDemo` example. [source,java,indent=0] ---- include::{testDir}/example/extensions/Random.java[tags=user_guide] ---- [source,java,indent=0] ---- include::{testDir}/example/extensions/RandomNumberDemo.java[tags=user_guide] ---- [[extensions-RandomNumberExtension]] The following code listing provides an example of how one might choose to implement such a `RandomNumberExtension`. This implementation works for the use cases in `RandomNumberDemo`; however, it may not prove robust enough to cover all use cases -- for example, the random number generation support is limited to integers; it uses `java.util.Random` instead of `java.security.SecureRandom`; etc. In any case, it is important to note which extension APIs are implemented and for what reasons. Specifically, `RandomNumberExtension` implements the following extension APIs: - `BeforeAllCallback`: to support static field injection - `BeforeEachCallback`: to support non-static field injection - `ParameterResolver`: to support constructor and method injection [NOTE] ==== Ideally, the `RandomNumberExtension` would implement `TestInstancePostProcessor` instead of `BeforeEachCallback` in order to support non-static field injection immediately after the test class has been instantiated. However, JUnit Jupiter currently does not allow a `TestInstancePostProcessor` to be registered via `@ExtendWith` on a non-static field (see link:{junit5-repo}/issues/3437[issue 3437]). In light of that, the `RandomNumberExtension` implements `BeforeEachCallback` as an alternative approach. ==== [source,java,indent=0] ---- include::{testDir}/example/extensions/RandomNumberExtension.java[tags=user_guide] ---- [TIP] .Extension Registration Order for `@ExtendWith` on Fields ==== Extensions registered declaratively via `@ExtendWith` on fields will be ordered relative to `@RegisterExtension` fields and other `@ExtendWith` fields using an algorithm that is deterministic but intentionally nonobvious. However, `@ExtendWith` fields can be ordered using the `@Order` annotation. See the <> tip for `@RegisterExtension` fields for details. ==== NOTE: `@ExtendWith` fields may be either `static` or non-static. The documentation on <> and <> for `@RegisterExtension` fields also applies to `@ExtendWith` fields. [[extensions-registration-programmatic]] ==== Programmatic Extension Registration Developers can register extensions _programmatically_ by annotating fields in test classes with `{RegisterExtension}`. When an extension is registered _declaratively_ via <>, it can typically only be configured via annotations. In contrast, when an extension is registered via `@RegisterExtension`, it can be configured _programmatically_ -- for example, in order to pass arguments to the extension's constructor, a static factory method, or a builder API. [[extensions-registration-programmatic-order]] [TIP] .Extension Registration Order ==== By default, extensions registered programmatically via `@RegisterExtension` or declaratively via `@ExtendWith` on fields 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 `@RegisterExtension` fields or `@ExtendWith` fields with `{Order}`. Any `@RegisterExtension` field or `@ExtendWith` field not annotated with `@Order` will be ordered using the _default_ order which has a value of `Integer.MAX_VALUE / 2`. This allows `@Order` annotated extension fields to be explicitly ordered before or after non-annotated extension fields. Extensions with an explicit order value less than the default order value will be registered before non-annotated extensions. Similarly, extensions with an explicit order value greater than the default order value will be registered after non-annotated extensions. For example, assigning an extension an explicit order value that is greater than the default order value allows _before_ callback extensions to be registered last and _after_ callback extensions to be registered first, relative to other programmatically registered extensions. ==== NOTE: `@RegisterExtension` fields must not be `null` (at evaluation time) but may be either `static` or non-static. [[extensions-registration-programmatic-static-fields]] ===== 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`, `TestInstancePostProcessor`, and `TestInstancePreDestroyCallback` as well as method-level extension APIs such as `BeforeEachCallback`, etc. In the following example, the `server` field in the test class is initialized programmatically by using a builder pattern supported by the `WebServerExtension`. The configured `WebServerExtension` will be automatically registered as an extension at the class level -- for example, in order to start the server before all tests in the class and then stop the server after all tests in the class have completed. In addition, static lifecycle methods annotated with `@BeforeAll` or `@AfterAll` as well as `@BeforeEach`, `@AfterEach`, and `@Test` methods can access the instance of the extension via the `server` field if necessary. [source,java,indent=0] .Registering an extension via a static field in Java ---- include::{testDir}/example/registration/WebServerDemo.java[tags=user_guide] ---- [[extensions-registration-programmatic-static-fields-kotlin]] ====== Static Fields in Kotlin The Kotlin programming language does not have the concept of a `static` field. However, the compiler can be instructed to generate a `private static` field using the `@JvmStatic` annotation in Kotlin. If you want the Kotlin compiler to generate a `public static` field, you can use the `@JvmField` annotation instead. The following example is a version of the `WebServerDemo` from the previous section that has been ported to Kotlin. [source,kotlin,indent=0] .Registering an extension via a static field in Kotlin ---- include::{kotlinTestDir}/example/registration/KotlinWebServerDemo.kt[tags=user_guide] ---- [[extensions-registration-programmatic-instance-fields]] ===== 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 each registered `TestInstancePostProcessor` has 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 invoking a custom `lookUpDocsDir()` method and supplying the result to the static `forPath()` factory method in the `DocumentationExtension`. The configured `DocumentationExtension` will be automatically registered as an extension at the method level. In addition, `@BeforeEach`, `@AfterEach`, and `@Test` methods can access the instance of the extension via the `docs` field if necessary. [source,java,indent=0] .An extension registered via an instance field ---- include::{testDir}/example/registration/DocumentationDemo.java[tags=user_guide] ---- [[extensions-registration-automatic]] ==== Automatic Extension Registration In addition to <> and <> support using annotations, JUnit Jupiter also supports _global extension registration_ via Java's `{ServiceLoader}` mechanism, allowing third-party extensions to be auto-detected and automatically registered based on what is available in the classpath. Specifically, a custom extension can be registered by supplying its fully qualified class name in a file named `org.junit.jupiter.api.extension.Extension` within the `/META-INF/services` folder in its enclosing JAR file. [[extensions-registration-automatic-enabling]] ===== Enabling Automatic Extension Detection Auto-detection is an advanced feature and is therefore not enabled by default. To enable it, set the `junit.jupiter.extensions.autodetection.enabled` _configuration parameter_ to `true`. This can be supplied as a JVM system property, as a _configuration parameter_ in the `LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform configuration file (see <> for details). For example, to enable auto-detection of extensions, you can start your JVM with the following system property. `-Djunit.jupiter.extensions.autodetection.enabled=true` When auto-detection is enabled, extensions discovered via the `{ServiceLoader}` mechanism will be added to the extension registry after JUnit Jupiter's global extensions (e.g., support for `TestInfo`, `TestReporter`, etc.). [[extensions-registration-inheritance]] ==== Extension Inheritance Registered extensions are inherited within test class hierarchies with top-down semantics. Similarly, extensions registered at the class-level are inherited at the method-level. Furthermore, a specific extension implementation can only be registered once for a given extension context and its parent contexts. Consequently, any attempt to register a duplicate extension implementation will be ignored. [[extensions-conditions]] === Conditional Test Execution `{ExecutionCondition}` defines the `Extension` API for programmatic, _conditional test execution_. An `ExecutionCondition` is _evaluated_ for each container (e.g., a test class) to determine if all the tests it contains should be executed based on the supplied `ExtensionContext`. Similarly, an `ExecutionCondition` is _evaluated_ for each test to determine if a given test method should be executed based on the supplied `ExtensionContext`. When multiple `ExecutionCondition` extensions are registered, a container or test is disabled as soon as one of the conditions returns _disabled_. Thus, there is no guarantee that a condition is evaluated because another extension might have already caused a container or test to be disabled. In other words, the evaluation works like the short-circuiting boolean OR operator. See the source code of `{DisabledCondition}` and `{Disabled}` for concrete examples. [[extensions-conditions-deactivation]] ==== Deactivating Conditions Sometimes it can be useful to run a test suite _without_ certain conditions being active. For example, you may wish to run tests even if they are annotated with `@Disabled` in order to see if they are still _broken_. To do this, provide a pattern for the `junit.jupiter.conditions.deactivate` _configuration parameter_ to specify which conditions should be deactivated (i.e., not evaluated) for the current test run. The pattern can be supplied as a JVM system property, as a _configuration parameter_ in the `LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform configuration file (see <> for details). For example, to deactivate JUnit's `@Disabled` condition, you can start your JVM with the following system property. `-Djunit.jupiter.conditions.deactivate=org.junit.*DisabledCondition` [[extensions-conditions-deactivation-patterns]] ===== Pattern Matching Syntax Refer to <> for details. [[extensions-test-instance-pre-construct-callback]] === Test Instance Pre-construct Callback `{TestInstancePreConstructCallback}` defines the API for `Extensions` that wish to be invoked _prior_ to test instances being constructed (by a constructor call or via `{TestInstanceFactory}`). This extension provides a symmetric call to `{TestInstancePreDestroyCallback}` and is useful in combination with other extensions to prepare constructor parameters or keeping track of test instances and their lifecycle. [[extensions-test-instance-factories]] === Test Instance Factories `{TestInstanceFactory}` defines the API for `Extensions` that wish to _create_ test class instances. Common use cases include acquiring the test instance from a dependency injection framework or invoking a static factory method to create the test class instance. If no `TestInstanceFactory` is registered, the framework will invoke the _sole_ constructor for the test class to instantiate it, potentially resolving constructor arguments via registered `ParameterResolver` extensions. Extensions that implement `TestInstanceFactory` can be registered on test interfaces, top-level test classes, or `@Nested` test classes. [WARNING] ==== Registering multiple extensions that implement `TestInstanceFactory` for any single class will result in an exception being thrown for all tests in that class, in any subclass, and in any nested class. Note that any `TestInstanceFactory` registered in a superclass or _enclosing_ class (i.e., in the case of a `@Nested` test class) is _inherited_. It is the user's responsibility to ensure that only a single `TestInstanceFactory` is registered for any specific test class. ==== [[extensions-test-instance-post-processing]] === Test Instance Post-processing `{TestInstancePostProcessor}` defines the API for `Extensions` that wish to _post process_ test instances. Common use cases include injecting dependencies into the test instance, invoking custom initialization methods on the test instance, etc. For a concrete example, consult the source code for the `{MockitoExtension}` and the `{SpringExtension}`. [[extensions-test-instance-pre-destroy-callback]] === Test Instance Pre-destroy Callback `{TestInstancePreDestroyCallback}` defines the API for `Extensions` that wish to process test instances _after_ they have been used in tests and _before_ they are destroyed. Common use cases include cleaning dependencies that have been injected into the test instance, invoking custom de-initialization methods on the test instance, etc. [[extensions-parameter-resolution]] === Parameter Resolution `{ParameterResolver}` defines the `Extension` API for dynamically resolving parameters at runtime. If a _test class_ constructor, _test method_, or _lifecycle method_ (see <>) declares a parameter, the parameter must be _resolved_ at runtime by a `ParameterResolver`. A `ParameterResolver` can either be built-in (see `{TestInfoParameterResolver}`) or <>. Generally speaking, parameters may be resolved by _name_, _type_, _annotation_, or any combination thereof. If you wish to implement a custom `{ParameterResolver}` that resolves parameters based solely on the type of the parameter, you may find it convenient to extend the `{TypeBasedParameterResolver}` which serves as a generic adapter for such use cases. For concrete examples, consult the source code for `{CustomTypeParameterResolver}`, `{CustomAnnotationParameterResolver}`, and `{MapOfListsTypeBasedParameterResolver}`. [WARNING] ==== Due to a bug in the byte code generated by `javac` on JDK versions prior to JDK 9, looking up annotations on parameters directly via the core `java.lang.reflect.Parameter` API will always fail for _inner class_ constructors (e.g., a constructor in a `@Nested` test class). The `{ParameterContext}` API supplied to `ParameterResolver` implementations therefore includes the following convenience methods for correctly looking up annotations on parameters. Extension authors are strongly encouraged to use these methods instead of those provided in `java.lang.reflect.Parameter` in order to avoid this bug in the JDK. * `boolean isAnnotated(Class annotationType)` * `Optional findAnnotation(Class annotationType)` * `List findRepeatableAnnotations(Class annotationType)` ==== [NOTE] ==== Other extensions can also leverage registered `ParameterResolvers` for method and constructor invocations, using the `{ExecutableInvoker}` available via the `getExecutableInvoker()` method in the `ExtensionContext`. ==== [[extensions-test-result-processing]] === Test Result Processing `{TestWatcher}` defines the API for extensions that wish to process the results of _test method_ executions. Specifically, a `TestWatcher` will be invoked with contextual information for the following events. * `testDisabled`: invoked after a disabled _test method_ has been skipped * `testSuccessful`: invoked after a _test method_ has completed successfully * `testAborted`: invoked after a _test method_ has been aborted * `testFailed`: invoked after a _test method_ has failed NOTE: In contrast to the definition of "test method" presented in <>, in this context _test method_ refers to any `@Test` method or `@TestTemplate` method (for example, a `@RepeatedTest` or `@ParameterizedTest`). Extensions implementing this interface can be registered at the class level, instance level, or method level. When registered at the class level, a `TestWatcher` will be invoked for any contained _test method_ including those in `@Nested` classes. When registered at the method level, a `TestWatcher` will only be invoked for the _test method_ for which it was registered. [WARNING] ==== If a `TestWatcher` is registered via a non-static (instance) field – for example, using `@RegisterExtension` – and the test class is configured with `@TestInstance(Lifecycle.PER_METHOD)` semantics (which is the default lifecycle mode), the `TestWatcher` will **not** be invoked with events for `@TestTemplate` methods (for example, `@RepeatedTest` or `@ParameterizedTest`). To ensure that a `TestWatcher` is invoked for all _test methods_ in a given class, it is therefore recommended that the `TestWatcher` be registered at the class level with `@ExtendWith` or via a `static` field with `@RegisterExtension` or `@ExtendWith`. ==== If there is a failure at the class level — for example, an exception thrown by a `@BeforeAll` method — no test results will be reported. Similarly, if the test class is disabled via an `ExecutionCondition` — for example, `@Disabled` — no test results will be reported. In contrast to other Extension APIs, a `TestWatcher` is not permitted to adversely influence the execution of tests. Consequently, any exception thrown by a method in the `TestWatcher` API will be logged at `WARNING` level and will not be allowed to propagate or fail test execution. [WARNING] ==== Any instances of `ExtensionContext.Store.CloseableResource` stored in the `Store` of the provided `{ExtensionContext}` will be closed _before_ methods in the `TestWatcher` API are invoked (see <>). You can use the parent context's `Store` to work with such resources. ==== [[extensions-lifecycle-callbacks]] === Test Lifecycle Callbacks The following interfaces define the APIs for extending tests at various points in the test execution lifecycle. Consult the following sections for examples and the Javadoc for each of these interfaces in the `{extension-api-package}` package for further details. * `{BeforeAllCallback}` ** `{BeforeEachCallback}` *** `{BeforeTestExecutionCallback}` *** `{AfterTestExecutionCallback}` ** `{AfterEachCallback}` * `{AfterAllCallback}` .Implementing Multiple Extension APIs NOTE: Extension developers may choose to implement any number of these interfaces within a single extension. Consult the source code of the `{SpringExtension}` for a concrete example. [[extensions-lifecycle-callbacks-before-after-execution]] ==== Before and After Test Execution Callbacks `{BeforeTestExecutionCallback}` and `{AfterTestExecutionCallback}` define the APIs for `Extensions` that wish to add behavior that will be executed _immediately before_ and _immediately after_ a test method is executed, respectively. As such, these callbacks are well suited for timing, tracing, and similar use cases. If you need to implement callbacks that are invoked _around_ `@BeforeEach` and `@AfterEach` methods, implement `BeforeEachCallback` and `AfterEachCallback` instead. The following example shows how to use these callbacks to calculate and log the execution time of a test method. `TimingExtension` implements both `BeforeTestExecutionCallback` and `AfterTestExecutionCallback` in order to time and log the test execution. [[extensions-lifecycle-callbacks-timing-extension]] [source,java,indent=0] .An extension that times and logs the execution of test methods ---- include::{testDir}/example/timing/TimingExtension.java[tags=user_guide] ---- Since the `TimingExtensionTests` class registers the `TimingExtension` via `@ExtendWith`, its tests will have this timing applied when they execute. [source,java,indent=0] .A test class that uses the example TimingExtension ---- include::{testDir}/example/timing/TimingExtensionTests.java[tags=user_guide] ---- The following is an example of the logging produced when `TimingExtensionTests` is run. .... INFO: Method [sleep20ms] took 24 ms. INFO: Method [sleep50ms] took 53 ms. .... [[extensions-exception-handling]] === Exception Handling Exceptions thrown during the test execution may be intercepted and handled accordingly before propagating further, so that certain actions like error logging or resource releasing may be defined in specialized `Extensions`. JUnit Jupiter offers API for `Extensions` that wish to handle exceptions thrown during `@Test` methods via `{TestExecutionExceptionHandler}` and for those thrown during one of test lifecycle methods (`@BeforeAll`, `@BeforeEach`, `@AfterEach` and `@AfterAll`) via `{LifecycleMethodExecutionExceptionHandler}`. The following example shows an extension which will swallow all instances of `IOException` but rethrow any other type of exception. [source,java,indent=0] .An exception handling extension that filters IOExceptions in test execution ---- include::{testDir}/example/exception/IgnoreIOExceptionExtension.java[tags=user_guide] ---- Another example shows how to record the state of an application under test exactly at the point of unexpected exception being thrown during setup and cleanup. Note that unlike relying on lifecycle callbacks, which may or may not be executed depending on the test status, this solution guarantees execution immediately after failing `@BeforeAll`, `@BeforeEach`, `@AfterEach` or `@AfterAll`. [source,java,indent=0] .An exception handling extension that records application state on error ---- include::{testDir}/example/exception/RecordStateOnErrorExtension.java[tags=user_guide] ---- Multiple execution exception handlers may be invoked for the same lifecycle method in order of declaration. If one of the handlers swallows the handled exception, subsequent ones will not be executed, and no failure will be propagated to JUnit engine, as if the exception was never thrown. Handlers may also choose to rethrow the exception or throw a different one, potentially wrapping the original. Extensions implementing `{LifecycleMethodExecutionExceptionHandler}` that wish to handle exceptions thrown during `@BeforeAll` or `@AfterAll` need to be registered on a class level, while handlers for `BeforeEach` and `AfterEach` may be also registered for individual test methods. [source,java,indent=0] .Registering multiple exception handling extensions ---- include::{testDir}/example/exception/MultipleHandlersTestCase.java[tags=user_guide] ---- [[extensions-intercepting-invocations]] === Intercepting Invocations `{InvocationInterceptor}` defines the API for `Extensions` that wish to intercept calls to test code. The following example shows an extension that executes all test methods in Swing's Event Dispatch Thread. [source,java,indent=0] .An extension that executes tests in a user-defined thread ---- include::{testDir}/example/interceptor/SwingEdtInterceptor.java[tags=user_guide] ---- [[extensions-test-templates]] === Providing Invocation Contexts for Test Templates A `{TestTemplate}` method can only be executed when at least one `{TestTemplateInvocationContextProvider}` is registered. Each such provider is responsible for providing a `Stream` of `{TestTemplateInvocationContext}` instances. Each context may specify a custom display name and a list of additional extensions that will only be used for the next invocation of the `{TestTemplate}` method. The following example shows how to write a test template as well as how to register and implement a `{TestTemplateInvocationContextProvider}`. [source,java,indent=0] .A test template with accompanying extension ---- include::{testDir}/example/TestTemplateDemo.java[tags=user_guide] ---- In this example, the test template will be invoked twice. The display names of the invocations will be `apple` and `banana` as specified by the invocation context. Each invocation registers a custom `{ParameterResolver}` which is used to resolve the method parameter. The output when using the `ConsoleLauncher` is as follows. .... └─ testTemplate(String) ✔ ├─ apple ✔ └─ banana ✔ .... The `{TestTemplateInvocationContextProvider}` extension API is primarily intended for implementing different kinds of tests that rely on repetitive invocation of a test-like method albeit in different contexts — for example, with different parameters, by preparing the test class instance differently, or multiple times without modifying the context. Please refer to the implementations of <> or <> which use this extension point to provide their functionality. [[extensions-keeping-state]] === Keeping State in Extensions Usually, an extension is instantiated only once. So the question becomes relevant: How do you keep the state from one invocation of an extension to the next? The `ExtensionContext` API provides a `Store` exactly for this purpose. Extensions may put values into a store for later retrieval. See the `<>` for an example of using the `Store` with a method-level scope. It is important to remember that values stored in an `ExtensionContext` during test execution will not be available in the surrounding `ExtensionContext`. Since `ExtensionContexts` may be nested, the scope of inner contexts may also be limited. Consult the corresponding Javadoc for details on the methods available for storing and retrieving values via the `{ExtensionContext_Store}`. .`ExtensionContext.Store.CloseableResource` NOTE: An extension context store is bound to its extension context lifecycle. When an extension context lifecycle ends it closes its associated store. All stored values that are instances of `CloseableResource` are notified by an invocation of their `close()` method in the inverse order they were added in. [[extensions-supported-utilities]] === Supported Utilities in Extensions The `junit-platform-commons` artifact exposes a package named `{junit-platform-support-package}` that contains _maintained_ utility methods for working with annotations, classes, reflection, and classpath scanning tasks. `TestEngine` and `Extension` authors are encouraged to use these supported methods in order to align with the behavior of the JUnit Platform. [[extensions-supported-utilities-annotations]] ==== Annotation Support `AnnotationSupport` provides static utility methods that operate on annotated elements (e.g., packages, annotations, classes, interfaces, constructors, methods, and fields). These include methods to check whether an element is annotated or meta-annotated with a particular annotation, to search for specific annotations, and to find annotated methods and fields in a class or interface. Some of these methods search on implemented interfaces and within class hierarchies to find annotations. Consult the Javadoc for `{AnnotationSupport}` for further details. [[extensions-supported-utilities-classes]] ==== Class Support `ClassSupport` provides static utility methods for working with classes (i.e., instances of `java.lang.Class`). Consult the Javadoc for `{ClassSupport}` for further details. [[extensions-supported-utilities-reflection]] ==== Reflection Support `ReflectionSupport` provides static utility methods that augment the standard JDK reflection and class-loading mechanisms. These include methods to scan the classpath in search of classes matching specified predicates, to load and create new instances of a class, and to find and invoke methods. Some of these methods traverse class hierarchies to locate matching methods. Consult the Javadoc for `{ReflectionSupport}` for further details. [[extensions-supported-utilities-modifier]] ==== Modifier Support `ModifierSupport` provides static utility methods for working with member and class modifiers -- for example, to determine if a member is declared as `public`, `private`, `abstract`, `static`, etc. Consult the Javadoc for `{ModifierSupport}` for further details. [[extensions-execution-order]] === Relative Execution Order of User Code and Extensions When executing a test class that contains one or more test methods, a number of extension callbacks are called in addition to the user-supplied test and lifecycle methods. NOTE: See also: <> [[extensions-execution-order-overview]] ==== User and Extension Code The following diagram illustrates the relative order of user-supplied code and extension code. User-supplied test and lifecycle methods are shown in orange, with callback code implemented by extensions shown in blue. The grey box denotes the execution of a single test method and will be repeated for every test method in the test class. :figure-caption: User code and extension code [#extensions-execution-order-diagram,reftext='{figure-caption}'] image::extensions_lifecycle.png[caption='',title='{figure-caption}'] The following table further explains the sixteen steps in the <> diagram. [cols="5,15,80"] |=== | Step | Interface/Annotation | Description | 1 | interface `org.junit.jupiter.api.extension.BeforeAllCallback` | extension code executed before all tests of the container are executed | 2 | annotation `org.junit.jupiter.api.BeforeAll` | user code executed before all tests of the container are executed | 3 | interface `org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler #handleBeforeAllMethodExecutionException` | extension code for handling exceptions thrown from `@BeforeAll` methods | 4 | interface `org.junit.jupiter.api.extension.BeforeEachCallback` | extension code executed before each test is executed | 5 | annotation `org.junit.jupiter.api.BeforeEach` | user code executed before each test is executed | 6 | interface `org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler #handleBeforeEachMethodExecutionException` | extension code for handling exceptions thrown from `@BeforeEach` methods | 7 | interface `org.junit.jupiter.api.extension.BeforeTestExecutionCallback` | extension code executed immediately before a test is executed | 8 | annotation `org.junit.jupiter.api.Test` | user code of the actual test method | 9 | interface `org.junit.jupiter.api.extension.TestExecutionExceptionHandler` | extension code for handling exceptions thrown during a test | 10 | interface `org.junit.jupiter.api.extension.AfterTestExecutionCallback` | extension code executed immediately after test execution and its corresponding exception handlers | 11 | annotation `org.junit.jupiter.api.AfterEach` | user code executed after each test is executed | 12 | interface `org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler #handleAfterEachMethodExecutionException` | extension code for handling exceptions thrown from `@AfterEach` methods | 13 | interface `org.junit.jupiter.api.extension.AfterEachCallback` | extension code executed after each test is executed | 14 | annotation `org.junit.jupiter.api.AfterAll` | user code executed after all tests of the container are executed | 15 | interface `org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler #handleAfterAllMethodExecutionException` | extension code for handling exceptions thrown from `@AfterAll` methods | 16 | interface `org.junit.jupiter.api.extension.AfterAllCallback` | extension code executed after all tests of the container are executed |=== In the simplest case only the actual test method will be executed (step 8); all other steps are optional depending on the presence of user code or extension support for the corresponding lifecycle callback. For further details on the various lifecycle callbacks please consult the respective Javadoc for each annotation and extension. All invocations of user code methods in the above table can additionally be intercepted by implementing <>. [[extensions-execution-order-wrapping-behavior]] ==== Wrapping Behavior of Callbacks JUnit Jupiter always guarantees _wrapping_ behavior for multiple registered extensions that implement lifecycle callbacks such as `BeforeAllCallback`, `AfterAllCallback`, `BeforeEachCallback`, `AfterEachCallback`, `BeforeTestExecutionCallback`, and `AfterTestExecutionCallback`. That means that, given two extensions `Extension1` and `Extension2` with `Extension1` registered before `Extension2`, any "before" callbacks implemented by `Extension1` are guaranteed to execute **before** any "before" callbacks implemented by `Extension2`. Similarly, given the two same two extensions registered in the same order, any "after" callbacks implemented by `Extension1` are guaranteed to execute **after** any "after" callbacks implemented by `Extension2`. `Extension1` is therefore said to _wrap_ `Extension2`. JUnit Jupiter also guarantees _wrapping_ behavior within class and interface hierarchies for user-supplied _lifecycle methods_ (see <>). * `@BeforeAll` methods are inherited from superclasses as long as they are not _hidden_, _overridden_, or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules). Furthermore, `@BeforeAll` methods from superclasses will be executed **before** `@BeforeAll` methods in subclasses. ** Similarly, `@BeforeAll` methods declared in an interface are inherited as long as they are not _hidden_ or _overridden_, and `@BeforeAll` methods from an interface will be executed **before** `@BeforeAll` methods in the class that implements the interface. * `@AfterAll` methods are inherited from superclasses as long as they are not _hidden_, _overridden_, or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules). Furthermore, `@AfterAll` methods from superclasses will be executed **after** `@AfterAll` methods in subclasses. ** Similarly, `@AfterAll` methods declared in an interface are inherited as long as they are not _hidden_ or _overridden_, and `@AfterAll` methods from an interface will be executed **after** `@AfterAll` methods in the class that implements the interface. * `@BeforeEach` methods are inherited from superclasses as long as they are not _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules). Furthermore, `@BeforeEach` methods from superclasses will be executed **before** `@BeforeEach` methods in subclasses. ** Similarly, `@BeforeEach` methods declared as interface default methods are inherited as long as they are not _overridden_, and `@BeforeEach` default methods will be executed **before** `@BeforeEach` methods in the class that implements the interface. * `@AfterEach` methods are inherited from superclasses as long as they are not _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules). Furthermore, `@AfterEach` methods from superclasses will be executed **after** `@AfterEach` methods in subclasses. ** Similarly, `@AfterEach` methods declared as interface default methods are inherited as long as they are not _overridden_, and `@AfterEach` default methods will be executed **after** `@AfterEach` methods in the class that implements the interface. The following examples demonstrate this behavior. Please note that the examples do not actually do anything realistic. Instead, they mimic common scenarios for testing interactions with the database. All methods imported statically from the `Logger` class log contextual information in order to help us better understand the execution order of user-supplied callback methods and callback methods in extensions. [source,java,indent=0] .Extension1 ---- include::{testDir}/example/callbacks/Extension1.java[tags=user_guide] ---- [source,java,indent=0] .Extension2 ---- include::{testDir}/example/callbacks/Extension2.java[tags=user_guide] ---- [source,java,indent=0] .AbstractDatabaseTests ---- include::{testDir}/example/callbacks/AbstractDatabaseTests.java[tags=user_guide] ---- [source,java,indent=0] .DatabaseTestsDemo ---- include::{testDir}/example/callbacks/DatabaseTestsDemo.java[tags=user_guide] ---- When the `DatabaseTestsDemo` test class is executed, the following is logged. ---- @BeforeAll AbstractDatabaseTests.createDatabase() @BeforeAll DatabaseTestsDemo.beforeAll() Extension1.beforeEach() Extension2.beforeEach() @BeforeEach AbstractDatabaseTests.connectToDatabase() @BeforeEach DatabaseTestsDemo.insertTestDataIntoDatabase() @Test DatabaseTestsDemo.testDatabaseFunctionality() @AfterEach DatabaseTestsDemo.deleteTestDataFromDatabase() @AfterEach AbstractDatabaseTests.disconnectFromDatabase() Extension2.afterEach() Extension1.afterEach() @BeforeAll DatabaseTestsDemo.afterAll() @AfterAll AbstractDatabaseTests.destroyDatabase() ---- The following sequence diagram helps to shed further light on what actually goes on within the `JupiterTestEngine` when the `DatabaseTestsDemo` test class is executed. //// PNG generated using ZenUML: https://app.zenuml.com See corresponding *.txt file in images folder for the source. //// image::extensions_DatabaseTestsDemo.png[caption='',title='DatabaseTestsDemo'] JUnit Jupiter does **not** guarantee the execution order of multiple lifecycle methods that are declared within a _single_ test class or test interface. It may at times appear that JUnit Jupiter invokes such methods in alphabetical order. However, that is not precisely true. The ordering is analogous to the ordering for `@Test` methods within a single test class. [NOTE] ==== Lifecycle methods that are declared within a _single_ test class or test interface will be ordered using an algorithm that is deterministic but intentionally non-obvious. This ensures that subsequent runs of a test suite execute lifecycle methods in the same order, thereby allowing for repeatable builds. ==== In addition, JUnit Jupiter does **not** support _wrapping_ behavior for multiple lifecycle methods declared within a single test class or test interface. The following example demonstrates this behavior. Specifically, the lifecycle method configuration is _broken_ due to the order in which the locally declared lifecycle methods are executed. * Test data is inserted _before_ the database connection has been opened, which results in a failure to connect to the database. * The database connection is closed _before_ deleting the test data, which results in a failure to connect to the database. [source,java,indent=0] .BrokenLifecycleMethodConfigDemo ---- include::{testDir}/example/callbacks/BrokenLifecycleMethodConfigDemo.java[tags=user_guide] ---- When the `BrokenLifecycleMethodConfigDemo` test class is executed, the following is logged. ---- Extension1.beforeEach() Extension2.beforeEach() @BeforeEach BrokenLifecycleMethodConfigDemo.insertTestDataIntoDatabase() @BeforeEach BrokenLifecycleMethodConfigDemo.connectToDatabase() @Test BrokenLifecycleMethodConfigDemo.testDatabaseFunctionality() @AfterEach BrokenLifecycleMethodConfigDemo.disconnectFromDatabase() @AfterEach BrokenLifecycleMethodConfigDemo.deleteTestDataFromDatabase() Extension2.afterEach() Extension1.afterEach() ---- The following sequence diagram helps to shed further light on what actually goes on within the `JupiterTestEngine` when the `BrokenLifecycleMethodConfigDemo` test class is executed. //// PNG generated using ZenUML: https://app.zenuml.com See corresponding *.txt file in images folder for the source. //// image::extensions_BrokenLifecycleMethodConfigDemo.png[caption='',title='BrokenLifecycleMethodConfigDemo'] [TIP] ==== Due to the aforementioned behavior, the JUnit Team recommends that developers declare at most one of each type of _lifecycle method_ (see <>) per test class or test interface unless there are no dependencies between such lifecycle methods. ====