public abstract Class AbstractThrowableAssert<SELF extends AbstractThrowableAssert<SELF, ACTUAL>, ACTUAL extends Throwable>

Returns a new assertion object that uses the cause of the current Throwable as the actual Throwable under test.

Examples:

 Throwable cause =  new IllegalArgumentException("wrong amount 123");
Throwable exception = new Exception("boom!", cause);

// typical use:
assertThat(throwableWithMessage).cause()
                                .hasMessageStartingWith("wrong amount");

Returns:AbstractThrowableAssert<?, ?>

a new assertion object

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable does not have a cause.

Since

3.23.0

Verifies that the org.assertj.core.api.ThrowableAssert.ThrowingCallable didn't raise a throwable.

Example :

 assertThatCode(() -> foo.bar()).doesNotThrowAnyException();

Exceptions

AssertionError:

if the actual statement raised a Throwable.

Since

3.7.0

Verifies that the org.assertj.core.api.ThrowableAssert.ThrowingCallable didn't raise a throwable except matching the provided type(s).

Example:

 void foo() {
  throw new IllegalArgumentException();
}

void bar() {
}

// assertions succeed:
assertThatCode(() -> foo()).doesNotThrowAnyExceptionExcept(IllegalArgumentException.class);
assertThatCode(() -> foo()).doesNotThrowAnyExceptionExcept(RuntimeException.class);
assertThatCode(() -> foo()).doesNotThrowAnyExceptionExcept(IllegalArgumentException.class, IllegalStateException.class);
assertThatCode(() -> bar()).doesNotThrowAnyExceptionExcept();

// assertions fails:
assertThatCode(() -> foo()).doesNotThrowAnyExceptionExcept();
assertThatCode(() -> foo()).doesNotThrowAnyExceptionExcept(NumberFormatException.class);
assertThatCode(() -> foo()).doesNotThrowAnyExceptionExcept(NumberFormatException.class, IOException.class);

Parameters

ignoredExceptionTypes:Class<? extends Throwable>[]

types allowed to be thrown.

Annotations

@SafeVarargs

Exceptions

AssertionError:

if the actual statement raised a Throwable with type other than provided one(s).

Since

3.26.0

 Throwable cause =  new IllegalArgumentException("wrong amount 123");
Throwable exception = new Exception("boom!", cause);

// typical use:
assertThat(throwableWithMessage).getCause()
                                .hasMessageStartingWith("wrong amount");

Returns:AbstractThrowableAssert<?, ?>

a new assertion object

Annotations

@Deprecated

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable does not have a cause.

Since

3.16.0

 Throwable rootCause =  new JdbcException("invalid query");
Throwable cause =  new RuntimeException(rootCause);
Throwable exception = new Exception("boom!", cause);

// typical use:
assertThat(throwableWithMessage).getRootCause()
                                .hasMessageStartingWith("invalid");

Returns:AbstractThrowableAssert<?, ?>

a new assertion object

Annotations

@Deprecated

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable does not have a root cause.

Since

3.16.0

Verifies that the actual Throwable has a cause similar to the given one, that is with the same type and message (it does not use the equals method for comparison).

Example:

 Throwable invalidArgException = new IllegalArgumentException("invalid arg");
Throwable throwable = new Throwable(invalidArgException);

// This assertion succeeds:
assertThat(throwable).hasCause(invalidArgException);

// These assertions fail:
assertThat(throwable).hasCause(new IllegalArgumentException("bad arg"));
assertThat(throwable).hasCause(new NullPointerException());
assertThat(throwable).hasCause(null); // prefer hasNoCause()

Parameters

cause:Throwable

the expected cause

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has not the given cause.

Verifies that the cause of the actual Throwable is exactly an instance of the given type.

Example:

 Throwable throwable = new Throwable(new NullPointerException());

// assertion will pass
assertThat(throwable).hasCauseExactlyInstanceOf(NullPointerException.class);

// assertions will fail (even if NullPointerException is a RuntimeException since we want an exact match)
assertThat(throwable).hasCauseExactlyInstanceOf(RuntimeException.class);
assertThat(throwable).hasCauseExactlyInstanceOf(IllegalArgumentException.class);

