Unit Testing Grails Custom Taglibs

I built out the initial iteration of my photography website a couple months ago, and I've been coming back to it recently to put some enhancements into place. I really must get the photography blog up and running, but until then, I poke around at doing the simpler things -- like a convenient copyright taglib.

I beat people at work over the head with TDD all the time, so I obviously want to follow my own example. I started out searching around a bit on unit testing custom taglibs in a Grails project. I didn't come up with much, and what I did find wasn't really exercising the parameters that come into a taglib closure.

Let's start out asking Grails to create a shell of a taglib for me in the conventional locations:

% grails create-tag-lib copyright

Now I have a shiny new test/unit/CopyrightTagLibTests.groovy and a grails-app/taglib/CopyrightTagLib.groovy, and they're empty.

I want to be able to use it like this in my GSP:

<g:copyright startYear = "2009">John Flinchbaugh</g:copyright>

I'll be giving it a start year, it should use the current year as the end year, and the body is the name to whom it should attribute copyright. If the current year and the startYear match, then it should display only one. Let's get that down in the unit test. Fortunately, the tag name used in the GSP is just the name of a closure in the taglib.

Taglibs take a map of attibutes and a closure for the body of the tag, and they render their output to the out property. My first assumption says we should see the current year only and the body text when no tag attributes are specified (empty map). I cheat a little and just derive the current year in the test to form my expectation instead of trying to inject the current date.

    void testCopyrightNoStart() {
        tagLib.copyright([:]) { "xyz" }
        def expectedDate = Calendar.getInstance().get(Calendar.YEAR)
        assertEquals("Copyright ${expectedDate} xyz", tagLib.out.toString())
    }

Next, I assume if the startYear is specified and it matches the current year, it'll only display one year, and not a range. Make special note, the value of the startYear attribute being passed into the copyright method is a String. When taglibs are called by the GSP engine, they will pass in String values, so do yourself the favor and make sure you're doing that here.

    void testCopyrightStartThisYear() {
        def expectedDate = Calendar.getInstance().get(Calendar.YEAR)
        tagLib.copyright(
            startYear: "${expectedDate}") { "xyz" }
        assertEquals("Copyright ${expectedDate} xyz", tagLib.out.toString())
    }

I do a little math for the test of the full functionality and pass in last year for the startYear and demonstrate the taglib in all its glory -- showing a range of years.

    void testCopyrightStartLastYear() {
        def expectedDate = Calendar.getInstance().get(Calendar.YEAR)
        tagLib.copyright(startYear: "${expectedDate - 1}") { "xyz" }
        assertEquals("Copyright ${expectedDate - 1} - ${expectedDate} xyz",
                tagLib.out.toString())
    }

I like to nail down expectations about what would be misuses as well, so I'm going to say that a bad startDate will still run fine, and it'll just be shown in the output of the taglib.

    void testCopyrightBadStart() {
        def expectedDate = Calendar.getInstance().get(Calendar.YEAR)
        tagLib.copyright(startYear: "badYear") { "xyz" }
        assertEquals("Copyright badYear - ${expectedDate} xyz", tagLib.out.toString())
    }

Now that I have all my tests done up front, let's run grails test-app to see what we have! All my shiny new tests fail spectacularly, because I've not written the taglib yet, so let's go write enough of this new copyright closure on the CopyrightTaglib to get these tests to pass.

I address one test at at time, starting with just giving myself an empty closure assigned to copyright, and adding and modifying bits of the taglib code until it passes all my tests. That's how I know I've done everything I wanted and nothing unnecessary.

class CopyrightTagLib {
    def copyright = { attrs, body ->
        def thisYear = Calendar.getInstance().get(Calendar.YEAR) as String
        def startYear = attrs.startYear ?: thisYear
        out << "Copyright"

        if (thisYear != startYear) {
            out << " ${startYear} -"
        }

        out << " ${thisYear} ${body()}"
    }
}

And there it is, some simple taglib code which satisfies my every expectation as laid down in the tests. The last thing to do, is go add my shiny new taglib to my footer.gsp and I'm done. The code for the test and taglib are available in their entirety here: copyright.zip.