Module com.github.robtimus.junit.support
Package com.github.robtimus.junit.support

Class ThrowableAsserter<R>

  • Type Parameters:
    R - The result type of the code to execute.
    public final class ThrowableAsserter<R>
extends Object
    An object that asserts that executing an Executable or retrieving the value of a ThrowingSupplier throws an error.

    This class is like several of the throwing assertions of ThrowableAssertions, especially the "one-of" assertions, but it provides more flexibility. It also removes the need for checking the return type of the returned error in case of the "one-of" assertions; instead, a set of assertions can be configured per expected error type (or none to just specify that the error type is one of the expected error types).

    This class should be used as follows:

    1. Call one of the static whenThrows or whenThrowsExactly methods to create an instance, and specify the assertions for that error type using thenAssert or thenAssertNothing.
    2. Call whenThrows and whenThrowsExactly any number of times and in any order, and specify the assertions for that error type using thenAssert or thenAssertNothing.
      However, all calls must be unique, i.e. you cannot call whenThrows twice with the same type, or call whenThrowsExactly twice with the same type
    3. Call whenThrowsNothing at most once, and specify the assertions for no error using thenAssert or thenAssertNothing.
    4. Call execute. This will execute the Executable or retrieve the value of the ThrowingSupplier, and perform the necessary assertions.
    5. Optionally, use the return value of the execute method to retrieve the error that was thrown or the ThrowingSupplier's value.

    An example: 

    
 whenThrows(UnsupportedOperationException.class, () -> map.computeIfAbsent(key, function)).thenAssertNothing()
         .whenThrows(IllegalArgumentException.class).thenAssert(thrown -> assertSame(exception, thrown))
         .execute();

    All methods throw a NullPointerException when provided with null arguments unless specified otherwise.

    Author:
    Rob Spoor
    Since:
    2.0

    • Method Detail

      • whenThrows

        public static <T extends Throwable> ThrowableAsserter.ThrownError<T,​Void> whenThrows​(Class<T> errorType,
                                                                                           Executable executable)
        Returns an object for configuring the assertions that should be performed when an instance of a specific error type is thrown when an Executable is run.
        Type Parameters:
        T - The error type.
        Parameters:
        errorType - The error type.
        executable - The Executable to run.
        Returns:
        An object for configuring the assertions that should be performed when an instance of a specific error type is thrown.
        See Also:
        Assertions.assertThrows(Class, Executable)

      • whenThrows

        public <T extends Throwable> ThrowableAsserter.ThrownError<T,​R> whenThrows​(Class<T> errorType)
        Returns an object for configuring the assertions that should be performed when an instance of a specific error type is thrown.
        Type Parameters:
        T - The error type.
        Parameters:
        errorType - The error type.
        Returns:
        An object for configuring the assertions that should be performed when an instance of a specific error type is thrown.
        Throws:
        IllegalArgumentException - If this method has already been called with the given error type.
        See Also:
        Assertions.assertThrows(Class, Executable)

      • whenThrowsExactly

        public static <T extends Throwable> ThrowableAsserter.ThrownError<T,​Void> whenThrowsExactly​(Class<T> errorType,
                                                                                                  Executable executable)
        Returns an object for configuring the assertions that should be performed when an exact instance of a specific error type is thrown when an Executable is run.
        Type Parameters:
        T - The error type.
        Parameters:
        errorType - The error type.
        executable - The Executable to run.
        Returns:
        An object for configuring the assertions that should be performed when an exact instance of a specific error type is thrown.
        See Also:
        Assertions.assertThrowsExactly(Class, Executable)

      • whenThrowsExactly

        public <T extends Throwable> ThrowableAsserter.ThrownError<T,​R> whenThrowsExactly​(Class<T> errorType)
        Returns an object for configuring the assertions that should be performed when an exact instance of a specific error type is thrown.
        Type Parameters:
        T - The error type.
        Parameters:
        errorType - The error type.
        Returns:
        An object for configuring the assertions that should be performed when an exact instance of a specific error type is thrown.
        Throws:
        IllegalArgumentException - If this method has already been called with the given error type.
        See Also:
        Assertions.assertThrowsExactly(Class, Executable)

      • whenThrowsNothing

        public ThrowableAsserter.NoError<R> whenThrowsNothing()
        Returns an object for configuring the assertions that should be performed if no error is thrown.

        If this method is not called, execute(), execute(String) and execute(Supplier) will fail if no error is thrown.

        Returns:
        An object for configuring the assertions that should be performed if no error is thrown.
        Throws:
        IllegalStateException - If this method is called without configuring the assertions for at least one error type, or If this method has already been called.

      • execute

        public ThrowableAsserter.Asserted<R> execute​(String message)
        Executes the Executable or retrieves the value of the ThrowingSupplier used to create this object, and perform the necessary assertions.
        Parameters:
        message - The failure message to fail with; may be null.
        Returns:
        An object that represents this object in its asserted state.
        Throws:
        AssertionFailedError - If an error is thrown that is not an instance of one of the configured error types, or if no error is thrown and whenThrowsNothing() has not been called.

      • execute

        public ThrowableAsserter.Asserted<R> execute​(Supplier<String> messageSupplier)
        Executes the Executable or retrieves the value of the ThrowingSupplier used to create this object, and perform the necessary assertions.
        Parameters:
        messageSupplier - The supplier for the failure message to fail with; may be null.
        Returns:
        An object that represents this object in its asserted state.
        Throws:
        AssertionFailedError - If an error is thrown that is not an instance of one of the configured error types, or if no error is thrown and whenThrowsNothing() has not been called.