Module org.junit.jupiter.api

Package org.junit.jupiter.api.extension

Interface TestInstantiationAwareExtension

All Superinterfaces:

Extension

All Known Subinterfaces:

InvocationInterceptor, ParameterResolver, TestInstanceFactory, TestInstancePostProcessor, TestInstancePreConstructCallback

All Known Implementing Classes:

TypeBasedParameterResolver

@API(status=MAINTAINED,
     since="5.13.3")
public interface TestInstantiationAwareExtension
extends Extension

TestInstantiationAwareExtension defines the API for Extensions that are aware of or influence the instantiation of test classes.

This interface is not intended to be implemented directly. Instead, extensions should implement one of the sub-interfaces listed below.

• InvocationInterceptor
• ParameterResolver
• TestInstancePreConstructCallback
• TestInstancePostProcessor
• TestInstanceFactory

See getTestInstantiationExtensionContextScope(ExtensionContext) for further details.

Since:

5.12

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	TestInstantiationAwareExtension.ExtensionContextScope	ExtensionContextScope is used to define the scope of the ExtensionContext supplied to an extension during the instantiation of test classes or processing of test instances.

Method Summary

Modifier and Type	Method	Description
default TestInstantiationAwareExtension.ExtensionContextScope	getTestInstantiationExtensionContextScope(ExtensionContext rootContext)	Determine whether this extension should receive a test-method scoped ExtensionContext during the instantiation of test classes or processing of test instances.

Method Details

getTestInstantiationExtensionContextScope

@API(status=MAINTAINED,
     since="5.13.3")
default TestInstantiationAwareExtension.ExtensionContextScope getTestInstantiationExtensionContextScope(ExtensionContext rootContext)

Determine whether this extension should receive a test-method scoped ExtensionContext during the instantiation of test classes or processing of test instances.

If an extension returns TEST_METHOD from this method, methods defined in the following extension APIs will be called with a test-method scoped ExtensionContext instead of a test-class scoped context. Note, however, that a test-class scoped context will always be supplied if the PER_CLASS test instance lifecycle is used.

• InvocationInterceptor: only the interceptTestClassConstructor(...) method
• ParameterResolver: only when resolving constructor parameters
• TestInstancePreConstructCallback
• TestInstancePostProcessor
• TestInstanceFactory

When a test-method scoped ExtensionContext is supplied, implementations of the above extension APIs will observe the following differences.

• getElement() may refer to the test method.
• getTestClass() may refer to a nested test class.
  • For TestInstancePostProcessor, use testInstance.getClass() to get the test class associated with the supplied instance.
  • For TestInstanceFactory and TestInstancePreConstructCallback, use TestInstanceFactoryContext.getTestClass() to get the class under construction.
  • For ParameterResolver, when resolving a parameter for a constructor, ensure that the Executable is a Constructor, and then use constructor.getDeclaringClass() to get the test class associated with the constructor.
• getTestMethod() is no longer empty, unless the PER_CLASS test instance lifecycle is used.
• If the extension adds a CloseableResource or AutoCloseable to the Store (unless the junit.jupiter.extensions.store.close.autocloseable.enabled configuration parameter is set to false), then the resource will be closed just after the instance is destroyed.
• Extensions can now access data previously stored by a TestTemplateInvocationContext, unless the PER_CLASS test instance lifecycle is used.

Note: The behavior which is enabled by returning TEST_METHOD from this method will become the default in future versions of JUnit. To ensure forward compatibility, extension authors are therefore advised to opt into this feature, even if they do not require the new functionality.

Parameters:

rootContext - the root extension context to allow inspection of configuration parameters; never null

Since:

5.12

Implementation Note:

There are no guarantees about how often this method will be called. Therefore, implementations should be idempotent and avoid side effects. If computation of the return value is costly, implementations may wish to cache the result in the Store of the supplied ExtensionContext.