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

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.

There is a newer version: 5.11.0-M1

/*
 * Copyright 2015-2017 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 v1.0 which
 * accompanies this distribution and is available at
 *
 * http://www.eclipse.org/legal/epl-v10.html
 */

package org.junit.jupiter.api.extension;

import static org.junit.platform.commons.meta.API.Usage.Experimental;

import org.junit.platform.commons.meta.API;

/**
 * {@code TestExecutionExceptionHandler} defines the API for {@link Extension
 * Extensions} that wish to handle exceptions thrown during test execution.
 *
 * In this context, test execution refers to the physical
 * invocation of a {@code @Test} method and not to any test-level extensions
 * or callbacks.
 *
 * 
Common use cases include swallowing an exception if it's anticipated
 * or rolling back a transaction in certain error scenarios.
 *
 * 
Implementations must provide a no-args constructor.
 *
 * @since 5.0
 */
@FunctionalInterface
@API(Experimental)
public interface TestExecutionExceptionHandler extends Extension {

	/**
	 * Handle the supplied {@link Throwable throwable}.
	 *
	 * 
Implementors must perform one of the following.
	 * 

	 * Swallow the supplied {@code throwable}, thereby preventing propagation.
	 * Rethrow the supplied {@code throwable} as is.
	 * Throw a new exception, potentially wrapping the supplied {@code throwable}.
	 * 
	 *
	 * If the supplied {@code throwable} is swallowed, subsequent
	 * {@code TestExecutionExceptionHandlers} will not be invoked; otherwise,
	 * the next registered {@code TestExecutionExceptionHandler} (if there is
	 * one) will be invoked with any {@link Throwable} thrown by this handler.
	 *
	 * Note that the {@link ExtensionContext#getExecutionException() execution
	 * exception} in the supplied {@code ExtensionContext} will not
	 * contain the {@code Throwable} thrown during invocation of the corresponding
	 * {@code @Test} method.
	 *
	 * @param context the current extension context; never {@code null}
	 * @param throwable the {@code Throwable} to handle; never {@code null}
	 */
	void handleTestExecutionException(ExtensionContext context, Throwable throwable) throws Throwable;

}