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.

See getTestInstantiationExtensionContextScope(ExtensionContext) for further details.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public 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 and Description
public default TestInstantiationAwareExtension.ExtensionContextScope	getTestInstantiationExtensionContextScope(ExtensionContext the root extension context to allow inspection of configuration parameters; never `null` rootContext) Determine whether this extension should receive a test-method scoped `ExtensionContext` during the instantiation of test classes or processing of test instances.

Method Detail

getTestInstantiationExtensionContextScope back to summary

getTestInstantiationExtensionContextScope	back to summary
public 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. 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`. Parameters rootContext:ExtensionContext the root extension context to allow inspection of configuration parameters; never `null` Annotations @API status:MAINTAINED since:5.13.3 Since 5.12

public 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.

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.

Parameters

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

Annotations

@API
status:MAINTAINED
since:5.13.3

Since

5.12

org.junit.jupiter.api.extension back to summary

public final Enum TestInstantiationAwareExtension.ExtensionContextScope

Class Inheritance

extends Enum<TestInstantiationAwareExtension.ExtensionContextScope>

java.lang.Object
java.lang.Enum
org.junit.jupiter.api.extension.TestInstantiationAwareExtension.ExtensionContextScope

Annotations

@API
status:MAINTAINED
since:5.13.3

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.

Since: 5.12
See Also: TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)

Field Summary

Modifier and Type	Field and Description
public static final TestInstantiationAwareExtension.ExtensionContextScope	DEFAULT Deprecated since 5.12. This behavior will be removed from future versions of JUnit, and `TEST_METHOD` will become the default. The extension should receive an `ExtensionContext` for the the default scope.
public static final String	DEFAULT_SCOPE_PROPERTY_NAME Property name used to set the default extension context scope: Supported Values Supported values include names of enum constants defined in this class, ignoring case.
public static final TestInstantiationAwareExtension.ExtensionContextScope	TEST_METHOD The extension should receive an `ExtensionContext` scoped to the test method.

Constructor Summary

Access	Constructor and Description
private	ExtensionContextScope()

Method Summary

Modifier and Type	Method and Description
public static TestInstantiationAwareExtension.ExtensionContextScope	valueOf(String name)
public static TestInstantiationAwareExtension.ExtensionContextScope[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

DEFAULT back to summary

DEFAULT	back to summary
public static final TestInstantiationAwareExtension.ExtensionContextScope DEFAULT Deprecated since 5.12. This behavior will be removed from future versions of JUnit, and `TEST_METHOD` will become the default. The extension should receive an `ExtensionContext` for the the default scope. The default scope is determined by the configuration parameter `DEFAULT_SCOPE_PROPERTY_NAME`. If not specified, extensions will receive an `ExtensionContext` scoped to the test class. Annotations @Deprecated since:5.12 @API status:DEPRECATED since:5.12 See Also `DEFAULT_SCOPE_PROPERTY_NAME`

public static final TestInstantiationAwareExtension.ExtensionContextScope DEFAULT

Deprecated

since 5.12.

This behavior will be removed from future versions of JUnit, and TEST_METHOD will become the default.

The extension should receive an ExtensionContext for the the default scope.

The default scope is determined by the configuration parameter DEFAULT_SCOPE_PROPERTY_NAME. If not specified, extensions will receive an ExtensionContext scoped to the test class.

Annotations

@Deprecated
since:5.12
@API
status:DEPRECATED
since:5.12

See Also: DEFAULT_SCOPE_PROPERTY_NAME

DEFAULT_SCOPE_PROPERTY_NAME back to summary

DEFAULT_SCOPE_PROPERTY_NAME	back to summary
public static final String DEFAULT_SCOPE_PROPERTY_NAME Property name used to set the default extension context scope: Supported Values Supported values include names of enum constants defined in this class, ignoring case. See Also `DEFAULT`

public static final String DEFAULT_SCOPE_PROPERTY_NAME

Property name used to set the default extension context scope:

Supported Values

Supported values include names of enum constants defined in this class, ignoring case.

See Also: DEFAULT

TEST_METHOD back to summary

TEST_METHOD	back to summary
public static final TestInstantiationAwareExtension.ExtensionContextScope TEST_METHOD The extension should receive an `ExtensionContext` scoped to the test method. Note, however, that a test-class scoped context will always be supplied if the `PER_CLASS` test instance lifecycle is used.

public static final TestInstantiationAwareExtension.ExtensionContextScope TEST_METHOD

The extension should receive an ExtensionContext scoped to the test method.

Note, however, that a test-class scoped context will always be supplied if the PER_CLASS test instance lifecycle is used.

Constructor Detail

ExtensionContextScope	back to summary
private ExtensionContextScope()

Method Detail

valueOf	back to summary
public static TestInstantiationAwareExtension.ExtensionContextScope valueOf(String name)

values	back to summary
public static TestInstantiationAwareExtension.ExtensionContextScope[] values()

public Interface TestInstantiationAwareExtension

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum TestInstantiationAwareExtension.ExtensionContextScope

Field Summary

Constructor Summary

Method Summary

Field Detail

Supported Values

Constructor Detail

Method Detail