# 9. Testing

Automated testing is seen as a key part of Grails, implemented using Groovy Tests. Hence, Grails provides many ways to making testing easier from low level unit testing to high level functional tests. This section details the different capabilities that Grails offers in terms of testing.

The first thing to be aware of is that all of the `create-*` commands actually end up creating `integration` tests automatically for you. For example say you run the create-controller command as follows:

    grails create-controller simple

Not only will Grails create a controller at `grails-app/controllers/SimpleController.groovy`, but also an integration test at `test/integration/SimpleControllerTests.groovy`. What Grails won't do however is populate the logic inside the test! That is left up to you.

#### Running Tests

Test are run with the test-app command:

    grails test-app

The above command will produce output such as:

    -------------------------------------------------------
    Running Unit Tests…
    Running test FooTests...FAILURE
    Unit Tests Completed in 464ms …
    -------------------------------------------------------Tests failed: 0 errors, 1 failures

Whilst reports will have been written out the `target/test-reports` directory.

> You can force a clean before running tests by passing `-clean` to the `test-app` command.

##### Targeting Tests

You can selectively target the test(s) to be run in different ways. To run all tests for a controller named `SimpleController` you would run:

    grails test-app SimpleController

This will run any tests for the class named `SimpleController`. Wildcards can be used...

    grails test-app *Controller

This will test all classes ending in `Controller`. Package names can optionally be specified...

    grails test-app some.org.*Controller

or to run all tests in a package...

    grails test-app some.org.*

or to run all tests in a package including subpackages...

    grails test-app some.org.**

You can also target particular test methods...

    grails test-app SimpleController.testLogin

This will run the `testLogin` test in the `SimpleController` tests. You can specify as many patterns in combination as you like...

    grails test-app some.org.* SimpleController.testLogin BookController

##### Targeting Test Types and/or Phases

In addition to targeting certain tests, you can also target test types and/or phases by using the `phase:type` syntax.

> Grails organises tests by phase and by type. A test phase relates to the state of the Grails application during the tests, and the type relates to the testing mechanism.

> Grails comes with support for 4 test phases (`unit`, `integration`, `functional` and `other`) and JUnit test types for the `unit` and `integration` phases. These test types have the same name as the phase.

> Testing plugins may provide new test phases or new test types for existing phases. Refer to the plugin documentation.

To execute the JUnit `integration` tests you can run:

    grails test-app integration:integration

Both `phase` and `type` are optional. Their absence acts as a wildcard. The following command will run all test types in the `unit` phase:

    grails test-app unit:

The Grails Spock Plugin is one plugin that adds new test types to Grails. It adds a `spock` test type to the `unit`, `integration` and `functional` phases. To run all spock tests in all phases you would run the following:

    grails test-app :spock

To run the all of the spock tests in the `functional` phase you would run...

    grails test-app functional:spock

More than one pattern can be specified...

    grails test-app unit:spock integration:spock

##### Targeting Tests in Types and/or Phases

Test and type/phase targetting can be applied at the same time:

    grails test-app integration: unit: some.org.**

This would run all tests in the `integration` and `unit` phases that are in the page `some.org` or a subpackage of.

## 9.1 Unit Testing

Unit testing are tests at the "unit" level. In other words you are testing individual methods or blocks of code without considering for surrounding infrastructure. In Grails you need to be particularity aware of the difference between unit and integration tests because in unit tests Grails does not inject any of the dynamic methods present during integration tests and at runtime.

This makes sense if you consider that the methods injected by Grails typically communicate with the database (with GORM) or the underlying Servlet engine (with Controllers). For example say you have service like the following in `BookController`:

    class MyService {
        def otherService	String createSomething() {
    		def stringId = otherService.newIdentifier()
    		def item = new Item(code: stringId, name: "Bangle")
    		item.save()
    		return stringId
    	}	int countItems(String name) {
    		def items = Item.findAllByName(name)
    		return items.size()
    	}
    }

As you can see the service takes advantage of GORM methods. So how do you go about testing the above code in a unit test? The answer can be found in Grails' testing support classes.

### The Testing Framework

