org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler Maven / Gradle / Ivy
/*
* Copyright 2015-2020 the original author or authors.
*
* All rights reserved. This program and the accompanying materials are
* made available under the terms of the Eclipse Public License v2.0 which
* accompanies this distribution and is available at
*
* https://www.eclipse.org/legal/epl-v20.html
*/
package org.junit.jupiter.api.extension;
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
import org.apiguardian.api.API;
/**
* {@code LifecycleMethodExecutionExceptionHandler} defines the API for
* {@link Extension Extensions} that wish to handle exceptions thrown during
* the execution of {@code @BeforeAll}, {@code @BeforeEach}, {@code @AfterEach},
* and {@code @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 {@code @BeforeAll} or {@code @AfterAll} methods are
* to be handled. When registered at the test level, only exceptions thrown from
* {@code @BeforeEach} or {@code @AfterEach} methods will be handled.
*
*
Constructor Requirements
*
* Consult the documentation in {@link 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.
*
*
* - Rethrow the supplied {@code Throwable} as is, which is the default implementation.
* - Swallow the supplied {@code Throwable}, thereby preventing propagation.
* - Throw a new exception, potentially wrapping the supplied {@code Throwable}.
*
*
* If the supplied {@code 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
* {@code LifecycleMethodExecutionExceptionHandler} (if there is one) will be
* invoked with any {@link Throwable} thrown by the previous handler.
*
* @see TestExecutionExceptionHandler
* @since 5.5
*/
@API(status = EXPERIMENTAL, since = "5.5")
public interface LifecycleMethodExecutionExceptionHandler extends Extension {
/**
* Handle the supplied {@link Throwable} that was thrown during execution of
* a {@code @BeforeAll} lifecycle method.
*
*
Please refer to the class-level Javadoc for
* Implementation Guidelines.
*
* @param context the current extension context; never {@code null}
* @param throwable the {@code Throwable} to handle; never {@code null}
*/
default void handleBeforeAllMethodExecutionException(ExtensionContext context, Throwable throwable)
throws Throwable {
throw throwable;
}
/**
* Handle the supplied {@link Throwable} that was thrown during execution of
* a {@code @BeforeEach} lifecycle method.
*
*
Please refer to the class-level Javadoc for
* Implementation Guidelines.
*
* @param context the current extension context; never {@code null}
* @param throwable the {@code Throwable} to handle; never {@code null}
*/
default void handleBeforeEachMethodExecutionException(ExtensionContext context, Throwable throwable)
throws Throwable {
throw throwable;
}
/**
* Handle the supplied {@link Throwable} that was thrown during execution of
* a {@code @AfterEach} lifecycle method.
*
*
Please refer to the class-level Javadoc for
* Implementation Guidelines.
*
* @param context the current extension context; never {@code null}
* @param throwable the {@code Throwable} to handle; never {@code null}
*/
default void handleAfterEachMethodExecutionException(ExtensionContext context, Throwable throwable)
throws Throwable {
throw throwable;
}
/**
* Handle the supplied {@link Throwable} that was thrown during execution of
* a {@code @AfterAll} lifecycle method.
*
*
Please refer to the class-level Javadoc for
* Implementation Guidelines.
*
* @param context the current extension context; never {@code null}
* @param throwable the {@code Throwable} to handle; never {@code null}
*/
default void handleAfterAllMethodExecutionException(ExtensionContext context, Throwable throwable)
throws Throwable {
throw throwable;
}
}