org.junit.jupiter.api.extension.TestWatcher 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 java.util.Optional;

import org.apiguardian.api.API;

/**
 * {@code TestWatcher} defines the API for {@link Extension Extensions} that
 * wish to process test results.
 *
 * The methods in this API are called after a test has been skipped or
 * executed. Any {@link ExtensionContext.Store.CloseableResource CloseableResource}
 * objects stored in the {@link ExtensionContext.Store Store} of the supplied
 * {@link ExtensionContext} will have already been closed before
 * methods in this API are invoked.
 *
 * 
Please note that this API is currently only used to report the results of
 * {@link org.junit.jupiter.api.Test @Test} methods and
 * {@link org.junit.jupiter.api.TestTemplate @TestTemplate} methods (e.g.,
 * {@code @RepeatedTest} and {@code @ParameterizedTest}). Moreover, if there is a
 * failure at the class level — for example, an exception thrown by a
 * {@code @BeforeAll} method — no test results will be reported. Similarly,
 * if the test class is disabled via an {@link ExecutionCondition} — for
 * example, {@code @Disabled} — no test results will be reported.
 *
 * 
Extensions implementing this interface can be registered at the class level,
 * instance level, or method level. When registered at the class level, a
 * {@code TestWatcher} will be invoked for any contained test method including
 * those in {@link org.junit.jupiter.api.Nested @Nested} classes. When registered
 * at the method level, a {@code TestWatcher} will only be invoked for the test
 * method for which it was registered.
 *
 * 
WARNING: If a {@code TestWatcher} is registered via a
 * non-static (instance) field — for example, using
 * {@link RegisterExtension @RegisterExtension} — and the test class is
 * configured with
 * {@link org.junit.jupiter.api.TestInstance @TestInstance(Lifecycle.PER_METHOD)}
 * semantics (which is the default lifecycle mode), the {@code TestWatcher} will
 * not be invoked with events for {@code @TestTemplate} methods
 * (such as {@code @RepeatedTest} and {@code @ParameterizedTest}). To ensure that
 * a {@code TestWatcher} is invoked for all test methods in a given class, it is
 * therefore recommended that the {@code TestWatcher} be registered at the class
 * level with {@link ExtendWith @ExtendWith} or via a {@code static} field with
 * {@code @RegisterExtension} or {@code @ExtendWith}.
 *
 * 
Exception Handling
 *
 * In contrast to other {@link Extension} APIs, a {@code TestWatcher} is not
 * permitted to adversely influence the execution of tests. Consequently, any
 * exception thrown by a method in the {@code TestWatcher} API will be logged at
 * {@code WARNING} level and will not be allowed to propagate or fail test
 * execution.
 *
 * @since 5.4
 */
@API(status = STABLE, since = "5.7")
public interface TestWatcher extends Extension {

	/**
	 * Invoked after a disabled test has been skipped.
	 *
	 * 
The default implementation does nothing. Concrete implementations can
	 * override this method as appropriate.
	 *
	 * @param context the current extension context; never {@code null}
	 * @param reason the reason the test is disabled; never {@code null} but
	 * potentially empty
	 */
	default void testDisabled(ExtensionContext context, Optional reason) {
		/* no-op */
	}

	/**
	 * Invoked after a test has completed successfully.
	 *
	 * 
The default implementation does nothing. Concrete implementations can
	 * override this method as appropriate.
	 *
	 * @param context the current extension context; never {@code null}
	 */
	default void testSuccessful(ExtensionContext context) {
		/* no-op */
	}

	/**
	 * Invoked after a test has been aborted.
	 *
	 * 
The default implementation does nothing. Concrete implementations can
	 * override this method as appropriate.
	 *
	 * @param context the current extension context; never {@code null}
	 * @param cause the throwable responsible for the test being aborted; may be {@code null}
	 */
	default void testAborted(ExtensionContext context, Throwable cause) {
		/* no-op */
	}

	/**
	 * Invoked after a test has failed.
	 *
	 * The default implementation does nothing. Concrete implementations can
	 * override this method as appropriate.
	 *
	 * @param context the current extension context; never {@code null}
	 * @param cause the throwable that caused test failure; may be {@code null}
	 */
	default void testFailed(ExtensionContext context, Throwable cause) {
		/* no-op */
	}

}