The core of the testing plugin is the `grails.test.GrailsUnitTestCase` class. This is a sub-class of `GroovyTestCase` geared towards Grails applications and their artifacts. It provides several methods for mocking particular types as well as support for general mocking a la Groovy's MockFor and StubFor classes.

Normally you might look at the `MyService` example shown previously and the dependency on another service and the use of dynamic domain class methods with a bit of a groan. You can use meta-class programming and the "map as object" idiom, but these can quickly get ugly. How might we write the test with GrailsUnitTestCase ?

    import grails.test.GrailsUnitTestCaseclass MyServiceTests extends GrailsUnitTestCase {
    	void testCreateSomething() {
    		// Mock the domain class.
    		mockDomain(Item)		// Mock the "other" service.
    		String testId = "NH-12347686"
    		def otherControl = mockFor(OtherService)
    		otherControl.demand.newIdentifier(1..1) {-> return testId }		// 	Initialise the service and test the target method.
    		def testService = new MyService()
    		testService.otherService = otherControl.createMock()		def retval = testService.createSomething()		// Check that the method returns the identifier returned by the
    		// mock "other" service and also that a new Item instance has
    		// been saved.
    		def testInstances = Item.list()
    		assertEquals testId, retval
    		assertEquals 1, testInstances.size()
    		assertTrue testInstances[0] instanceof Item
    	}	void testCountItems() {
    		// Mock the domain class, this time providing a list of test
    		// Item instances that can be searched.
    		def testInstances = [ new Item(code: "NH-4273997", name: "Laptop"),
    							  new Item(code: "EC-4395734", name: "Lamp"),
    							  new Item(code: "TF-4927324", name: "Laptop") ]
    		mockDomain(Item, testInstances)		// Initialise the service and test the target method. def testService = new MyService()		assertEquals 2, testService.countItems("Laptop")
    		assertEquals 1, testService.countItems("Lamp")
    		assertEquals 0, testService.countItems("Chair")
    	}
    }

OK, so a fair bit of new stuff there, but once we break it down you should quickly see how easy it is to use the methods available to you. Take a look at the "testCreateSomething()" test method. The first thing you will probably notice is the `mockDomain()` method, which is one of several provided by `GrailsUnitTestCase`:

    def testInstances = []
    mockDomain(Item, testInstances)

It adds all the common domain methods (both instance and static) to the given class so that any code using it sees it as a full-blown domain class. So for example, once the `Item` class has been mocked, we can safely call the `save()` method on instances of it. Invoking the `save()` method doesn't really save the instance to any database but it will cache the object in the testing framework so the instance will be visible to certain queries. The following code snippet demonstrates the effect of calling the `save()` method.

    void testSomething() {
        def testInstances=[]
        mockDomain(Song, testInstances)
        assertEquals(0, Song.count())
        new Song(name:"Supper's Ready").save()
        assertEquals(1, Song.count())
    }

The next bit we want to look at is centered on the `mockFor` method:

    def otherControl = mockFor(OtherService)
    otherControl.demand.newIdentifier(1..1) {-> return testId }

This is analagous to the `MockFor` and `StubFor` classes that come with Groovy and it can be used to mock any class you want. In fact, the "demand" syntax is identical to that used by Mock/StubFor, so you should feel right at home. Of course you often need to inject a mock instance as a dependency, but that is pretty straight forward with the `createMock()` method, which you simply call on the mock control as shown. For those familiar with EasyMock, the name `otherControl` highlights the role of the object returned by `mockFor()` - it is a control object rather than the mock itself.

The rest of the `testCreateSomething()` method should be pretty familiar, particularly as you now know that the mock `save()` method adds instances to `testInstances` list. However, there is an important technique missing from the test method. We can determine that the mock `newIdentifier()` method is called because its return value has a direct impact on the result of the `createSomething()` method. But what if that weren't the case? How would we know whether it had been called or not? With Mock/StubFor the check would be performed at the end of the `use()` closure, but that's not available here. Instead, you can call `verify()` on the control object - in this case `otherControl`. This will perform the check and throw an assertion error if it hasn't been called when it should have been.

