Package org.junit.jupiter.api.extension

Interface InvocationInterceptor

All Superinterfaces:

Extension, TestInstantiationAwareExtension

@API(status=STABLE,
     since="5.10")
public interface InvocationInterceptor
extends TestInstantiationAwareExtension

InvocationInterceptor defines the API for Extensions that wish to intercept calls to test code.

Invocation Contract

Each method in this class must call InvocationInterceptor.Invocation.proceed() or InvocationInterceptor.Invocation.skip() exactly once on the supplied invocation. Otherwise, the enclosing test or container will be reported as failed.

The default implementation calls proceed() on the supplied invocation.

Constructor Requirements

Consult the documentation in Extension for details on constructor requirements.

ExtensionContext Scope

As of JUnit Jupiter 5.12, this API participates in the TestInstantiationAwareExtension contract. Implementations of this API may therefore choose to override getTestInstantiationExtensionContextScope(ExtensionContext). See interceptTestClassConstructor(Invocation, ReflectiveInvocationContext, ExtensionContext) for details.

Since:

5.5

See Also:

InvocationInterceptor.Invocation, ReflectiveInvocationContext, ExtensionContext

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	InvocationInterceptor.Invocation<T>	An invocation that returns a result and may throw a Throwable.

Nested classes/interfaces inherited from interface org.junit.jupiter.api.extension.TestInstantiationAwareExtension

TestInstantiationAwareExtension.ExtensionContextScope

Method Summary

Modifier and Type	Method	Description
default void	interceptAfterAllMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of an @AfterAll method.
default void	interceptAfterEachMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of an @AfterEach method.
default void	interceptBeforeAllMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a @BeforeAll method.
default void	interceptBeforeEachMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a @BeforeEach method.
default void	interceptDynamicTest(InvocationInterceptor.Invocation<java.lang.Void> invocation, DynamicTestInvocationContext invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a DynamicTest.
default void	interceptDynamicTest(InvocationInterceptor.Invocation<java.lang.Void> invocation, ExtensionContext extensionContext)	Deprecated. use interceptDynamicTest(Invocation, DynamicTestInvocationContext, ExtensionContext) instead
default <T> T	interceptTestClassConstructor(InvocationInterceptor.Invocation<T> invocation, ReflectiveInvocationContext<java.lang.reflect.Constructor<T>> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a test class constructor.
default <T> T	interceptTestFactoryMethod(InvocationInterceptor.Invocation<T> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a @TestFactory method, such as a @RepeatedTest or @ParameterizedTest method.
default void	interceptTestMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a @Test method.
default void	interceptTestTemplateMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation, ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext, ExtensionContext extensionContext)	Intercept the invocation of a @TestTemplate method.

Methods inherited from interface org.junit.jupiter.api.extension.TestInstantiationAwareExtension

getTestInstantiationExtensionContextScope

Method Detail

interceptTestClassConstructor

default <T> T interceptTestClassConstructor(InvocationInterceptor.Invocation<T> invocation,
                                            ReflectiveInvocationContext<java.lang.reflect.Constructor<T>> invocationContext,
                                            ExtensionContext extensionContext)
                                     throws java.lang.Throwable

Intercept the invocation of a test class constructor.

Note that the test class may not have been initialized (static initialization) when this method is invoked.

By default, the supplied ExtensionContext represents the test class that's about to be constructed. Extensions may override TestInstantiationAwareExtension.getTestInstantiationExtensionContextScope(org.junit.jupiter.api.extension.ExtensionContext) to return TEST_METHOD in order to change the scope of the ExtensionContext to the test method, unless the PER_CLASS lifecycle is used. Changing the scope makes test-specific data available to the implementation of this method and allows keeping state on the test level by using the provided Store instance.

Type Parameters:

T - the result type

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Returns:

the result of the invocation; never null

Throws:

java.lang.Throwable - in case of failure

interceptBeforeAllMethod

default void interceptBeforeAllMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                      ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                      ExtensionContext extensionContext)
                               throws java.lang.Throwable

Intercept the invocation of a @BeforeAll method.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptBeforeEachMethod

default void interceptBeforeEachMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                       ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                       ExtensionContext extensionContext)
                                throws java.lang.Throwable

Intercept the invocation of a @BeforeEach method.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptTestMethod

default void interceptTestMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                 ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                 ExtensionContext extensionContext)
                          throws java.lang.Throwable

Intercept the invocation of a @Test method.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptTestFactoryMethod

default <T> T interceptTestFactoryMethod(InvocationInterceptor.Invocation<T> invocation,
                                         ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                         ExtensionContext extensionContext)
                                  throws java.lang.Throwable

Intercept the invocation of a @TestFactory method, such as a @RepeatedTest or @ParameterizedTest method.

Type Parameters:

T - the result type

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Returns:

the result of the invocation; potentially null

Throws:

java.lang.Throwable - in case of failures

interceptTestTemplateMethod

default void interceptTestTemplateMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                         ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                         ExtensionContext extensionContext)
                                  throws java.lang.Throwable

Intercept the invocation of a @TestTemplate method.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptDynamicTest

@Deprecated
@API(status=DEPRECATED,
     since="5.8")
default void interceptDynamicTest(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                  ExtensionContext extensionContext)
                           throws java.lang.Throwable

Deprecated.

use interceptDynamicTest(Invocation, DynamicTestInvocationContext, ExtensionContext) instead

Intercept the invocation of a DynamicTest.

Parameters:

invocation - the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptDynamicTest

@API(status=STABLE,
     since="5.11")
default void interceptDynamicTest(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                  DynamicTestInvocationContext invocationContext,
                                  ExtensionContext extensionContext)
                           throws java.lang.Throwable

Intercept the invocation of a DynamicTest.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptAfterEachMethod

default void interceptAfterEachMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                      ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                      ExtensionContext extensionContext)
                               throws java.lang.Throwable

Intercept the invocation of an @AfterEach method.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures

interceptAfterAllMethod

default void interceptAfterAllMethod(InvocationInterceptor.Invocation<java.lang.Void> invocation,
                                     ReflectiveInvocationContext<java.lang.reflect.Method> invocationContext,
                                     ExtensionContext extensionContext)
                              throws java.lang.Throwable

Intercept the invocation of an @AfterAll method.

Parameters:

invocation - the invocation that is being intercepted; never null

invocationContext - the context of the invocation that is being intercepted; never null

extensionContext - the current extension context; never null

Throws:

java.lang.Throwable - in case of failures