net.obvj.junit.utils.matchers

Class ExceptionMatcher

java.lang.Object

org.hamcrest.BaseMatcher<T>

org.hamcrest.TypeSafeDiagnosingMatcher<Runnable>

net.obvj.junit.utils.matchers.ExceptionMatcher

All Implemented Interfaces:

org.hamcrest.Matcher<Runnable>, org.hamcrest.SelfDescribing

public class ExceptionMatcher
extends org.hamcrest.TypeSafeDiagnosingMatcher<Runnable>

A Matcher that matches if a procedure throws an expected exception.

For example:

 
 assertThat(() -> obj.doStuff("p1"),
         throwsException(NullPointerException.class));
 
 

Exception details, such as message and cause, can also be evaluated using additional methods. For example:

 
 assertThat(() -> obj.doStuff("p1"),
         throwsException(IllegalStateException.class)
             .withCause(FileNotFoundException.class));

 assertThat(() -> obj.doStuff(null),
         throwsException(MyException.class)
             .withMessageContaining("ERR-12008"));
 
 

Since:

1.1.0

Author:

oswaldo.bapvic.jr

Method Summary

Modifier and Type	Method and Description
void	describeTo(org.hamcrest.Description description) Describes the "expected" pat of the test description.
static ExceptionMatcher	throwsException(Class<? extends Exception> exception) Creates a matcher that matches if the examined procedure throws a given exception.
ExceptionMatcher	withCause(Class<? extends Throwable> cause) Assigns an expected cause for evaluation.
ExceptionMatcher	withMessageContaining(String... substrings) Assigns one or more expected substrings for the exception message evaluation.

Methods inherited from class org.hamcrest.TypeSafeDiagnosingMatcher

describeMismatch, matches

Methods inherited from class org.hamcrest.BaseMatcher

_dont_implement_Matcher___instead_extend_BaseMatcher_, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

throwsException

public static ExceptionMatcher throwsException(Class<? extends Exception> exception)

Creates a matcher that matches if the examined procedure throws a given exception.

For example:

 
 assertThat(() -> obj.doStuff("p1"),
         throwsException(IllegalStateException.class));
 
 

The matcher matches if the actual exception class is either the same as, or is a child of, the Throwable represented by the specified parameter.

For example, if the examined code throws a NullPointerException, all of the following assertions are valid:

 
 assertThat( ... throwsException(NullPointerException.class));
 assertThat( ... throwsException(RuntimeException.class));
 assertThat( ... throwsException(Exception.class));
 
 

In other words, the matcher tests whether the actual exception can be converted to the specified class.

Parameters:

exception - the expected exception class. A null value is allowed, and means that no exception is expected

Returns:

the matcher

withCause

public ExceptionMatcher withCause(Class<? extends Throwable> cause)

Assigns an expected cause for evaluation.

For example:

 
 assertThat(() -> obj.doStuff("p1"),
         throwsException(IllegalStateException.class)
             .withCause(FileNotFoundException.class));
 
 

The matcher matches if the actual cause class is either the same as, or is a child of, the Throwable represented by the specified parameter.

For example, if the examined cause is a NullPointerException, all of the following assertions are valid:

 
 withCause(NullPointerException.class);
 withCause(RuntimeException.class);
 withCause(Exception.class);
 
 

In other words, the matcher tests whether the actual cause can be converted to the specified class.

Parameters:

cause - the expected cause. A null value is allowed, and means that an exception without cause is expected

Returns:

the matcher, incremented with a given cause for testing

withMessageContaining

public ExceptionMatcher withMessageContaining(String... substrings)

Assigns one or more expected substrings for the exception message evaluation.

For example:

 
 assertThat(() -> obj.doStuff(null),
         throwsException(IllegalArgumentException.class)
             .withMessageContaining("argument cannot be null");

 assertThat(() -> obj.doStuff(null),
         throwsException(MyException.class)
             .withMessageContaining("ERR-12008", "mandatory");
 
 

Parameters:

substrings - a substring of the exception message to be checked

Returns:

the matcher, incremented with a given message for testing

describeTo

public void describeTo(org.hamcrest.Description description)

Describes the "expected" pat of the test description.

See Also:

SelfDescribing.describeTo(Description)