Introduction to Hamcrest Collection Matchers

Another post in the series of Hamcrest Matchers, a framework for writing test matcher objects. This week we’ll dive into collections and iterables, and we’ll see how we can use Hamcrest for making those asserts even more readable.

In many software projects I encounter code like the following:

Or, even worse:

The second loses context by not knowning the expected value and the actual value; it knows only that they are not equal.

So, while this above might be a valid asserts, their readability and error feedback can be improved by using a framework like Hamcrest. This can be done in the following way:

In my opinion, this increases readability quite a bit, and makes it easier to maintain tests like this. Check the following piece of code for more examples:

Error messages

Whenever a assertion fails, you get a pretty clear error message, which will help you quickly solve issues you run into. For example, if in the above code example I would have made a wrong assumption, and instead of:

If would have typed:

The following error message would have shown up:

Whereas the the JUnit equivalent:

Would have resulted in the following:

Which would have helped a great deal also, but it’s just that the Hamcrest one is a bit more clear, and a bit more elaborate on the error message.

I hope this helps in picking up Hamcrest and that it helps in writing clear, consistent tests. See you next week!

Introduction to Hamcrest String Matchers

Another week, another blogpost. For those catching on just now, or finding this post using a search engine; I’m writing a series of posts about Hamcrest, a framework for writing test matcher objects, and showing you how to use Hamcrest. While the previous post was about the Core Matchers, the topic of this week is Hamcrest String Matchers.

The Hamcrest String Matchers are the following:
containsString, startsWith, endsWith, equalToIgnoringCase, equalToIgnoringWhitespace, isEmpty, isEmptyOrNull and stringContainsInOrder

Also in this post, I will give an example of all of them in the code block below:

Again, the Hamcrest assertions are very clear, and makes your testcode a easier to read an maintain. Enjoy!

Introduction to Hamcrest Core Matchers

In our previous post, we got a small introduction into Hamcrest, a framework for writing test matcher objects, and why you should use them. This post will dive deeper into Hamcrest Matchers. A Matcher is a ‘match’ rule to be defined declaratively. The Hamcrest library comes with numerous matchers included, and it’s of course possible to write your own Matcher.

The topic of this week: the Core Matchers.

The common Matchers of Hamcrest are the following:
is, equalTo, not, anything, instanceOf, any, isA, nullValue, notNullValue, sameInstance, theInstance, isIn, isOneOf and hasToString.

I will give an example of all of them in the code block below:

As you can see, the Hamcrest assertions are very readable, and makes your testcode a bit easier to maintain.

PS: I always wanted to write some posts about Hamcrest, but the thing which really triggered me was the Hamcrest cheat sheet created by Marc Philipp. Be sure to check it out, it’s a great piece of work!

Hamcrest Matchers in JUnit tests

With JUnit being the dominant Test framework, chances are high that during your career as a software engineer, you’ve encountered the JUnit framework in one or more projects. Therefor, code like this:

Should not be unfamiliar to you. This blogpost is on improving the example above. There are good alternatives in writing your tests, like Spock, but these take a little more effort to setup, since it’s mostly used in Groovy projects. The goal of this blogpost is to improve the above Java test with little effort, and for that, we’re going to use Hamcrest.

Hamcrest is (in our case) a set of Java matchers which improve the readability of the code and error messages shown when assertions do not match. So, let’s get back to our original example: what does it really say?

Means something like: verify that the getValue method of result should return the String hello, and if not, print the message ‘result doesn’t match hello’. Wouldn’t it be more understandable if we could write something like this in a more natural language? Well, with Hamcrest we can:

In this example, we’re using ‘assertThat’, which is a method coming from JUnit. JUnit itself supports a random amount of Matchers, but I would recommend on forgetting those, and just use only the Matchers from Hamcrest itself (which means, adding the Hamcrest library to the project, version 1.3 at this moment), since the Hamcrest library contains a much bigger set of Matchers. Also, note that the ‘is’ method here is optional, but I added it to improve readability.

Hamcrest can be added to your Maven project by including the following dependency:

And using this library, you’ll get many matchers, supporting String, Collections, Maps, Numbers, and even XML elements, but more on that in my next blog!

