First8 staat voor vakmanschap. Al onze collega’s zijn een groot aanhanger van Open Source en in het bijzonder het Java-platform. Wij zijn gespecialiseerd in het pragmatisch ontwikkelen van bedrijfskritische Java toepassingen waarbij integratie van systemen, hoge eisen aan beveiliging en veel transacties een belangrijke rol spelen. Op deze pagina vind je onze blogs.

So If You’re Using Tag Libraries for Your View Models You Have To Test Them, Right?

In a previous post I introduced thinking about (visual) components and used a Task Browser as an example of an user interface “component” .


I explained that using

  • View Model(s) e.g. plain-old Groovy objects (POGOs) holding the related data e.g. a class TaskBrowser
  • Tag Libraries (LayoutTagLib) and tags (def taskBrowser) to render the associated HTML (views/layouts/components/_taskBrowser.gsp) to the page

allows for more maintainable and testable code.

Let’s put our money where our mouth is and see how one could test the used tag library.

The Parts

So these are the (simplified) parts in the equation.

Task – The domain class

TaskBrowser – Just a POGO with the data

HomeController – Creating the Task Browser in an index action

home/index.gsp – The GSP for the index action

views/layouts/components/_taskBrowser.gsp – The Task Browser HTML

LayoutTagLib – Finally, the tag library

Unit Test

If you look at the tag library code there’s a few things interesting enough to cover with an unit test.

Normally whenever you use a Grails command to create a controller, service or tag library, also an associated unit test is created. If not, you can always create one later on with

In any case, we start with a LayoutTagLibSpec which is initially pretty empty.

The @TestFor annotation is part of the Grails framework. It not only indicates the class-under-test (aka the actual unit we’re supposed to be testing here), but also gives us a concrete instance of that class. More on that later.

Now we can implement our first test, called…

Task browser tag should show all tasks by default

Although the skeleton testmethod "test something" starts with “test…”, I try to omit that part. We’re a creating tests obviously and repeating “test xxx” up front has no additional value but taking up space.

If we were in the unit test of the TaskBrowser (e.g. TaskBrowserSpec) I would skip the name of the class-under-test from the testmethod e.g. “task browser tag should show…”. Since we’re in a more generic LayoutTagLib I would like to know which tag – of many more to come ofcourse – we’re talking about, so I do start with “task browser tag…”

I usually start by placing my Given/When/Then Spock labels in the test method. This helps me structure my own head in thinking about

  1. What are the prequisites? (Given)
  2. What’s the actual code to invoke? (When)
  3. What’s there to assert or verify? (Then)

Here’s what I have now:

The actual invocation of the tag goes under When.

Since the @TestFor annotation points to a tag library class, we’re given an implicit tagLib variable to work which references a clean LayoutTagLib instance each time.

Don’t do this in a unit test, because it’s the preTestFor way:

but use the tagLib, Luke.

So we have this:

I know that the happy-path flow for this test needs a TaskBrowser instance. There should be al least one task to verify the tag should show it by default. So let’s add them:

Hey, why is true there in the Then block? It’s because we need to have a Then block after When, to be able to execute this test once at this moment. Normally we would write this probably with Expect as

but I’m too lazy to update it to Expect and change it back later to When/Then 😉 We need the Then later on anyway.

What Grails does in a unit test for a tag library is actually rendering the template /layouts/components/_taskBrowser.gsp using the supplied model.

Remember the code for the LayoutTagLib?

If above (simplistic) test succeeds, the _taskBrowser.gsp — and its logic — hasn’t failed with an exception. You can make a typo in your template(s) and see the evaluation fail. Covering just the evaluation of a GSP might be worth a test, but we haven’t checked anything of the contents.

How do we know if the correct template is referenced? How do we know if the correct model is actually passed along?

The Inevitable Truth

If you look at the Testing chapter of the Grails documentation, you’ll see a simplistic example of testing the response of a SimpleTagLib

Our tag isn’t as simple as returning “Hello World” – our tag renders 500 lines of Sophisticated Task Browser HTML to the output buffer. Verifying this the simple way isn’t that simple.

There are a few approaches here.

#1 – Checking for parts

Often contains is used in pieces of code which simply need to be checked for the presence of an item. We could try to verify the existence of our single task “My task” somewhere in the output like this:

We have verified successfully that “My task” is visible somewhere in 500 lines of output.

(Psst, quickly beef up the test before we continue – make sure we always have at least a multiple amount of test items to check logic which deals with a collection, instead of a single item)

The disadvantage is that we’ve coupled our test for the tag lib logic (showing or filtering tasks) with the rendering of the HTML (presence of the title of a task)

To alleviate this a bit we should be…

#2 – Controlling what parts are rendered

Just as with Controller tests we can use a feature of the ControllerUnitTestMixin to mock the view used for rendering.

Use the implicit getViews() or getGroovyPages() — which return a Map for us to manipulate. Overwrite the real template with custom content of our own, in which we control what & how the model is rendered.

First make sure we actually overwrite the correct template path, by letting the test fail. The taskBrowser tag says render(template: '/layouts/components/taskBrowser'... so we have to put alternative contents under key '/layouts/components/_taskBrowser.gsp' — there’s a discrepancy in the format of writing the template path.

This fails correctly…

…so we know we have the correct key.

Now choose proper contents.

Just printing the collection of tasks should give us all we need to verify that our 2 tasks have been passed to the model to our custom template now.


We can (and should) not rely on the String-representation of a Task class, our model.

Now don’t go adding a toString() method! We could adjust the test to detect the presence of the correct items by a unique property e.g. the title.

This succeeds!

And is ugly. We’re still relying on coercing the result from the rendering (StreamCharBuffer) to a String which need to be compared as a whole with something we expect or checked for parts. For testing some small HTML snippets this is fine though.

There are a few tips and tricks I’ll share in a future post as the model becomes too complex to test through this mechanism. For now we’ll be flying with this mechanism.

Task browser

I often take the first, simple test as a basis for further tests. In a 2nd test we need to verify if the task browser can actually filter for once on task types, such as Personal or Work.

Introduced a filter by passing along a filter attribute to the tag. The resulting test could look like the following. We’re checking that only one task which has that type is rendered, and not the other.

(Normally, I would have supplied all kinds of labels to the given:, when: etc. blocks, but I’ll leave that as an exercise for the reader.)

If I weren’t too tired of spending a weekend with Romans and gladiators I would have written some more variations and a concluding part, but I hope just writing above down here on the First8 blog (crossposted from my personal blog) will be of some help to someone.

Happy testing!