Lastly, `testCountItems()` in the example demonstrates another facet of the `mockDomain()` method:

    def testInstances = [ new Item(code: "NH-4273997", name: "Laptop"),
    					  new Item(code: "EC-4395734", name: "Lamp"),
    					  new Item(code: "TF-4927324", name: "Laptop") ]
    mockDomain(Item, testInstances)

It is normally quite fiddly to mock the dynamic finders manually, and you often have to set up different data sets for each invocation. On top of that, if you decide a different finder should be used then you have to update the tests to check for the new method! Thankfully the `mockDomain()` method provides a lightweight implementation of the dynamic finders backed by a list of domain instances. Simply provide the test data as the second argument of the method and the mock finders will just work.

### GrailsUnitTestCase - the mock methods

You have already seen a couple of examples in the introduction of the `mock..()` methods provided by the `GrailsUnitTestCase` class. Here we will look at all the available methods in some detail, starting with the all-purpose `mockFor()`. But before we do, there is a very important point to make: using these methods ensures that any changes you make to the given classes do not leak into other tests! This is a common and serious problem when you try to perform the mocking yourself via meta-class programming, but that headache just disappears as long as you use at least one of `mock..()` methods on each class you want to mock.

    mockFor(class, loose = false)

General purpose mocking that allows you to set up either strict or loose demands on a class.

This method is surprisingly intuitive to use. By default it will create a strict mock control object (one for which the order in which methods are called is important) that you can use to specify demands:

    def strictControl = mockFor(MyService)
    strictControl.demand.someMethod(0..2) { String arg1, int arg2 -> … }
    strictControl.demand.static.aStaticMethod {-> … }

Notice that you can mock static methods as well as instance ones simply by using the "static" property after "demand". You then specify the name of the method that you want to mock with an optional range as its argument. This range determines how many times you expect the method to be called, so if the number of invocations falls outside of that range (either too few or too many) then an assertion error will be thrown. If no range is specified, a default of "1..1" is assumed, i.e. that the method must be called exactly once.

The last part of a demand is a closure representing the implementation of the mock method. The closure arguments should match the number and types of the mocked method, but otherwise you are free to add whatever you want in the body.

As we mentioned before, if you want an actual mock instance of the class that you are mocking, then you need to call `mockControl.createMock()`. In fact, you can call this as many times as you like to create as many mock instances as you need. And once you have executed the test method, you can call `mockControl.verify()` to check whether the expected methods were actually called or not.

Lastly, the call:

    def looseControl = mockFor(MyService, true)

will create a mock control object that has only loose expectations, i.e. the order that methods are invoked does not matter.

#### mockDomain(class, testInstances = )

Takes a class and makes mock implementations of all the domain class methods (both instance- and static-level) accessible on it.

Mocking domain classes is one of the big wins from using the testing plugin. Manually doing it is fiddly at best, so it's great that mockDomain() takes that burden off your shoulders.

In effect, `mockDomain()` provides a lightweight version of domain classes in which the "database" is simply a list of domain instances held in memory. All the mocked methods ( `save()` , `get()` , `findBy*()` , etc.) work against that list, generally behaving as you would expect them to. In addition to that, both the mocked `save()` and validate() methods will perform real validation (support for the unique constraint included!) and populate an errors object on the corresponding domain instance.

There isn't much else to say other than that the plugin does not support the mocking of criteria or HQL queries. If you use either of those, simply mock the corresponding methods manually (for example with `mockFor()` ) or use an integration test with real data.

#### mockForConstraintsTests(class, testInstances = )

Highly specialised mocking for domain classes and command objects that allows you to check whether the constraints are behaving as you expect them to.

Do you test your domain constraints? If not, why not? If your answer is that they don't need testing, think again. Your constraints contain logic and that logic is highly susceptible to bugs - the kind of bugs that can be tricky to track down (particularly as save() doesn't throw an exception when it fails). If your answer is that it's too hard or fiddly, that is no longer an excuse. Enter the `mockForConstraintsTests()` method.

