net.obvj.junit.utils.matchers

Class ExceptionMatcher

java.lang.Object

org.hamcrest.BaseMatcher<T>

org.hamcrest.TypeSafeDiagnosingMatcher<Procedure>

net.obvj.junit.utils.matchers.ExceptionMatcher

All Implemented Interfaces:

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

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

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	exception(Class<? extends Exception> exception) This method behaves exactly the same as calling throwsException(Class).
static ExceptionMatcher	throwsException() Creates a matcher that matches if the examined procedure throws any exception.
static ExceptionMatcher	throwsException(Class<? extends Exception> exception) Creates a matcher that matches if the examined procedure throws a given exception.
static org.hamcrest.Matcher<Procedure>	throwsNoException() Creates a matcher that matches if the examined procedure throws no exception.
<T> ExceptionMatcher	with(Function<? super T,Object> function, org.hamcrest.Matcher<?> matcher) Uses the given function to extract a value from the expected throwable, and a matcher to be used against the function's result.
ExceptionMatcher	withCause(Class<? extends Throwable> cause) Assigns an expected cause for evaluation.
ExceptionMatcher	withCause(ExceptionMatcher matcher) Assigns another ExceptionMatcher to be used for the exception cause validation.
ExceptionMatcher	withMessage(org.hamcrest.Matcher<String> matcher) Assigns an external Matcher to be used in combination for the exception message validation.
ExceptionMatcher	withMessage(String message) Assigns an expected message for validation.
ExceptionMatcher	withMessageContaining(String... substrings) Assigns one or more expected substrings for exception message validation.
ExceptionMatcher	withNoCause() Instruct the matcher to ensure that the expected exception has no cause.

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()

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

For example:

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

Note: This has the same effect as calling:

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

Returns:

the matcher

Since:

1.3.1

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 Exception 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

Since:

1.1.0

exception

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

This method behaves exactly the same as calling throwsException(Class).

It was created primarily to allow a nested ExceptionMatcher to validate the cause of an exception.

For example:

  assertThat(() -> obj.doStuff("p1"),
         throwsException(IllegalArgumentException.class)
             .withCause(
                 exception(FileNotFoundException.class)
                     .withMessage("File p1 not found"));
 

Parameters:

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

Returns:

a new matcher

Since:

1.6.0

See Also:

throwsException(Class)

throwsNoException

public static org.hamcrest.Matcher<Procedure> throwsNoException()

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

For example:

 
 assertThat(() -> obj.doStuff("p1"),
         throwsNoException());
 

Note: This has the same effect as calling:

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

Returns:

the matcher

Since:

1.3.1

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

Returns:

the matcher, incremented with a given cause for testing

Since:

1.1.0

withCause

public ExceptionMatcher withCause(ExceptionMatcher matcher)

Assigns another ExceptionMatcher to be used for the exception cause validation.

For example:

  assertThat(() -> obj.doStuff("p1"),
         throwsException(IllegalArgumentException.class)
             .withCause(
                 exception(FileNotFoundException.class)
                     .withMessage("File p1 not found"));
 

Parameters:

matcher - the matcher to be used in combination for exception cause validation

Returns:

the matcher, incremented with the specified matcher for testing

Since:

1.6.0

See Also:

exception(Class)

withNoCause

public ExceptionMatcher withNoCause()

Instruct the matcher to ensure that the expected exception has no cause.

Returns:

the matcher, enabled for cause cause checking, and expecting none

Since:

1.6.0

withMessage

public ExceptionMatcher withMessage(org.hamcrest.Matcher<String> matcher)

Assigns an external Matcher to be used in combination for the exception message validation.

For example:

• Combining the ExceptionMatcher and Hamcrest's CoreMatchers:

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

• Combining the ExceptionMatcher with CoreMatchers and StringMatcher:

   
   assertThat(() -> obj.doStuff(null),
           throwsException(MyException.class)
               .withMessage(either(startsWith("ERR-0001"))
                   .or(containsAny("division by zero").ignoreCase())));
   

Parameters:

matcher - the matcher to be used in combination for exception message validation

Returns:

the matcher, incremented with the specified matcher for testing

Since:

1.2.0

withMessage

public ExceptionMatcher withMessage(String message)

Assigns an expected message for validation.

For example:

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

Note: This has the same effect as calling:

 withMessage(equalTo("argument cannot be null"));
 

Parameters:

message - the message for exception validation

Returns:

the matcher, incremented with the specified message for testing

Since:

1.2.0

withMessageContaining

public ExceptionMatcher withMessageContaining(String... substrings)

Assigns one or more expected substrings for exception message validation.

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 - one or more substrings for exception message validation

Returns:

the matcher, incremented with the specified substring(s) for testing

Since:

1.1.0

with

public <T> ExceptionMatcher with(Function<? super T,Object> function,
                                 org.hamcrest.Matcher<?> matcher)

Uses the given function to extract a value from the expected throwable, and a matcher to be used against the function's result.

This can be particularly useful to extract custom exception data using a method reference or a lambda expression.

For example:

 
 assertThat(() -> obj.doStuff(null),
         throwsException(MyCustomException.class)
             .with(MyCustomException::getErrorCode, equalTo(12001))
             .with(MyCustomException::getLocalizedMessage, equalTo("Invalid parameter")));
 

Type Parameters:

T - the expected throwable type

Parameters:

function - a function to be applied to extract the value from the throwable

matcher - the matcher to be used against the function result

Returns:

the matcher, incremented with the specified custom function and matcher

Since:

1.8.0

describeTo

public void describeTo(org.hamcrest.Description description)

Describes the "expected" pat of the test description.

Parameters:

description - the Description to be appended to