Module org.junit.jupiter.api

Package org.junit.jupiter.api.extension

Interface ExtensionContext

All Known Subinterfaces:

ExtensionContextInternal

@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 of ExtensionContext to perform their work.

This interface is not intended to be implemented by clients.

Since:

5.0

See Also:

• ExtensionContext.Store
• ExtensionContext.Namespace

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ExtensionContext.Namespace	A Namespace is used to provide a scope for data saved by extensions within a ExtensionContext.Store.
static interface	ExtensionContext.Store	Store provides methods for extensions to save and retrieve data.
static enum	ExtensionContext.StoreScope	StoreScope is an enumeration of the different scopes for ExtensionContext.Store instances.

Method Summary

Modifier and Type	Method	Description
Optional<String>	getConfigurationParameter(String key)	Get the configuration parameter stored under the specified key.
<T> Optional<T>	getConfigurationParameter(String key, Function<String,T> transformer)	Get and transform the configuration parameter stored under the specified key using the specified transformer.
String	getDisplayName()	Get the display name for the current test or container.
Optional<AnnotatedElement>	getElement()	Get the AnnotatedElement corresponding to the current extension context, if available.
List<Class<?>>	getEnclosingTestClasses()	Get the enclosing test classes of the current test or container.
ExecutableInvoker	getExecutableInvoker()	Get an ExecutableInvoker to invoke methods and constructors with support for dynamic resolution of parameters.
Optional<Throwable>	getExecutionException()	Get the exception that was thrown during execution of the test or container associated with this ExtensionContext, if available.
ExecutionMode	getExecutionMode()	Get the ExecutionMode associated with the current test or container.
Optional<ExtensionContext>	getParent()	Get the parent extension context, if available.
default Class<?>	getRequiredTestClass()	Get the required Class 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 required Method associated with the current test or container.
ExtensionContext	getRoot()	Get the root ExtensionContext.
ExtensionContext.Store	getStore(ExtensionContext.Namespace namespace)	Get the ExtensionContext.Store for the supplied ExtensionContext.Namespace.
ExtensionContext.Store	getStore(ExtensionContext.StoreScope scope, ExtensionContext.Namespace namespace)	Returns the store for supplied scope and namespace.
Set<String>	getTags()	Get the set of all tags for the current test or container.
Optional<Class<?>>	getTestClass()	Get the Class 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 the TestInstance.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 the Method associated with the current test, if available.
String	getUniqueId()	Get the unique ID of the current test or container.
void	publishDirectory(String name, ThrowingConsumer<Path> action)	Publish a directory with the supplied name written by the supplied action and attach it to the current test or container.
void	publishFile(String name, MediaType mediaType, ThrowingConsumer<Path> action)	Publish a file with the supplied name written by the supplied action and attach it to the current test or container.
default void	publishReportEntry(String value)	Publish the specified value to be consumed by an org.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 an org.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 an org.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; never null but potentially empty

See Also:

• getRoot()

getRoot

ExtensionContext getRoot()

Get the root ExtensionContext.

Returns:

the root extension context; never null but potentially this ExtensionContext

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 the AnnotatedElement 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 or Method 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 the AnnotatedElement; never null but potentially empty

See Also:

• getTestClass()
• getTestMethod()

getTestClass

Optional<Class<?>> getTestClass()

Get the Class associated with the current test or container, if available.

Returns:

an Optional containing the class; never null but potentially empty

See Also:

• getRequiredTestClass()

getEnclosingTestClasses

@API(status=EXPERIMENTAL,
     since="5.12.1")
List<Class<?>> getEnclosingTestClasses()

Get the enclosing test classes of the current test or container.

This method is useful to look up annotations on nested test classes and their enclosing runtime types:

 AnnotationSupport.findAnnotation(
     extensionContext.getRequiredTestClass(),
     MyAnnotation.class,
     extensionContext.getEnclosingTestClasses()
 );
 

Returns:

an empty list if there is no class associated with the current test or container or when it is not nested; otherwise, a list containing the enclosing test classes in order from outermost to innermost; never null

Since:

5.12.1

See Also:

• AnnotationSupport.findAnnotation(Class, Class, List)

getRequiredTestClass

default Class<?> getRequiredTestClass()

Get the required Class 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 this ExtensionContext

getTestInstanceLifecycle

@API(status=STABLE,
     since="5.1")
Optional<TestInstance.Lifecycle> getTestInstanceLifecycle()

Get the TestInstance.Lifecycle of the test instance associated with the current test or container, if available.

Returns:

an Optional containing the test instance Lifecycle; never null 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; never null 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 this ExtensionContext

See Also:

• getRequiredTestInstances()

getTestInstances

@API(status=STABLE,
     since="5.7")
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; never null but potentially empty

Since:

5.4

See Also:

• getRequiredTestInstances()

getRequiredTestInstances