This is like a much reduced version of the `mockDomain()` method that simply adds a `validate()` method to a given domain class. All you have to do is mock the class, create an instance with field values, and then call `validate()`. You can then access the errors property on your domain instance to find out whether the validation failed or not. So if all we are doing is mocking the `validate()` method, why the optional list of test instances? That is so that we can test unique constraints as you will soon see.

So, suppose we have a simple domain class like so:

    class Book {
        String title
        String author	static constraints = {
    		title(blank: false, unique: true)
    		author(blank: false, minSize: 5)
    	}
    }

Don't worry about whether the constraints are sensible or not (they're not!), they are for demonstration only. To test these constraints we can do the following:

    class BookTests extends GrailsUnitTestCase {
        void testConstraints() {
            def existingBook = new Book(title: "Misery", author: "Stephen King")
            mockForConstraintsTests(Book, [ existingBook ])		// Validation should fail if both properties are null.
    		def book = new Book()
    		assertFalse book.validate()
    		assertEquals "nullable", book.errors["title"]
    		assertEquals "nullable", book.errors["author"]		// So let's demonstrate the unique and minSize constraints.
    		book = new Book(title: "Misery", author: "JK")
    		assertFalse book.validate()
    		assertEquals "unique", 	book.errors["title"]
    		assertEquals "minSize", book.errors["author"]		// Validation should pass!
    		book = new Book(title: "The Shining", author: "Stephen King")
    		assertTrue book.validate()
    	}
    }

You can probably look at that code and work out what's happening without any further explanation. The one thing we will explain is the way the errors property is used. First, it does return a real Spring `Errors` instance, so you can access all the properties and methods you would normally expect. Second, this particular `Errors` object also has map/property access as shown. Simply specify the name of the field you are interested in and the map/property access will return the name of the constraint that was violated. Note that it is the constraint name , not the message code (as you might expect).

That's it for testing constraints. One final thing we would like to say is that testing the constraints in this way catches a common error: typos in the "constraints" property! It is currently one of the hardest bugs to track down normally, and yet a unit test for your constraints will highlight the problem straight away.

#### mockLogging(class, enableDebug = false)

Adds a mock "log" property to a class. Any messages passed to the mock logger are echoed to the console.

#### mockController(class)

Adds mock versions of the dynamic controller properties and methods to the given class. This is typically used in conjunction with the `ControllerUnitTestCase` class.

#### mockTagLib(class)

Adds mock versions of the dynamic taglib properties and methods to the given class. This is typically used in conjunction with the `TagLibUnitTestCase` class.

## 9.2 Integration Testing

Integration tests differ from unit tests in that you have full access to the Grails environment within the test. Grails will use an in-memory HSQLDB database for integration tests and clear out all the data from the database in between each test.

#### Testing Controllers

To test controllers you first have to understand the Spring Mock Library

Essentially Grails automatically configures each test with a MockHttpServletRequest, MockHttpServletResponse, and MockHttpSession which you can then use to perform your tests. For example consider the following controller:

    class FooController {	def text = {
    	    render "bar"
    	}	def someRedirect = {
    		redirect(action:"bar")
    	}
    }

The tests for this would be:

    class FooControllerTests extends GroovyTestCase {  void testText() {
    		def fc = new FooController()
    		fc.text()
    		assertEquals "bar", fc.response.contentAsString
    	}	void testSomeRedirect() {		def fc = new FooController()
    		fc.someRedirect()
    		assertEquals "/foo/bar", fc.response.redirectedUrl
    	}
    }

In the above case the response is an instance of `MockHttpServletResponse` which we can use to obtain the `contentAsString` (when writing to the response) or the URL redirected to for example. These mocked versions of the Servlet API are, unlike the real versions, all completely mutable and hence you can set properties on the request such as the `contextPath` and so on.

Grails does not invoke interceptors automatically when calling actions during integration testing. You should test interceptors in isolation, and via functional testing if necessary.

#### Testing Controllers with Services

If your controller references a service, you have to explicitly initialise the service from your test.

Given a controller using a service:

    class FilmStarsController {
        def popularityService    def update = {
            // do something with popularityService
        }
    }

