net.obvj.junit.utils.matchers

Class AdvancedMatchers

java.lang.Object

net.obvj.junit.utils.matchers.AdvancedMatchers

public class AdvancedMatchers
extends Object

A class that groups all Matchers provided by junit-utils, so that they can be accessed with a single static import declaration.

For example:

  import static net.obvj.junit.utils.matchers.AdvancedMatchers.*;

  ...

  assertThat(() -> obj.doStuff(),
          throwsException(IllegalStateException.class)
              .withMessage(containsAll("invalid state").ignoreCase()));
 

Since:

1.2.1

Author:

oswaldo.bapvic.jr

Method Summary

Modifier and Type	Method and Description
static StringMatcher	containsAll(String... substrings) Creates a matcher that matches if the examined string contains all of the specified substrings (regardless of the order they appear in the string).
static StringMatcher	containsAny(String... substrings) Creates a matcher that matches if the examined string contains any of the specified substrings.
static StringMatcher	containsNone(String... substrings) Creates a matcher that matches if the examined string contains none of the specified substrings.
static InstantiationNotAllowedMatcher	instantiationNotAllowed() Creates a matcher that matches if the examined class cannot be instantiated, which is particularly useful for utility classes.
static IsNegativeMatcher	isNegative() A matcher that matches if a Number is negative.
static IsPositiveMatcher	isPositive() A matcher that matches if a Number is positive.
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, 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.

If applicable, the matcher can also be incremented to validate the exception message and cause.

For example:

  assertThat(() -> obj.doStuff(""),
          throwsException(IllegalArgumentException.class)
              .withMessage("The argument must not be empty"));
 

Parameters:

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

Returns:

the matcher

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

instantiationNotAllowed

public static InstantiationNotAllowedMatcher instantiationNotAllowed()

Creates a matcher that matches if the examined class cannot be instantiated, which is particularly useful for utility classes.

For example:

 assertThat(TestUtils.class, instantiationNotAllowed());
 

First, the matcher verifies all declared constructors, and then it tries to create a new instance using the default constructor.

A matching class shall have all constructors declared as private and throw an exception inside the default constructor, so it can never be instantiated.

For example:

 private MyClass()
 {
     throw new IllegalStateException("Instantiation not allowed");
 }
 

If applicable, the matcher can also be incremented to validate the exception thrown by the constructor:

  assertThat(TestUtils.class, instantiationNotAllowed()
          .throwing(IllegalStateException.class)
              .withMessage("Instantiation not allowed"));
 

Returns:

the matcher

containsAll

public static StringMatcher containsAll(String... substrings)

Creates a matcher that matches if the examined string contains all of the specified substrings (regardless of the order they appear in the string).

For example:

 assertThat("the quick brown fox", containsAll("fox", "the"))
 

By default, the matcher is case-sensitive, but this behavior can be modified with an additional method call.

For example:

 assertThat("the quick brown fox", containsAll("FOX", "The").ignoreCase())
 

Parameters:

substrings - the substrings to be tested

Returns:

the matcher

containsAny

public static StringMatcher containsAny(String... substrings)

Creates a matcher that matches if the examined string contains any of the specified substrings.

For example:

 assertThat("the quick brown fox", containsAny("fox", "dragon"))
 

By default, the matcher is case-sensitive, but this behavior can be modified with an additional method call.

For example:

 assertThat("the quick brown fox", containsAny("FOX", "dragon").ignoreCase())
 

Parameters:

substrings - the substrings to be tested

Returns:

the matcher

containsNone

public static StringMatcher containsNone(String... substrings)

Creates a matcher that matches if the examined string contains none of the specified substrings.

For example:

 assertThat("the quick brown fox", containsNone("cat", "mouse"))
 

Parameters:

substrings - the substrings to be tested

Returns:

the matcher

isPositive

public static IsPositiveMatcher isPositive()

A matcher that matches if a Number is positive.

This is particularly useful in situations where the exact value of an operation is unpredictable.

For example:

 assertThat(stopwatch.elapsedTime(TimeUnit.MILLISECONDS), isPositive());
 

Returns:

the matcher

Since:

1.3.0

isNegative

public static IsNegativeMatcher isNegative()

A matcher that matches if a Number is negative.

This is particularly useful in situations where the exact value of an operation is unpredictable.

For example:

 assertThat(duration.compareTo(otherDuration), isNegative());
 

Returns:

the matcher

Since:

1.3.0