org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of junit-jupiter-api Show documentation
Module "junit-jupiter-api" of JUnit 5.
The newest version!
/*
 * Copyright 2015-2024 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.STABLE;

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.
 *
 * @since 5.5
 * @see TestExecutionExceptionHandler
 */
@API(status = STABLE, since = "5.10")
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;
	}

}