The test for this would be:

    class FilmStarsTests extends GroovyTestCase {
        def popularityService    public void testInjectedServiceInController () {
            def fsc = new FilmStarsController()
            fsc.popularityService = popularityService
            fsc.update()
        }
    }

#### Testing Controller Command Objects

With command objects you just supply parameters to the request and it will automatically do the command object work for you when you call your action with no parameters:

Given a controller using a command object:

    class AuthenticationController {
        def signup = { SignupForm form ->
            …
        }
    }

You can then test it like this:

    def controller = new AuthenticationController()
    controller.params.login = "marcpalmer"
    controller.params.password = "secret"
    controller.params.passwordConfirm = "secret"
    controller.signup()

Grails auto-magically sees your call to `signup()` as a call to the action and populates the command object from the mocked request parameters. During controller testing, the `params` are mutable with a mocked request supplied by Grails.

#### Testing Controllers and the render Method

The render method allows you to render a custom view at any point within the body of an action. For instance, consider the example below:

    def save = {
    	def book = Book(params)
    	if(book.save()) {
    		// handle
    	}
    	else {
    		render(view:"create", model:[book:book])
    	}
    }

In the above example the result of the model of the action is not available as the return value, but instead is stored within the `modelAndView` property of the controller. The `modelAndView` property is an instance of Spring MVC's ModelAndView class and you can use it to the test the result of an action:

    def bookController = new BookController()
    bookController.save()
    def model = bookController.modelAndView.model.book

#### Simulating Request Data

If you're testing an action that requires request data such as a REST web service you can use the Spring MockHttpServletRequest object to do so. For example consider this action which performs data binding from an incoming request:

    def create = {
    	[book: new Book(params['book']) ]
    }

If you wish the simulate the 'book' parameter as an XML request you could do something like the following:

    void testCreateWithXML() {
    	def controller = new BookController()
    	controller.request.contentType = 'text/xml'
    	controller.request.contents = '''<?xml version="1.0" encoding="ISO-8859-1"?>
    	<book>
    		<title>The Stand</title>
    		…
    	</book>
    	'''.getBytes() // note we need the bytes	def model = controller.create()
    	assert model.book
    	assertEquals "The Stand", model.book.title
    }

The same can be achieved with a JSON request:

    void testCreateWithJSON() {
    	def controller = new BookController()
     	controller.request.contentType = "text/json"
     	controller.request.content = '{"id":1,"class":"Book","title":"The Stand"}'.getBytes()	def model = controller.create()
    	assert model.book
    	assertEquals "The Stand", model.book.title}

> With JSON don't forget the `class` property to specify the name the target type to bind too. In the XML this is implicit within the name of the `<book>` node, but with JSON you need this property as part of the JSON packet.

For more information on the subject of REST web services see the section on REST.

#### Testing Web Flows

Testing Web Flows requires a special test harness called `grails.test.WebFlowTestCase` which sub classes Spring Web Flow's AbstractFlowExecutionTests class.

> Subclasses of `WebFlowTestCase` must be integration tests

For example given this trivial flow:

    class ExampleController {
    	def exampleFlow = {
    		start {
    			on("go") {
    				flow.hello = "world"
    			}.to "next"
    		}
    		next {
    			on("back").to "start"
    			on("go").to "end"
    		}
    		end()
    	}
    }

You need to tell the test harness what to use for the "flow definition". This is done via overriding the abstract `getFlow` method:

    class ExampleFlowTests extends grails.test.WebFlowTestCase {
    	def getFlow() { new ExampleController().exampleFlow }
    	…
    }

If you need to specify the flow id you can do so by overriding the getFlowId method otherwise the default is `test`:

    class ExampleFlowTests extends grails.test.WebFlowTestCase {
    	String getFlowId() { "example" }
    	…
    }

Once this is done in your test you need to kick off the flow with the `startFlow` method which returns a `ViewSelection` object:

    void testExampleFlow() {
    	def viewSelection = startFlow()	assertEquals "start", viewSelection.viewName
    	…
    }