Parameters

type:Class<? extends Throwable>

the expected cause type.

Returns:SELF

this assertion object.

Exceptions

NullPointerException:

if given type is null.

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has no cause.
• if the cause of the actual Throwable is not exactly an instance of the given type.

Verifies that the cause of the actual Throwable is an instance of the given type.

Example:

 Throwable throwable = new Throwable(new NullPointerException());

// assertions will pass
assertThat(throwable).hasCauseInstanceOf(NullPointerException.class);
assertThat(throwable).hasCauseInstanceOf(RuntimeException.class);

// assertion will fail
assertThat(throwable).hasCauseInstanceOf(IllegalArgumentException.class);

Parameters

type:Class<? extends Throwable>

the expected cause type.

Returns:SELF

this assertion object.

Exceptions

NullPointerException:

if given type is null.

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has no cause.
• if the cause of the actual Throwable is not an instance of the given type.

Verifies that the actual Throwable has a cause that refers to the given one, i.e. using == comparison

Example:

 Throwable invalidArgException = new IllegalArgumentException("invalid arg");
Throwable throwable = new Throwable(invalidArgException);

// This assertion succeeds:
assertThat(throwable).hasCauseReference(invalidArgException);

// These assertions fail:
assertThat(throwable).hasCauseReference(new IllegalArgumentException("invalid arg"));
assertThat(throwable).hasCauseReference(new NullPointerException());
assertThat(throwable).hasCauseReference(null); // prefer hasNoCause()

Parameters

expected:Throwable

the expected cause

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has a cause that does not refer to the given (i.e. actual.getCause() != cause)

Verifies that the message of the actual Throwable is equal to the given one.

Parameters

message:String

the expected message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable is not equal to the given one.

Verifies that the message of the actual (@code Throwable) is equal to the given one, after being formatted using the String#format method.

Example:

 Throwable invalidArgException = new IllegalArgumentException("foo is not a valid input");
Throwable throwable = new Throwable(invalidArgException);

// This assertion succeeds:
assertThat(throwable).hasMessage("%s is not a valid input", "foo");

// These assertions fail:
assertThat(throwable).hasMessage("%s is not a valid input", "bar");
assertThat(throwable).hasMessage("%s is not a valid input", 12);
assertThat(null).hasMessage("%s is not a valid input", "foo");

Parameters

message:String

a format string representing the expected message

parameters:Object[]

argument referenced by the format specifiers in the format string

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable is not equal to the given one.

IllegalFormatException:

if the message contains an illegal syntax according to String#format(String, Object...).

Verifies that the message of the actual Throwable contains the given description.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");
Throwable throwableWithoutMessage = new IllegalArgumentException();

// assertion will pass:
assertThat(throwableWithMessage).hasMessageContaining("123");

// assertions will fail:
assertThat(throwableWithoutMessage).hasMessageContaining("123");
assertThat(throwableWithMessage).hasMessageContaining("234"); 

Parameters

description:String

the description expected to be contained in the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not contain the given description.

Verifies that the message of the actual Throwable contains the given description, after being formatted using the String#format method.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");
Throwable throwableWithoutMessage = new IllegalArgumentException();

// assertion will pass:
assertThat(throwableWithMessage).hasMessageContaining("amount %d", 123);

// assertions will fail:
assertThat(throwableWithoutMessage).hasMessageContaining("amount %d", 123);
assertThat(throwableWithMessage).hasMessageContaining("%s amount", "right"); 

Parameters

description:String

the description expected to be contained in the actual Throwable's message.

parameters:Object[]

argument referenced by the format specifiers in the format string

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not contain the given description.

IllegalFormatException:

if the message contains an illegal syntax according to String#format(String, Object...).

Verifies that the message of the actual Throwable contains all the given values.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");
Throwable throwableWithoutMessage = new IllegalArgumentException();

// assertion will pass:
assertThat(throwableWithMessage).hasMessageContainingAll("amount", "123");

// assertions will fail:
assertThat(throwableWithoutMessage).hasMessageContainingAll("123");
assertThat(throwableWithMessage).hasMessageContainingAll("234"); 

Parameters

