Hamcrest Matchers
Hamcrest is a popular framework that help us to create the matcher objects. It is used for writing software tests and also performs unit testing in Java programming language. Hamcrest is mainly used with other unit testing frameworks like JUnit, jMockit, Mockito, etc.
Hamcrest framework is designed to make the test more readable and understandable. It makes the use of static methods to construct an assertion that is very easy to write and understand. It has been ported to C#, Python, PHP, JavaScript, C++, Rust, and Swift.
The Hamcrest framework was designed to accommodate different types of unit testing frameworks. For example, Hamcrest can be used with TestNG and JUnit (all versions). The Hamcrest framework is also used with mocking frameworks such as JMock, EasyMock, and Mockito.
Following are some important methods of the Matchers class are:
| Method type and method name | Description |
|---|---|
| Matcher<java.lang.Object> anything() | It creates a matcher that always matches to the object, regardless of the examined object. |
| Matcher<T> describedAs(java.lang.String description, Matcher<T> matcher, java.lang.object… values) | It is used to wrap an existing matcher and also overrides its specified description. |
| Matcher<T> is(Matcher<T> matcher) | It acts as an adjective to the other matchers along with retaining its behavior, and allowing tests to be more readable. |
| Matcher<T> allOf(java.lang.Iterable<Matcher<? Super T>> matchers) | It creates a matcher that matches, if the examined object matches ALL of the specified matchers. |
| AnyOf<T> anyOf(java.lang.Iterable<Matcher<? Super T>> matchers) | It creates a matcher that matches, if the examined object matches ANY of the specified matchers. |
| Matcher<T> not(Matcher<T> matcher) | It creates a matcher that wraps an existing matcher, but it inverts the logic by which it will match the objects. |
| Matcher<T> equalTo(T operand) | It creates a matcher that matches when the examined object is logically equal to the specified operand. |
| Matcher<T> hasToString(Matcher<? super java.lang.String> toStringMatcher) | It creates a matcher that matches any examined object whose toString method returns a value that satisfies the specified matcher. |
| Matcher<T> instanceOf(java.lang.Class<?>> type) | It creates a matcher that matches when the examined object is an instance of the specified type, as determined by calling the Class.isInstance(Object) method. |
| Matcher<java.lang.object> notNullValue() | It creates a shortcut to the frequently used notNullValues. |
| Matcher<T> sameInstance(T target) | It creates a matcher that matches only when the examined object is the same instance as the specified target object. |
| Matcher<T> hasProperty(java.lang.String propertyName) | It creates a matcher that matches when the examined object has a JavaBean property with the specified name. |
| IsArray<T> array(Matcher<? super T>>… elementMatchers) | It creates a matcher that matches arrays whose elements are convinced with the specified matchers. |
| Matcher<java.util.Map<? extends K,? extends V>> hasEntry(K key, V value) | It creates a matcher for the Maps matching when the examined Map contains at least one entry whose key and value equals to the specified key and value. |
| Matcher<T[]> hasItemInArray(Matcher<? super T> elementMatcher) | It creates a matcher for arrays that matches when the examined array contains at least one item that should be matched with the specified elementMatcher. |
| Matcher<java.math.BigDecimal> closeTo(java.math.BigDecimal operand, java.math.BigDecimal error) | It creates a matcher of BigDecimals that matches when an examined BigDecimal object is equal to the specified operand within a range of +/- error. |
| Matcher<T> greaterThan(T value) | It creates a matcher of Comparable object that matches when the examined object is greater than the specified value. |
| Matcher<T> lessThan(T value) | It creates a matcher of Comparable object that matches when the examined object is less than the specified value. |
| Matcher<java.lang.String> equalToIgnoringCase(java.lang.String expectedString) | It creates a matcher of String that matches when the examined string is equal to the specified expectedString, ignoring case. |
The following code snippet shows how to use the Hamcrest matcher. It shows that the given list or array hasSize(5) contains five items. Here, num is the object of the list that contains some integers.
The following code snippet shows that all the items available in the list or array are greaterThan, lessThan, or greaterThanOrEqualTo to the specified number.
Hence, it is clear from the preceding code snippet that Hamcrest framework makes the code easy to read and understand.
Example of Hamcrest
Here, we are going to create a basic Hamcrest example.
HamcrestMockito.java
Output