As demonstrated above you can check you're on the right state using the `viewName` property of the `ViewSelection` object. To trigger and event you need to use the `signalEvent` method:

    void testExampleFlow() {
    	…
    	viewSelection = signalEvent("go")
    	assertEquals "next", viewSelection.viewName
    	assertEquals "world", viewSelection.model.hello
    }

Here we have signaled to the flow to execute the event "go" this causes a transition to the "next" state. In the example a transition action placed a `hello` variable into the flow scope. We can test the value of this variable by inspecting the `model` property of the `ViewSelection` as above.

#### Testing Tag Libraries

Testing tag libraries is actually pretty trivial because when a tag is invoked as a method it returns its result as a string. So for example if you have a tag library like this:

    class FooTagLib {
       def bar =  { attrs, body ->
       	   out << "<p>Hello World!</p>"
       }   def bodyTag =  { attrs, body ->
          out << "<${attrs.name}>"
               out << body()
          out << "</${attrs.name}>"
       }
    }

The tests would look like:

    class FooTagLibTests extends GroovyTestCase {  void testBarTag() {
    	   assertEquals "<p>Hello World!</p>", new FooTagLib().bar(null,null)
       }   void testBodyTag() {
    	   assertEquals "<p>Hello World!</p>", new FooTagLib().bodyTag(name:"p") {
    	       "Hello World!"
           }
        }
    }

Notice that for the second example, `testBodyTag`, we pass a block that returns the body of the tag. This is handy for representing the body as a String.

#### Testing Tag Libraries with GroovyPagesTestCase

In addition to doing simply testing of tag libraries like the above you can also use the `grails.test.GroovyPagesTestCase` class to test tag libraries.

The `GroovyPagesTestCase` class is a sub class of the regular `GroovyTestCase` class and provides utility methods for testing the output of a GSP rendering.

> `GroovyPagesTestCase` can only be used in an integration test.

As an example given a date formatting tag library such as the one below:

    class FormatTagLib {
    	def dateFormat = { attrs, body ->
    		out << new java.text.SimpleDateFormat(attrs.format) << attrs.date
    	}
    }

This can be easily tested as follows:

    class FormatTagLibTests extends GroovyPagesTestCase {
    	void testDateFormat() {
    		def template = '<g:dateFormat format="dd-MM-yyyy" date="${myDate}" />'		def testDate = … // create the date
    		assertOutputEquals( '01-01-2008', template, [myDate:testDate] )
    	}
    }

You can also obtain the result of a GSP using the `applyTemplate` method of the `GroovyPagesTestCase` class:

    class FormatTagLibTests extends GroovyPagesTestCase {
    	void testDateFormat() {
    		def template = '<g:dateFormat format="dd-MM-yyyy" date="${myDate}" />'		def testDate = … // create the date
    		def result = applyTemplate( template, [myDate:testDate] )		assertEquals '01-01-2008', result
    	}
    }

#### Testing Domain Classes

Testing domain classes is typically a simple matter of using the GORM API, however there are some things to be aware of. Firstly, if you are testing queries you will often need to "flush" in order to ensure the correct state has been persisted to the database. For example take the following example:

    void testQuery() {
    	def books = [ new Book(title:"The Stand"), new Book(title:"The Shining")]
    	books*.save()	assertEquals 2, Book.list().size()
    }

This test will actually fail, because calling save does not actually persist the `Book` instances when called. Calling `save` merely indicates to Hibernate that at some point in the future these instances should be persisted. If you wish to commit changes immediately you need to "flush" them:

    void testQuery() {
    	def books = [ new Book(title:"The Stand"), new Book(title:"The Shining")]
    	books*.save(flush:true)	assertEquals 2, Book.list().size()
    }

In this case since we're passing the argument `flush` with a value of `true` the updates will be persisted immediately and hence will be available to the query later on.

## 9.3 Functional Testing

Functional tests involve testing the actual running application and are often harder to automate. Grails does not ship with any functional testing support out of the box, but has support for Canoo WebTest via a plug-in.

To get started install Web Test with the following commands:

    grails install-plugin webtest

Then refer to the reference on the wiki which explains how to go about using Web Test and Grails.