values:CharSequence[]

the Strings expected to be contained in the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not contain all the given values.

Verifies that the message of the actual Throwable ends with the given description.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");

// assertion will pass
assertThat(throwableWithMessage).hasMessageEndingWith("123");

// assertion will fail
assertThat(throwableWithMessage).hasMessageEndingWith("456");

Parameters

description:String

the description expected to end the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not end with the given description.

Verifies that the message of the actual Throwable ends with the given description, after being formatted using the String#format method.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");

// assertion will pass
assertThat(throwableWithMessage).hasMessageEndingWith("%s 123", "amount");

// assertion will fail
assertThat(throwableWithMessage).hasMessageEndingWith("amount %d", 456);

Parameters

description:String

the description expected to end the actual Throwable's message.

parameters:Object[]

argument referenced by the format specifiers in the format string

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not end with the given description.

IllegalFormatException:

if the message contains an illegal syntax according to String#format(String, Object...).

Verifies that a sequence of the message of the actual Throwable matches with the given regular expression (see java.util.regex.Matcher#find()).
The Pattern used under the hood enables the Pattern#DOTALL mode.

Examples:

 Throwable throwable = new IllegalArgumentException("Dear John,\n" +
                                                   "it' s a wrong amount");
// assertion will pass
assertThat(throwable).hasMessageFindingMatch("wrong amount");
assertThat(throwable).hasMessageFindingMatch("Dear John");
assertThat(throwable).hasMessageFindingMatch("wrong amount$");

// assertion will fail
assertThat(throwable).hasMessageFindingMatch("Dear John$");

Parameters

regex:String

the regular expression expected to be found in the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable doesn't contain any sequence matching with the given regular expression

NullPointerException:

if the regex is null

Since

3.12.0

Verifies that the message of the Throwable under test matches the given regular expression.

Examples:

 Throwable throwable = new IllegalArgumentException("wrong amount 123");

// assertion succeeds
assertThat(throwable).hasMessageMatching("wrong amount [0-9]*");

// assertion fails
assertThat(throwable).hasMessageMatching("wrong amount [0-9]* euros");

Parameters

regex:String

the regular expression of value expected to be matched the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not match the given regular expression.

NullPointerException:

if the regex is null

Verifies that the message of the Throwable under test matches the given regular expression Pattern.

Examples:

 Throwable throwable = new IllegalArgumentException("wrong amount 123");

// assertion succeeds
assertThat(throwable).hasMessageMatching(Pattern.compile("wrong amount [0-9]*"));

// assertion fails
assertThat(throwable).hasMessageMatching(Pattern.compile("wrong amount [0-9]* euros"));

Parameters

regex:Pattern

the regular expression of value expected to be matched the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not match the given regular expression.

NullPointerException:

if the regex is null

Verifies that the message of the actual Throwable does not contain the given content or is null.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");
Throwable throwableWithoutMessage = new IllegalArgumentException();

// assertions will pass:
assertThat(throwableWithMessage).hasMessageNotContaining("234");
assertThat(throwableWithoutMessage).hasMessageNotContaining("foo");

// assertion will fail:
assertThat(throwableWithMessage).hasMessageNotContaining("amount");

Parameters

content:String

the content expected not to be contained in the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable contains the given content.

Since

3.12.0

Verifies that the message of the actual Throwable does not contain any of the given values or is null.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");
Throwable throwableWithoutMessage = new IllegalArgumentException();

// assertions will pass:
assertThat(throwableWithMessage).hasMessageNotContainingAny("234");
assertThat(throwableWithoutMessage).hasMessageNotContainingAny("foo");

// assertion will fail:
assertThat(throwableWithMessage).hasMessageNotContainingAny("foo", "amount");

Parameters

values:CharSequence[]

the contents expected to not be contained in the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable contains any of the given values.

Since

3.12.0

Verifies that the message of the actual Throwable starts with the given description.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");

// assertion will pass:
assertThat(throwableWithMessage).hasMessageStartingWith("wrong amount");

// assertions will fail:
assertThat(throwableWithMessage).hasMessageStartingWith("right amount"); 

Parameters

description:String

the description expected to start the actual Throwable's message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not start with the given description.

Verifies that the message of the actual Throwable starts with the given description, after being formatted using the String#format method.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");

// assertion will pass:
assertThat(throwableWithMessage).hasMessageStartingWith("%s amount", "wrong");

// assertions will fail:
assertThat(throwableWithMessage).hasMessageStartingWith("%s amount", "right"); 

Parameters

description:String

the description expected to start the actual Throwable's message.

parameters:Object[]

argument referenced by the format specifiers in the format string

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the message of the actual Throwable does not start with the given description.

IllegalFormatException:

if the message contains an illegal syntax according to String#format(String, Object...).

Verifies that the actual Throwable does not have a cause.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has a cause.

Verifies that the actual Throwable has no suppressed exceptions.

Example:

 // assertion will pass
assertThat(new Throwable()).hasNoSuppressedExceptions();

// assertion will fail
Throwable throwableWithSuppressedException = new Throwable();
throwableWithSuppressedException.addSuppressed(new IllegalArgumentException());
assertThat(throwableWithSuppressedException).hasNoSuppressedExceptions();

Returns:SELF

this assertion object.

Exceptions

NullPointerException:

if given type is null.

AssertionError:

if the actual Throwable has any suppressed exceptions.

Since

2.6.0 / 3.6.0

Verifies that the actual Throwable has a root cause similar to the given one, that is with the same type and message (it does not use the equals method for comparison).

Example:

 Throwable invalidArgException = new IllegalArgumentException("invalid arg");
Throwable throwable = new Throwable(new RuntimeException(invalidArgException));

// This assertion succeeds:
assertThat(throwable).hasRootCause(invalidArgException);

// These assertions fail:
assertThat(throwable).hasRootCause(new IllegalArgumentException("bad arg"));
assertThat(throwable).hasRootCause(new RuntimeException());
assertThat(throwable).hasRootCause(null); // prefer hasNoCause()

Parameters

cause:Throwable

the expected root cause

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has not the given cause.

Since

3.12.0

Verifies that the root cause of the actual Throwable is exactly an instance of the given type.

Example:

 Throwable throwable = new Throwable(new IllegalStateException(new NullPointerException()));

// assertion will pass
assertThat(throwable).hasRootCauseExactlyInstanceOf(NullPointerException.class);

// assertions will fail (even if NullPointerException is a RuntimeException since we want an exact match)
assertThat(throwable).hasRootCauseExactlyInstanceOf(RuntimeException.class);
assertThat(throwable).hasRootCauseExactlyInstanceOf(IllegalStateException.class);

Parameters

type:Class<? extends Throwable>

the expected cause type.

Returns:SELF

this assertion object.

Exceptions

NullPointerException:

if given type is null.

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has no cause.
• if the root cause of the actual Throwable is not exactly an instance of the given type.

Verifies that the root cause of the actual Throwable is an instance of the given type.

Example:

 Throwable throwable = new Throwable(new IllegalStateException(new NullPointerException()));

// assertions will pass
assertThat(throwable).hasRootCauseInstanceOf(NullPointerException.class);
assertThat(throwable).hasRootCauseInstanceOf(RuntimeException.class);

// assertion will fail
assertThat(throwable).hasRootCauseInstanceOf(IllegalStateException.class);

Parameters

type:Class<? extends Throwable>

the expected cause type.

Returns:SELF

this assertion object.

Exceptions

NullPointerException:

if given type is null.

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable has no cause.
• if the cause of the actual Throwable is not an instance of the given type.

Verifies that the message of the root cause of the actual Throwable is equal to the given one.

Example:

 Throwable throwable = new Throwable(new IllegalStateException(new NullPointerException("object")));

// assertion will pass
assertThat(throwable).hasRootCauseMessage("object");

// assertions will fail
assertThat((Throwable) null).hasRootCauseMessage("object");
assertThat(throwable).hasRootCauseMessage("another object");
assertThat(new Throwable()).hasRootCauseMessage("object");
assertThat(new Throwable(new NullPointerException())).hasRootCauseMessage("object");

Parameters

message:String

the expected root cause message.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the root cause of the actual Throwable is null.
• if the message of the root cause of the actual Throwable is not equal to the given one.

Since

3.14.0

Verifies that the message of the root cause of the actual Throwable is equal to the given one, after being formatted using String#format(String, Object...) method.

Example:

Throwable throwable = new Throwable(new IllegalStateException(new NullPointerException("expected message")));

// assertion will pass
assertThat(throwable).hasRootCauseMessage("%s %s", "expected", "message");

// assertions will fail
assertThat((Throwable) null).hasRootCauseMessage("%s %s", "expected", "message");
assertThat(throwable).hasRootCauseMessage("%s", "message");
assertThat(new Throwable()).hasRootCauseMessage("%s %s", "expected", "message");
assertThat(new Throwable(new NullPointerException())).hasRootCauseMessage("%s %s", "expected", "message");

Parameters

message:String

the expected root cause message.

parameters:Object[]

argument referenced by the format specifiers in the format string.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the root cause of the actual Throwable is null.
• if the message of the root cause of the actual Throwable is not equal to the given one.

IllegalFormatException:

if the message contains an illegal syntax according to String#format(String, Object...).

Since

3.14.0

Verifies that the stack trace of the actual Throwable contains the given description.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");

// assertion will pass
assertThat(throwableWithMessage).hasStackTraceContaining("amount 123");

// assertion will fail
assertThat(throwableWithMessage).hasStackTraceContaining("456");

Parameters

description:String

the description expected to be contained in the actual Throwable's stack trace.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the stack trace of the actual Throwable does not contain the given description.

Verifies that the stack trace of the actual Throwable contains the given description, after being formatted using the String#format method.

Examples:

 Throwable throwableWithMessage = new IllegalArgumentException("wrong amount 123");

// assertion succeeds
assertThat(throwableWithMessage).hasStackTraceContaining("%s", amount);

// assertion fails
assertThat(throwableWithMessage).hasStackTraceContaining("%d", 456);

Parameters

description:String

the description expected to be contained in the actual Throwable's stack trace.

parameters:Object[]

argument referenced by the format specifiers in the format string

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the stack trace of the actual Throwable does not contain the given description.

IllegalFormatException:

if the message contains an illegal syntax according to String#format(String, Object...).

Verifies that the actual Throwable has a suppressed exception similar to the given one, that is with the same type and message (it does not use the equals method for comparison).

Example:

 Throwable throwable = new Throwable();
Throwable invalidArgException = new IllegalArgumentException("invalid argument");
throwable.addSuppressed(invalidArgException);

// These assertions succeed:
assertThat(throwable).hasSuppressedException(invalidArgException);
assertThat(throwable).hasSuppressedException(new IllegalArgumentException("invalid argument"));

// These assertions fail:
assertThat(throwable).hasSuppressedException(new IllegalArgumentException("invalid parameter"));
assertThat(throwable).hasSuppressedException(new NullPointerException());

Parameters

suppressedException:Throwable

the expected suppressed exception

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable does not have the given suppressed exception.

Since

2.6.0 / 3.6.0

A shortcut for extracting(Throwable::getMessage, as(InstanceOfAssertFactories.STRING)) which allows to extract a throwable's message and then execute assertions on it.

Note that once you have navigated to the throwable's message you can't navigate back to the throwable.

Example :

 Throwable throwable = new Throwable("boom!");

// assertions succeed:
assertThat(throwable).message().startsWith("boo")
                               .endsWith("!");

// assertion fails:
assertThat(throwable).message().isEmpty();

Returns:AbstractStringAssert<?>

the created StringAssert on the throwable message.

Since

3.22.0

Returns a new assertion object that uses the root cause of the current Throwable as the actual Throwable under test.

Examples:

 Throwable rootCause =  new JdbcException("invalid query");
Throwable cause =  new RuntimeException(rootCause);
Throwable exception = new Exception("boom!", cause);

// typical use:
assertThat(throwableWithMessage).rootCause()
                                .hasMessageStartingWith("invalid");

Returns:AbstractThrowableAssert<?, ?>

a new assertion object

Exceptions

AssertionError:

• if the actual Throwable is null.
• if the actual Throwable does not have a root cause.

Since

3.23.0