One last note: be aware to use the latests version of JUnit though (currently 4.11). When using an older version you might (read: will) run into dependency issues. Don’t say I didn’t warn you!

Testing Command Objects in Grails 2.0

In Grails 2.0, you need to use mockCommandObject to test command objects. However, what the Grails documentation doesn’t mention is how to use the mockCommandObject method. The mockCommandObject method is located in the ControllerUnitTestMixin. To use the method, you can use the following example:

This is a little inconvenient if your class needs a lot of properties. To make things a little easier, you can mock the command object in the setup method (using JUnit’s @Before annotation), and use the default constructor (with Map support), as you would normally:

Friday Repost: Groovy Test Data Builder Pattern

The Friday Repost series are copies from my earlier writings. Since I don’t want to loose them, and they might prove useful to others, I’m reposting them on this blog

Most of us value the quality of our code highly. I do, and I expect you, as a reader, also to care for the quality of your code. Because of that, we write tests. Test which usually contain of 3 parts: the setup, the execution and the verification. And sometimes some cleanup. In this blog, I’d like to focus on the setup part, and try to get rid of some boilerplate code which can easily clutter our tests!

As I mentioned before, we usually write some setup code which serves as input for our test. This code can look like this:

Writing this code can be time consuming, plus the code doesn’t reveal the intention of the test. What are the significant bits in this setup code? Is it the age? Is it my name? Or a combination?

To solve the creation of testdata, there are multiple patterns. On of those patterns is the Test Data Builder pattern. The idea behind the Test Data Builder pattern is that test data should be easily to construct, which is usually accomplished by chaining method calls (also called a Fluent Interface, or a Builder).

I’ve taken the concept to Groovy and made an TestDataBuilder Category. A Groovy Category adds functionality to your code within a limited scope (defined by the ‘use’ keyword). This enables the object which is used in the setup of the test to ‘borrow’ the method of the TestDataBuilder Groovy class, which allows it to construct itself with testdata. This is best demonstrated by the use of an example:

By placing the creation of the data in the scope of the Category, the .build() method becomes available in for the Person class. Calling the build method will instantiate the Person class and populate all the fields with values which all equal true. So numbers will become 1, booleans true, Strings will get the name of the variable as a value, etc.

To use this in tests, and make the code more intention revealing, we can choose to populate some fields with our own values, and have the rest be generated.

The benefits of this is that you save a lot of setup code, and make the code a lot more clear and maintainable. If you want to use this, the code can be found on (This class was previously called the ObjectMother, an error on my side. The change in name isn’t reflected yet in GitHub). Yes, there are some limitations, like it doesn’t handly all standard datatypes yet (like dates), nor does it populate associations (list with other objects) yet. Have fun, and any feedback on the code would be highly valued!

Friday Repost: Remove Groovy MetaClass methods

The Friday Repost series are copies from my earlier writings. Since I don’t want to loose them, and they might prove useful to others, I’m reposting them on this blog

Whenever you are using metaclasses in Groovy or Grails unit tests, you might use Groovy’s metaClass power to mock the behavior of methods. However, Grails doesn’t fork the JVM for each test, so a nice side effect of this is that the mocked method will be available for the complete lifetime of the VM. Since Grails first executes unit tests (the test which usually contain the mocked code), and then followed by the integration tests, these tests can fail because you are maybe still using a mocked version of the method instead of the real one! This can often happen when mocking Grails methods, like dynamic finders, or named queries. The trick is to clean up these methods.

This is done by registering the metaClass when extending GrailsUnitTestCase. You’ll have to call the registerMetaClass(clazz) method, which does the following internally:

You can use this code in your tests in the following way, for example in the UserTests.groovy:

This way, the User class is registered with Grails to be cleaned up afterwards. This is done automatically in the teardown of the test, so you’re sure that no custom defined methods are available after running the test.

So, beware that whenever you use Groovy’s meta magic, be also sure to clean it up afterwards, since it might affect other parts of the code. You can check out my other blog post for a good solution to not forget the cleanup part!

This (two) week(s) in Discobot (30-31.2011)

Each week, we work on the Discobot project, which goal it is to make Groovy run on Android. While that in itself isn’t the biggest problem, as you can read in our previous blog posts, making developing for Android using Groovy and making sure we are feature complete, well, let’s say it’s challenging.

