Interface LifecycleMethodExecutionExceptionHandler

All Superinterfaces:
Extension

@API(status=STABLE, since="5.10") public interface LifecycleMethodExecutionExceptionHandler extends Extension
LifecycleMethodExecutionExceptionHandler defines the API for Extensions that wish to handle exceptions thrown during the execution of @BeforeAll, @BeforeEach, @AfterEach, and @AfterAll lifecycle methods.

Common use cases include swallowing an exception if it's anticipated, logging errors, or rolling back a transaction in certain error scenarios.

Implementations of this extension API must be registered at the class level if exceptions thrown from @BeforeAll or @AfterAll methods are to be handled. When registered at the test level, only exceptions thrown from @BeforeEach or @AfterEach methods will be handled.

Constructor Requirements

Consult the documentation in Extension for details on constructor requirements.

Implementation Guidelines

An implementation of an exception handler method defined in this API must perform one of the following.

  1. Rethrow the supplied Throwable as is, which is the default implementation.
  2. Swallow the supplied Throwable, thereby preventing propagation.
  3. Throw a new exception, potentially wrapping the supplied Throwable.

If the supplied Throwable is swallowed by a handler method, subsequent handler methods for the same lifecycle will not be invoked; otherwise, the corresponding handler method of the next registered LifecycleMethodExecutionExceptionHandler (if there is one) will be invoked with any Throwable thrown by the previous handler.

Since:
5.5
See Also:
  • Method Details

    • handleBeforeAllMethodExecutionException

      default void handleBeforeAllMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable
      Handle the supplied Throwable that was thrown during execution of a @BeforeAll lifecycle method.

      Please refer to the class-level Javadoc for Implementation Guidelines.

      Parameters:
      context - the current extension context; never null
      throwable - the Throwable to handle; never null
      Throws:
      Throwable
    • handleBeforeEachMethodExecutionException

      default void handleBeforeEachMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable
      Handle the supplied Throwable that was thrown during execution of a @BeforeEach lifecycle method.

      Please refer to the class-level Javadoc for Implementation Guidelines.

      Parameters:
      context - the current extension context; never null
      throwable - the Throwable to handle; never null
      Throws:
      Throwable
    • handleAfterEachMethodExecutionException

      default void handleAfterEachMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable
      Handle the supplied Throwable that was thrown during execution of a @AfterEach lifecycle method.

      Please refer to the class-level Javadoc for Implementation Guidelines.

      Parameters:
      context - the current extension context; never null
      throwable - the Throwable to handle; never null
      Throws:
      Throwable
    • handleAfterAllMethodExecutionException

      default void handleAfterAllMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable
      Handle the supplied Throwable that was thrown during execution of a @AfterAll lifecycle method.

      Please refer to the class-level Javadoc for Implementation Guidelines.

      Parameters:
      context - the current extension context; never null
      throwable - the Throwable to handle; never null
      Throws:
      Throwable