Interface ExtensionContext
-
@API(status=STABLE, since="5.0") public interface ExtensionContext
ExtensionContext
encapsulates the context in which the current test or container is being executed.Extensions
are provided an instance ofExtensionContext
to perform their work.- Since:
- 5.0
- See Also:
ExtensionContext.Store
,ExtensionContext.Namespace
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
ExtensionContext.Namespace
ANamespace
is used to provide a scope for data saved by extensions within aExtensionContext.Store
.static interface
ExtensionContext.Store
Store
provides methods for extensions to save and retrieve data.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description Optional<String>
getConfigurationParameter(String key)
Get the configuration parameter stored under the specifiedkey
.String
getDisplayName()
Get the display name for the current test or container.Optional<AnnotatedElement>
getElement()
Get theAnnotatedElement
corresponding to the current extension context, if available.Optional<Throwable>
getExecutionException()
Get the exception that was thrown during execution of the test or container associated with thisExtensionContext
, if available.Optional<ExtensionContext>
getParent()
Get the parent extension context, if available.default Class<?>
getRequiredTestClass()
Get the requiredClass
associated with the current test or container.default Object
getRequiredTestInstance()
Get the required test instance associated with the current test or container.default TestInstances
getRequiredTestInstances()
Get the required test instances associated with the current test or container.default Method
getRequiredTestMethod()
Get the requiredMethod
associated with the current test or container.ExtensionContext
getRoot()
Get the rootExtensionContext
.ExtensionContext.Store
getStore(ExtensionContext.Namespace namespace)
Get theExtensionContext.Store
for the suppliedExtensionContext.Namespace
.Set<String>
getTags()
Get the set of all tags for the current test or container.Optional<Class<?>>
getTestClass()
Get theClass
associated with the current test or container, if available.Optional<Object>
getTestInstance()
Get the test instance associated with the current test or container, if available.Optional<TestInstance.Lifecycle>
getTestInstanceLifecycle()
Get theTestInstance.Lifecycle
of the test instance associated with the current test or container, if available.Optional<TestInstances>
getTestInstances()
Get the test instances associated with the current test or container, if available.Optional<Method>
getTestMethod()
Get theMethod
associated with the current test, if available.String
getUniqueId()
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 Detail
-
getParent
Optional<ExtensionContext> getParent()
Get the parent extension context, if available.- Returns:
- an
Optional
containing the parent; nevernull
but potentially empty - See Also:
getRoot()
-
getRoot
ExtensionContext getRoot()
Get the rootExtensionContext
.- Returns:
- the root extension context; never
null
but potentially thisExtensionContext
- See Also:
getParent()
-
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
Set<String> 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()
,getTestMethod()
-
getTestClass
Optional<Class<?>> 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()
-
getRequiredTestClass
default Class<?> 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
@API(status=STABLE, since="5.1") Optional<TestInstance.Lifecycle> 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:
TestInstance
-
getTestInstance
Optional<Object> 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()
,getTestInstances()
-
getRequiredTestInstance
default Object 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:
getRequiredTestInstances()
-
getTestInstances
@API(status=EXPERIMENTAL, since="5.4") Optional<TestInstances> 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()
-
getRequiredTestInstances
@API(status=EXPERIMENTAL, since="5.4") default TestInstances 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
Optional<Method> getTestMethod()
Get theMethod
associated with the current test, if available.- Returns:
- an
Optional
containing the method; nevernull
but potentially empty - See Also:
getRequiredTestMethod()
-
getRequiredTestMethod
default Method 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
Optional<Throwable> 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
@API(status=STABLE, since="5.1") Optional<String> getConfigurationParameter(String key)
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:
System.getProperty(String)
,ConfigurationParameters
-
publishReportEntry
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.- 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(String, String)
,publishReportEntry(String)
,EngineExecutionListener.reportingEntryPublished(org.junit.platform.engine.TestDescriptor, org.junit.platform.engine.reporting.ReportEntry)
-
publishReportEntry
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.- Parameters:
key
- the key of the published pair; nevernull
or blankvalue
- the value of the published pair; nevernull
or blank- See Also:
publishReportEntry(Map)
,publishReportEntry(String)
,EngineExecutionListener.reportingEntryPublished(org.junit.platform.engine.TestDescriptor, org.junit.platform.engine.reporting.ReportEntry)
-
publishReportEntry
@API(status=STABLE, since="5.3") 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.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:
publishReportEntry(Map)
,publishReportEntry(String, String)
,EngineExecutionListener.reportingEntryPublished(org.junit.platform.engine.TestDescriptor, org.junit.platform.engine.reporting.ReportEntry)
-
getStore
ExtensionContext.Store getStore(ExtensionContext.Namespace namespace)
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:
ExtensionContext.Namespace.GLOBAL
-
-