{"id":49089,"date":"2015-11-15T23:05:31","date_gmt":"2015-11-15T21:05:31","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=49089"},"modified":"2023-12-13T11:10:32","modified_gmt":"2023-12-13T09:10:32","slug":"hamcrest-matchers-tutorial","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2015\/11\/hamcrest-matchers-tutorial.html","title":{"rendered":"Hamcrest matchers tutorial"},"content":{"rendered":"

This article is part of our Academy Course titled Testing with Mockito<\/a>.<\/p>\n

In this course, you will dive into the magic of Mockito. You will learn about Mocks, Spies and Partial Mocks, and their corresponding Stubbing behaviour. You will also see the process of Verification with Test Doubles and Object Matchers. Finally, Test Driven Development (TDD) with Mockito is discussed in order to see how this library fits in the concept of TDD. Check it out here<\/a>!<\/em>
\nIn this tutorial we will look at the Hamcrest Matcher library and how to integrate it with JUnit and Mockito.<\/p>\n

\n

Table Of Contents<\/h3>\n
\n
1. What is Hamcrest?<\/a><\/dt>\n
2. Including Hamcrest<\/a><\/dt>\n
3. Meet the Matchers<\/a><\/dt>\n
\n
\n
3.1. Simple Matchers<\/a><\/dt>\n
3.2. Simple Matchers Combining Other Matchers<\/a><\/dt>\n<\/dl>\n<\/dd>\n
4. Conclusion<\/a><\/dt>\n<\/dl>\n<\/div>\n

<\/a>1. What is Hamcrest?<\/h2>\n

Hamcrest is a framework for creating matcher objects. These matcher objects are predicates and are used to write rules which can be satisfied under certain conditions. They are most often used in automated testing, though the can be used in other scenarios such as data validation. Hamcrest lets us step beyond simple JUnit asserts and enables us to craft very specific, readable verification code.<\/p>\n

Hamcrest is designed to make tests very readable. It makes liberal use of static methods to create an assertion grammar which is easy to write and to understand. When used in conjunction with JUnit and Mockito it allows us to write clear, concise tests which satisfy the property of good unit testing which is to \u2018test one thing\u2019.<\/p>\n

Suppose we have a String called and we want to test that it is equal to another, expected, string we can use JUnit asserts to test this:<\/p>\n

\nassertEquals(expected, actual);\n<\/pre>\n
In Hamcrest we make use of the JUnit assertThat(valueUnderTest, matcher)<\/code> method. This method always forms the basis of the Hamcrest assert; we are asserting that the value under test satisfies the matcher predicate.  To rewrite the above test in hamcrest at it\u2019s most basic level we could write:<\/p>\n
\nassertThat(actual, equalTo(expected));\n<\/pre>\n
Note the assertThat convention is to have the actual value under test as the first parameter, this is opposite to the assertEquals convention. This is an improvement on readability, but Hamcrest additionally gives us some nice syntactic sugar in the form of the is()<\/code> matcher.  This matcher does nothing itself, it simply relays the result of its input matcher allowing your assertion code to read just like English.  Let\u2019s rewrite the above using is()<\/code>:<\/p>\n
\nassertThat(actual, is(equalTo(expected)));\n<\/pre>\n
Very nice, very readable!<\/p>\n
Hamcrest generates detailed output when its matchers fail, specifying the expected values and the actual values, to assist you in figuring out why the test should fail.  Look at the following test case:<\/p>\n
\n@Test\n    public void test_failed() throws Exception {\n        \/\/ Given\n        Integer number = 7;\n\n        \/\/ Then\n        assertThat(number, greaterThan(10));\n    }\n<\/pre>\n
Obviously this test will fail, but Hamcrest will give detailed information about the failure:<\/p>\n
\njava.lang.AssertionError: \nExpected: a value greater than <10>\n     but: <7> was less than <10>\n<\/pre>\n
Throughout this tutorial we will stick to the convention of having just one assertion as part of our unit tests. This may seem repetitive, particularly where the setup part of the test is the same across a number of tests, however this is good practice in Unit Testing. It allows us to create tests which are targeted – tests will fail only if their single assertion fails, every other assertion will continue to execute. It allows us to create tests which are readable – we can see at a glance the purpose of the test.  It allows us to create test which document the code – we can use test names which convey the granular purpose of the test, and therefore the behaviour of the code under test (think customer_should_have_balance_updated_by_input_order_amount()<\/code> rather than verifyOrderMethod()<\/code>). It allows us to create tests which are not brittle – if a test does too much it may break if unrelated functionality is changed, forcing us to rewrite the test just to get it working again without changing the actual code under test.<\/p>\n
If we adopt the \u2018test one thing\u2019 habit we will be writing much better unit tests into the future!<\/p>\n
<\/a>2. Including Hamcrest<\/h2>\n
If you are using Maven you can add Hamcrest to your project with the following dependency to your pom.xml<\/p>\n
\n<dependency>\n  \t<groupId>org.hamcrest<\/groupId>\n  \t<artifactId>hamcrest-all<\/artifactId>\n  \t<version>1.3<\/version>\n  <\/dependency>\n<\/pre>\n
If you are using Gradle add the following<\/p>\n
\ndependencies {\n    testCompile \"org.hamcrest:hamcrest-all:1.3\"\n  }\n<\/pre>\n
To add hamcrest directly to the classpath of your project you can download hamcrest-all-1.3.jar from https:\/\/code.google.com\/p\/hamcrest\/ to a location on your hard drive.<\/p>\n
Right click on your eclipse project and select \u2018Properties\u2019 and then select \u2018Java Build Path\u2019 in the left pane and \u2018Libraries\u2019 on the right.<\/p>\n
On the \u2018Libraries\u2019 tab click the \u2018Add External Jars\u2019 button and navigate to the hamcrest-all jar you previously downloaded.  Select the jar and it is now added to your project and available to use.<\/p>\n
Note that JUnit gets bundled with a stripped down version of Hamcrest (Hamcrest Core) so your compiler will pick up that version if JUnit appears before Hamcrest on the classpath. To counteract this please ensure Hamcrest appears before JUnit on the classpath.  You can achieve this in Maven by listing the hamcrest-all dependency before all other dependencies.<\/p>\n
As with the Mockito static methods we can add the Hamcrest library to Eclipse content assist by launching Window -> Preferences and go to Java\/Editor\/Content Assist\/Favorites in the left nav.  After that add the following as \u201cNew Type\u2026” as per Figure 1<\/p>\n