@API(status=STABLE,
     since="5.7")
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 this ExtensionContext

Since:

5.4

getTestMethod

Optional<Method> getTestMethod()

Get the Method associated with the current test, if available.

Returns:

an Optional containing the method; never null but potentially empty

See Also:

• getRequiredTestMethod()

getRequiredTestMethod

default Method getRequiredTestMethod()

Get the required Method 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 this ExtensionContext

getExecutionException

Optional<Throwable> getExecutionException()

Get the exception that was thrown during execution of the test or container associated with this ExtensionContext, 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-level Extension. Similarly, if this ExtensionContext represents a test class, the execution exception returned by this method can be any exception thrown in a @BeforeAll or AfterAll method or a class-level Extension.

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; never null 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 specified key.

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; never null or blank

Returns:

an Optional containing the value; never null but potentially empty

Since:

5.1

See Also:

• System.getProperty(String)
• ConfigurationParameters

getConfigurationParameter

@API(status=STABLE,
     since="5.10")
<T> Optional<T> getConfigurationParameter(String key,
 Function<String,T> transformer)

Get and transform the configuration parameter stored under the specified key using the specified transformer.

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; never null or blank

transformer - the transformer to apply in case a value is found; never null

Returns:

an Optional containing the value; never null but potentially empty

Since:

5.7

See Also:

• System.getProperty(String)
• ConfigurationParameters

publishReportEntry

void publishReportEntry(Map<String,String> map)

Publish a map of key-value pairs to be consumed by an org.junit.platform.engine.EngineExecutionListener in order to supply additional information to the reporting infrastructure.

Parameters:

map - the key-value pairs to be published; never null; keys and values within entries in the map also must not be null 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 an org.junit.platform.engine.EngineExecutionListener in order to supply additional information to the reporting infrastructure.

Parameters:

key - the key of the published pair; never null or blank

value - the value of the published pair; never null 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 an org.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 supplied value argument as the value.

Parameters:

value - the value to be published; never null 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)

publishFile

@API(status=EXPERIMENTAL,
     since="5.12")
void publishFile(String name,
 MediaType mediaType,
 ThrowingConsumer<Path> action)

Publish a file with the supplied name written by the supplied action and attach it to the current test or container.

The file will be resolved in the report output directory prior to invoking the supplied action.

Parameters:

name - the name of the file to be attached; never null or blank and must not contain any path separators

mediaType - the media type of the file; never null; use MediaType.APPLICATION_OCTET_STREAM if unknown

action - the action to be executed to write the file; never null

Since:

5.12

See Also:

• EngineExecutionListener.fileEntryPublished(org.junit.platform.engine.TestDescriptor, org.junit.platform.engine.reporting.FileEntry)

publishDirectory

@API(status=EXPERIMENTAL,
     since="5.12")
void publishDirectory(String name,
 ThrowingConsumer<Path> action)

Publish a directory with the supplied name written by the supplied action and attach it to the current test or container.

The directory will be resolved and created in the report output directory prior to invoking the supplied action.

Parameters:

name - the name of the directory to be attached; never null or blank and must not contain any path separators

action - the action to be executed to write the file; never null

Since:

5.12

See Also:

• EngineExecutionListener.fileEntryPublished(org.junit.platform.engine.TestDescriptor, org.junit.platform.engine.reporting.FileEntry)

getStore

ExtensionContext.Store getStore(ExtensionContext.Namespace namespace)

Get the ExtensionContext.Store for the supplied ExtensionContext.Namespace.

Use getStore(Namespace.GLOBAL) to get the default, global ExtensionContext.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 their close() methods.

Parameters:

namespace - the Namespace to get the store for; never null

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
• getStore(StoreScope, Namespace)

getStore

@API(status=EXPERIMENTAL,
     since="5.13")
ExtensionContext.Store getStore(ExtensionContext.StoreScope scope,
 ExtensionContext.Namespace namespace)

Returns the store for supplied scope and namespace.

If scope is EXTENSION_CONTEXT, the store behaves exactly like the one returned by getStore(Namespace). If the scope is LAUNCHER_SESSION or EXECUTION_REQUEST, all stored values that are instances of AutoCloseable are notified by invoking their close() methods when the scope is closed.

Since:

5.13

See Also:

• ExtensionContext.StoreScope
• getStore(Namespace)

getExecutionMode

@API(status=STABLE,
     since="5.8.1")
ExecutionMode getExecutionMode()

Get the ExecutionMode associated with the current test or container.

Returns:

the ExecutionMode of the test; never null

Since:

5.8.1

See Also:

• @ExecutionMode

getExecutableInvoker

@API(status=STABLE,
     since="5.11")
ExecutableInvoker getExecutableInvoker()

Get an ExecutableInvoker to invoke methods and constructors with support for dynamic resolution of parameters.

Since:

5.9