ExtensionContext
encapsulates the context in which the
current test or container is being executed.
Extensions
are provided an instance of
ExtensionContext
to perform their work.
- Since:
- 5.0
- See Also:
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic class
ANamespace
is used to provide a scope for data saved by extensions within aExtensionContext.Store
.static interface
Store
provides methods for extensions to save and retrieve data. -
Method Summary
Modifier and TypeMethodDescriptionGet the configuration parameter stored under the specifiedkey
.<T> Optional<T>
getConfigurationParameter
(String key, Function<String, T> transformer) Get and transform the configuration parameter stored under the specifiedkey
using the specifiedtransformer
.Get the display name for the current test or container.Get theAnnotatedElement
corresponding to the current extension context, if available.Get anExecutableInvoker
to invoke methods and constructors with support for dynamic resolution of parameters.Get the exception that was thrown during execution of the test or container associated with thisExtensionContext
, if available.Get theExecutionMode
associated with the current test or container.Get the parent extension context, if available.default Class<?>
Get the requiredClass
associated with the current test or container.default Object
Get the required test instance associated with the current test or container.default TestInstances
Get the required test instances associated with the current test or container.default Method
Get the requiredMethod
associated with the current test or container.getRoot()
Get the rootExtensionContext
.getStore
(ExtensionContext.Namespace namespace) Get theExtensionContext.Store
for the suppliedExtensionContext.Namespace
.getTags()
Get the set of all tags for the current test or container.Get theClass
associated with the current test or container, if available.Get the test instance associated with the current test or container, if available.Get theTestInstance.Lifecycle
of the test instance associated with the current test or container, if available.Get the test instances associated with the current test or container, if available.Get theMethod
associated with the current test, if available.Get the unique ID of the current test or container.default void
publishReportEntry
(String value) Publish the specified value to be consumed by anorg.junit.platform.engine.EngineExecutionListener
in order to supply additional information to the reporting infrastructure.default void
publishReportEntry
(String key, String value) Publish the specified key-value pair to be consumed by anorg.junit.platform.engine.EngineExecutionListener
in order to supply additional information to the reporting infrastructure.void
publishReportEntry
(Map<String, String> map) Publish a map of key-value pairs to be consumed by anorg.junit.platform.engine.EngineExecutionListener
in order to supply additional information to the reporting infrastructure.
-
Method Details
-
getParent
Optional<ExtensionContext> getParent()Get the parent extension context, if available.- Returns:
- an
Optional
containing the parent; nevernull
but potentially empty - See Also:
-
getRoot
ExtensionContext getRoot()Get the rootExtensionContext
.- Returns:
- the root extension context; never
null
but potentially thisExtensionContext
- See Also:
-
getUniqueId
String getUniqueId()Get the unique ID of the current test or container.- Returns:
- the unique ID of the test or container; never
null
or blank
-
getDisplayName
String getDisplayName()Get the display name for the current test or container.The display name is either a default name or a custom name configured via
@DisplayName
.For details on default display names consult the Javadoc for
TestInfo.getDisplayName()
.Note that display names are typically used for test reporting in IDEs and build tools and may contain spaces, special characters, and even emoji.
- Returns:
- the display name of the test or container; never
null
or blank
-
getTags
Get the set of all tags for the current test or container.Tags may be declared directly on the test element or inherited from an outer context.
- Returns:
- the set of tags for the test or container; never
null
but potentially empty
-
getElement
Optional<AnnotatedElement> getElement()Get theAnnotatedElement
corresponding to the current extension context, if available.For example, if the current extension context encapsulates a test class, test method, test factory method, or test template method, the annotated element will be the corresponding
Class
orMethod
reference.Favor this method over more specific methods whenever the
AnnotatedElement
API suits the task at hand — for example, when looking up annotations regardless of concrete element type.- Returns:
- an
Optional
containing theAnnotatedElement
; nevernull
but potentially empty - See Also:
-
getTestClass
Get theClass
associated with the current test or container, if available.- Returns:
- an
Optional
containing the class; nevernull
but potentially empty - See Also:
-
getRequiredTestClass
Get the requiredClass
associated with the current test or container.Use this method as an alternative to
getTestClass()
for use cases in which the test class is required to be present.- Returns:
- the test class; never
null
- Throws:
PreconditionViolationException
- if the test class is not present in thisExtensionContext
-
getTestInstanceLifecycle
Get theTestInstance.Lifecycle
of the test instance associated with the current test or container, if available.- Returns:
- an
Optional
containing the test instanceLifecycle
; nevernull
but potentially empty - Since:
- 5.1
- See Also:
-
getTestInstance
Get the test instance associated with the current test or container, if available.- Returns:
- an
Optional
containing the test instance; nevernull
but potentially empty - See Also:
-
getRequiredTestInstance
Get the required test instance associated with the current test or container.Use this method as an alternative to
getTestInstance()
for use cases in which the test instance is required to be present.- Returns:
- the test instance; never
null
- Throws:
PreconditionViolationException
- if the test instance is not present in thisExtensionContext
- See Also:
-
getTestInstances
Get the test instances associated with the current test or container, if available.While top-level tests only have a single test instance, nested tests have one additional instance for each enclosing test class.
- Returns:
- an
Optional
containing the test instances; nevernull
but potentially empty - Since:
- 5.4
- See Also:
-
getRequiredTestInstances
Get the required test instances associated with the current test or container.Use this method as an alternative to
getTestInstances()
for use cases in which the test instances are required to be present.- Returns:
- the test instances; never
null
- Throws:
PreconditionViolationException
- if the test instances are not present in thisExtensionContext
- Since:
- 5.4
-
getTestMethod
Get theMethod
associated with the current test, if available.- Returns:
- an
Optional
containing the method; nevernull
but potentially empty - See Also:
-
getRequiredTestMethod
Get the requiredMethod
associated with the current test or container.Use this method as an alternative to
getTestMethod()
for use cases in which the test method is required to be present.- Returns:
- the test method; never
null
- Throws:
PreconditionViolationException
- if the test method is not present in thisExtensionContext
-
getExecutionException
Get the exception that was thrown during execution of the test or container associated with thisExtensionContext
, if available.This method is typically used for logging and tracing purposes. If you wish to actually handle an exception thrown during test execution, implement the
TestExecutionExceptionHandler
API.Unlike the exception passed to a
TestExecutionExceptionHandler
, an execution exception returned by this method can be any exception thrown during the invocation of a@Test
method, its surrounding@BeforeEach
and@AfterEach
methods, or a test-levelExtension
. Similarly, if thisExtensionContext
represents a test class, the execution exception returned by this method can be any exception thrown in a@BeforeAll
orAfterAll
method or a class-levelExtension
.Note, however, that this method will never return an exception swallowed by a
TestExecutionExceptionHandler
. Furthermore, if multiple exceptions have been thrown during test execution, the exception returned by this method will be the first such exception with all additional exceptions suppressed in the first one.- Returns:
- an
Optional
containing the exception thrown; nevernull
but potentially empty if test execution has not (yet) resulted in an exception
-
getConfigurationParameter
Get the configuration parameter stored under the specifiedkey
.If no such key is present in the
ConfigurationParameters
for the JUnit Platform, an attempt will be made to look up the value as a JVM system property. If no such system property exists, an attempt will be made to look up the value in the JUnit Platform properties file.- Parameters:
key
- the key to look up; nevernull
or blank- Returns:
- an
Optional
containing the value; nevernull
but potentially empty - Since:
- 5.1
- See Also:
-
getConfigurationParameter
@API(status=EXPERIMENTAL, since="5.7") <T> Optional<T> getConfigurationParameter(String key, Function<String, T> transformer) Get and transform the configuration parameter stored under the specifiedkey
using the specifiedtransformer
.If no such key is present in the
ConfigurationParameters
for the JUnit Platform, an attempt will be made to look up the value as a JVM system property. If no such system property exists, an attempt will be made to look up the value in the JUnit Platform properties file.In case the transformer throws an exception, it will be wrapped in a
JUnitException
with a helpful message.- Parameters:
key
- the key to look up; nevernull
or blanktransformer
- the transformer to apply in case a value is found; nevernull
- Returns:
- an
Optional
containing the value; nevernull
but potentially empty - Since:
- 5.7
- See Also:
-
publishReportEntry
Publish a map of key-value pairs to be consumed by anorg.junit.platform.engine.EngineExecutionListener
in order to supply additional information to the reporting infrastructure.- Parameters:
map
- the key-value pairs to be published; nevernull
; keys and values within entries in the map also must not benull
or blank- See Also:
-
publishReportEntry
Publish the specified key-value pair to be consumed by anorg.junit.platform.engine.EngineExecutionListener
in order to supply additional information to the reporting infrastructure.- Parameters:
key
- the key of the published pair; nevernull
or blankvalue
- the value of the published pair; nevernull
or blank- See Also:
-
publishReportEntry
Publish the specified value to be consumed by anorg.junit.platform.engine.EngineExecutionListener
in order to supply additional information to the reporting infrastructure.This method delegates to
publishReportEntry(String, String)
, supplying"value"
as the key and the suppliedvalue
argument as the value.- Parameters:
value
- the value to be published; nevernull
or blank- Since:
- 5.3
- See Also:
-
getStore
Get theExtensionContext.Store
for the suppliedExtensionContext.Namespace
.Use
getStore(Namespace.GLOBAL)
to get the default, globalExtensionContext.Namespace
.A 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
ExtensionContext.Store.CloseableResource
are notified by invoking theirclose()
methods.- Parameters:
namespace
- theNamespace
to get the store for; nevernull
- Returns:
- the store in which to put and get objects for other invocations
working in the same namespace; never
null
- See Also:
-
getExecutionMode
Get theExecutionMode
associated with the current test or container.- Returns:
- the
ExecutionMode
of the test; nevernull
- Since:
- 5.8.1
- See Also:
-
getExecutableInvoker
Get anExecutableInvoker
to invoke methods and constructors with support for dynamic resolution of parameters.- Since:
- 5.9
-