15 Testing

Automated testing is a key part of Grails. 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 for testing.

The first thing to be aware of is that all of the create- and generate-\ commands create unit or integration tests automatically. For example if you run the create-controller command as follows:

  1. grails create-controller com.acme.app.simple

Grails will create a controller at grails-app/controllers/com/acme/app/SimpleController.groovy, and also a unit test at src/test/groovy/com/acme/app/SimpleControllerSpec.groovy. What Grails won’t do however is populate the logic inside the test! That is left up to you.

The default class name suffix is Tests but as of Grails 1.2.2, the suffix of Test is also supported.

Running Tests

Tests are run with the test-app command:

  1. grails test-app

The command will produce output such as:

  1. -------------------------------------------------------
  2. Running Unit Tests...
  3. Running test FooTests...FAILURE
  4. Unit Tests Completed in 464ms ...
  5. -------------------------------------------------------
  7. Tests failed: 0 errors, 1 failures

whilst showing the reason for each test failure.

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

Grails writes both plain text and HTML test reports to the target/test-reports directory, along with the original XML files. The HTML reports are generally the best ones to look at.

Using Grails' interactive mode confers some distinct advantages when executing tests. First, the tests will execute significantly faster on the second and subsequent runs. Second, a shortcut is available to open the HTML reports in your browser:

  1. open test-report

You can also run your unit tests from within most IDEs.

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:

  1. grails test-app SimpleController

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

  1. grails test-app *Controller

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

  1. grails test-app some.org.*Controller

or to run all tests in a package…​

  1. grails test-app some.org.*

or to run all tests in a package including subpackages…​

  1. grails test-app some.org.**.*

You can also target particular test methods…​

  1. 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…​

  1. grails test-app some.org.* SimpleController.testLogin BookController
In Grails 2.x, adding -rerun as an argument would only run those tests which failed in the previous test-app run. This argument is no longer supported.
In Grails 3.x, you might need to specify the package name before the class name, as well as append "Spec" to the end. For example, if you want to run the test for the ProductController, you should use grails test-app *.ProductControllerSpec. Note that the star can be used if you don’t want to type the whole package hierarchy.

Debugging

In order to debug your tests via a remote debugger, you can add —debug-jvm after grails in any commands, like so:

  1. grails --debug-jvm test-app

This will open the default Java remote debugging port, 5005, for you to attach a remote debugger from your editor / IDE of choice.

This differs from Grails 2.3 and previous, where the grails-debug command existed.

Targeting Test Phases

In addition to targeting certain tests, you can also target test phases. By default Grails has two testing phases unit and integration.

Grails 2.x uses phase:type syntax. In Grails 3.0 it was removed, because it made no sense in Gradle context.

To execute unit tests you can run:

  1. grails test-app -unit

To run integration tests you would run…​

  1. grails test-app -integration

Targeting Tests When Using Phases

Test and phase targeting can be applied at the same time:

  1. grails test-app some.org.**.* -unit

This would run all tests in the unit phase that are in the package some.org or a subpackage.