Current efforts are twofold: one is developing a set of developer tools using Gradle, on which Marcin is focusing the most. On the other hand, we need some tools to make sure our version of Groovy works on Android, which is what I (Erik) am focusing on.


As you can see in the screenshot above, our project is already capable of building the project and installing it on the emulator using the Gradle plugin. Also, the start of a demo application has been built, which will allow us to run all the tests packed with Groovy. For that, we have tweaked the build process of Groovy itself, so that it produces a jar which includes all the tests. This jar is used in the Discobot project. To figure out which tests are available, an Android Classpath Scanner is used. It uses a hack by inspecting the Dex files itself, but we are currently using that to scan for files which extend from GroovyTestCase, and run those. Once that is working, we’ll probably write a better UI around it.

Also, the Gradle plugin still needs some finishing touches to improve the overall user experience. Marcin is currently working on the last gradle task which will initialize the android project structure. It will call the android create project command-line tool from Android SDK, change the src directory structure of your project to obey Gradle conventions and create a ‘Hello World’ activity written in Groovy, so you can quickly get a simple working application to start out with!

We’ll try to update you again with more information next week!

Testing Grails controller actions that use bindData method and render validation errors as JSON

Let’s assume that we have a controller action in a grails application that updates a user domain instance. We want name and surname to be updateable but login and password shouldn’t be updateble. To achieve that we will use the controller’s bindData() method with whitelisting. The action will be called using ajax so we also want to render JSON with validation errors in response if there were any. So our controller might look like that:

And the example User class might look like that:

Our next step will be unit testing the action. We want to make sure that only the whitelisted fields are copied from parameters (testUpdate) and also that the validation errors are rendered (testUpdateValidationError):

It turns out that those tests won’t pass. But not because of the fact that we have bugs in the code, it’s just that grails doesn’t do enough magic for our controller action to be unit testable out of the box.

First problem is that the bindData() method is not mocked in ControllerUnitTestCase. Fortunately thanks to this stackoverflow response we know how to easily mock it. To make it reusable let’s create a mixin out of it:

Now all that we have to do to make it work is to apply it on our test class and call the mockBindData() method in the setUp() method.

Second problem is that by default the JSON converter doesn’t know how to convert bean validation errors. But that’s easily fixable as well – all we have to do is register validation error marshaller in the testUpdateValidationError test:

After the aforementioned changes our passing test class should look like that:

Groovy MetaClass Magic in Unit Tests

As you may or may not know, Groovy has the concept of MetaClasses. MetaClasses enable you to add or change methods at runtime. This is especially handy when doing some mocking during a unit test (or, in our case, GrailsUnitTestCases). By mocking methods, you can mock out certain dependencies or behavior which you might not want during a unit test. An example:

In this case, if you want to test the logic of the PersonAdapter without using the complex operations in the service, on way to test this by using some MetaClass magic, as can be seen below:

While this might be not be the optimal example or test (you might consider using Mocks instead), there’s a flaw in this test. Since the complexOperation is now metaClassed on the class level, instead of on the object, it means that future tests will also be affected, including Integration tests. This might lead to some very unexpected behaviors, which are sometimes hard to track down.

There are two ways to ‘fix’ this:

  1. Always call the super.tearDown() in tests. This will reset the Groovy meta registry to it’s normal state. However, you need to explicitly call ‘registerMetaClass’ in tests to allow Grails to clean this up. If you forget this, you’re metaClass change can affect other tests too. To prevent that, we have option 2.
  2. Use the MetaClassMixin.

The MetaClassMixin is a simple class we use in our project to automatically register metaClasses in the GroovySystem’s MetaClassRegistery. Since we are using only the MetaClassMixin to do metaclass magic instead of doing it directly on classes, we can never forget to register the class anymore. This has saved us in many cases. An example usage can be seen below:

Using the MetaClassMixin, you no long have to worry about registering your MetaClassed classes, or, more importantly forgetting to register them! Below, you can find the source of the MetaClassMixin (this mixin has been written by Levi Hoogenberg, so credits for that!). Feedback on this welcome of course!

Happy metaClassing!