org.junit.jupiter.api.Assumptions Maven / Gradle / Ivy
Show all versions of junit-jupiter-api Show documentation
/*
* 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;
import static org.apiguardian.api.API.Status.STABLE;
import java.util.function.BooleanSupplier;
import java.util.function.Supplier;
import org.apiguardian.api.API;
import org.junit.jupiter.api.function.Executable;
import org.junit.platform.commons.util.ExceptionUtils;
import org.junit.platform.commons.util.StringUtils;
import org.opentest4j.TestAbortedException;
/**
* {@code Assumptions} is a collection of utility methods that support
* conditional test execution based on assumptions.
*
* In direct contrast to failed {@linkplain Assertions assertions},
* failed assumptions do not result in a test failure; rather,
* a failed assumption results in a test being aborted.
*
*
Assumptions are typically used whenever it does not make sense to
* continue execution of a given test method — for example, if the
* test depends on something that does not exist in the current runtime
* environment.
*
*
Although it is technically possible to extend this class, extension is
* strongly discouraged. The JUnit Team highly recommends that the methods
* defined in this class be used via static imports.
*
* @since 5.0
* @see TestAbortedException
* @see Assertions
*/
@API(status = STABLE, since = "5.0")
public class Assumptions {
/**
* Protected constructor allowing subclassing but not direct instantiation.
*
* @since 5.3
*/
protected Assumptions() {
/* no-op */
}
// --- assumeTrue ----------------------------------------------------------
/**
* Validate the given assumption.
*
* @param assumption the assumption to validate
* @throws TestAbortedException if the assumption is not {@code true}
*/
public static void assumeTrue(boolean assumption) throws TestAbortedException {
assumeTrue(assumption, "assumption is not true");
}
/**
* Validate the given assumption.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @throws TestAbortedException if the assumption is not {@code true}
*/
public static void assumeTrue(BooleanSupplier assumptionSupplier) throws TestAbortedException {
assumeTrue(assumptionSupplier.getAsBoolean(), "assumption is not true");
}
/**
* Validate the given assumption.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @param message the message to be included in the {@code TestAbortedException}
* if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code true}
*/
public static void assumeTrue(BooleanSupplier assumptionSupplier, String message) throws TestAbortedException {
assumeTrue(assumptionSupplier.getAsBoolean(), message);
}
/**
* Validate the given assumption.
*
* @param assumption the assumption to validate
* @param messageSupplier the supplier of the message to be included in
* the {@code TestAbortedException} if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code true}
*/
public static void assumeTrue(boolean assumption, Supplier messageSupplier) throws TestAbortedException {
if (!assumption) {
throwAssumptionFailed(messageSupplier.get());
}
}
/**
* Validate the given assumption.
*
* @param assumption the assumption to validate
* @param message the message to be included in the {@code TestAbortedException}
* if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code true}
*/
public static void assumeTrue(boolean assumption, String message) throws TestAbortedException {
if (!assumption) {
throwAssumptionFailed(message);
}
}
/**
* Validate the given assumption.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @param messageSupplier the supplier of the message to be included in
* the {@code TestAbortedException} if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code true}
*/
public static void assumeTrue(BooleanSupplier assumptionSupplier, Supplier messageSupplier)
throws TestAbortedException {
assumeTrue(assumptionSupplier.getAsBoolean(), messageSupplier);
}
// --- assumeFalse ---------------------------------------------------------
/**
* Validate the given assumption.
*
* @param assumption the assumption to validate
* @throws TestAbortedException if the assumption is not {@code false}
*/
public static void assumeFalse(boolean assumption) throws TestAbortedException {
assumeFalse(assumption, "assumption is not false");
}
/**
* Validate the given assumption.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @throws TestAbortedException if the assumption is not {@code false}
*/
public static void assumeFalse(BooleanSupplier assumptionSupplier) throws TestAbortedException {
assumeFalse(assumptionSupplier.getAsBoolean(), "assumption is not false");
}
/**
* Validate the given assumption.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @param message the message to be included in the {@code TestAbortedException}
* if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code false}
*/
public static void assumeFalse(BooleanSupplier assumptionSupplier, String message) throws TestAbortedException {
assumeFalse(assumptionSupplier.getAsBoolean(), message);
}
/**
* Validate the given assumption.
*
* @param assumption the assumption to validate
* @param messageSupplier the supplier of the message to be included in
* the {@code TestAbortedException} if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code false}
*/
public static void assumeFalse(boolean assumption, Supplier messageSupplier) throws TestAbortedException {
if (assumption) {
throwAssumptionFailed(messageSupplier.get());
}
}
/**
* Validate the given assumption.
*
* @param assumption the assumption to validate
* @param message the message to be included in the {@code TestAbortedException}
* if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code false}
*/
public static void assumeFalse(boolean assumption, String message) throws TestAbortedException {
if (assumption) {
throwAssumptionFailed(message);
}
}
/**
* Validate the given assumption.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @param messageSupplier the supplier of the message to be included in
* the {@code TestAbortedException} if the assumption is invalid
* @throws TestAbortedException if the assumption is not {@code false}
*/
public static void assumeFalse(BooleanSupplier assumptionSupplier, Supplier messageSupplier)
throws TestAbortedException {
assumeFalse(assumptionSupplier.getAsBoolean(), messageSupplier);
}
// --- assumingThat --------------------------------------------------------
/**
* Execute the supplied {@link Executable}, but only if the supplied
* assumption is valid.
*
* Unlike the other assumption methods, this method will not abort the test.
* If the assumption is invalid, this method does nothing. If the assumption is
* valid and the {@code executable} throws an exception, it will be treated like
* a regular test failure. That exception will be rethrown as is
* but {@link ExceptionUtils#throwAsUncheckedException masked} as an unchecked
* exception.
*
* @param assumptionSupplier the supplier of the assumption to validate
* @param executable the block of code to execute if the assumption is valid
* @see #assumingThat(boolean, Executable)
*/
public static void assumingThat(BooleanSupplier assumptionSupplier, Executable executable) {
assumingThat(assumptionSupplier.getAsBoolean(), executable);
}
/**
* Execute the supplied {@link Executable}, but only if the supplied
* assumption is valid.
*
*
Unlike the other assumption methods, this method will not abort the test.
* If the assumption is invalid, this method does nothing. If the assumption is
* valid and the {@code executable} throws an exception, it will be treated like
* a regular test failure. That exception will be rethrown as is
* but {@link ExceptionUtils#throwAsUncheckedException masked} as an unchecked
* exception.
*
* @param assumption the assumption to validate
* @param executable the block of code to execute if the assumption is valid
* @see #assumingThat(BooleanSupplier, Executable)
*/
public static void assumingThat(boolean assumption, Executable executable) {
if (assumption) {
try {
executable.execute();
}
catch (Throwable t) {
throw ExceptionUtils.throwAsUncheckedException(t);
}
}
}
// --- abort ---------------------------------------------------------------
/**
* Abort the test without a message.
*
*
Although aborting with an explicit message is recommended, this may be
* useful when maintaining legacy code.
*
*
See Javadoc for {@link #abort(String)} for an explanation of this
* method's generic return type {@code V}.
*
* @throws TestAbortedException always
* @since 5.9
*/
@API(status = STABLE, since = "5.9")
public static V abort() {
throw new TestAbortedException();
}
/**
* Abort the test with the given {@code message}.
*
* The generic return type {@code V} allows this method to be used
* directly as a single-statement lambda expression, thereby avoiding the
* need to implement a code block with an explicit return value. Since this
* method throws a {@link TestAbortedException} before its return statement,
* this method never actually returns a value to its caller. The following
* example demonstrates how this may be used in practice.
*
*
{@code
* Stream.of().map(entry -> abort("assumption not met"));
* }
*
* @param message the message to be included in the {@code TestAbortedException}
* @throws TestAbortedException always
* @since 5.9
*/
@API(status = STABLE, since = "5.9")
public static V abort(String message) {
throw new TestAbortedException(message);
}
/**
* Abort the test with the supplied message.
*
* See Javadoc for {@link #abort(String)} for an explanation of this
* method's generic return type {@code V}.
*
* @param messageSupplier the supplier of the message to be included in the
* {@code TestAbortedException}
* @throws TestAbortedException always
* @since 5.9
*/
@API(status = STABLE, since = "5.9")
public static V abort(Supplier messageSupplier) {
throw new TestAbortedException(messageSupplier.get());
}
private static void throwAssumptionFailed(String message) {
throw new TestAbortedException(
StringUtils.isNotBlank(message) ? "Assumption failed: " + message : "Assumption failed");
}
}