Functional Testing

In addition to unit testing, Grails supports functional testing of your web application.

For this purpose, it uses the free open-source Canoo WebTest.

If you want to try out webtest very quickly, you can create a new project with create-app, create a domain class and then "generate-all" this domain class. Then generate the test layout with "create webtest" and generate the webtest itself with "generate-webtest". You can then run the tests with "run-webtest".  Note that the scaffolded webtest will not work out of the box if you use dynamic scaffolding of your controller. Just use generative scaffolding for the controller instead.

How to test your web application

Install and create

From the root directory of your application call

grails install-plugin webtest
grails create-webtest

This results in the following actions

• downloads Canoo WebTest plugin and installs it in your current grails application. The download can take a few minutes.
• creates the test directory structure for the current application
• creates standard properties and a standard test suite
• you are asked for a domain name or you can provide one with the command like "grails create-webtest MyClass"
• creates an initial webtest for the default views and controllers of the domain class
• tests basic operations: list, create, delete through the web GUI

Running the tests.

From the root directory of your application call

grails run-webtest

Runs the tests and puts reports in the reports dir.

When on Windows, the browser is automatically opened on the HTML report. It will present you a header with summarized and statistical data like below.

A trailing section shows details about all operations effected during the test (excerpt).

Note that WebTest stores all result pages it received from the server.
From the test report, you can click on the corresponding link to find out what
page the test engine worked upon at this point.

Test First WebTests can even be started if the server is not running. You can actually run the test before you have coded anything. In this case the report will show a lot of failed tests but that's helpful anyways. You'll see what behavior the tests expect and how the report is generated.

Defining your tests

The webtest folder layout

After creation and generation of a test for the mydomain domain class, you'll find the following files and folders below your application folder:

myapp
+-- webtest
    +-- conf    (webtest.properties)
    +-- reports (readme.txt)
    +-- tests   (TestSuite.groovy, MydomainTest.groovy)

Notable places for costomization are

Adapting the test logic

MydomainTest.groovy will initially contain lines like

class MydomainTest extends grails.util.WebTest {

    // Unlike unit tests, functional tests are often sequence dependent.
    // Specify that sequence here.
    void suite() {
        testMydomainListNewDelete()
        // add tests for more operations here
    }

    def testMydomainListNewDelete() {
        webtest('Mydomain basic operations: view list, create new entry, back to view, delete, view'){
            invoke(url:'mydomain')
            verifyText(text:'Home')

            verifyListPage(0)    // <- internal method call for extracting common steps

            clickLink(label:'New Mydomain')
            verifyText(text:'Create Mydomain')
            clickButton(label:'Create')

    // more ...
}

There are multiple steps like invoke, clickButton, verifyXXX, etc. that make up the test specification.

Find the full list of available steps, their parameters, a comprehensive description, and examples under WebTest Docs. This site also contains additional helpers like direct access to the WebTest docs via a sidebar and the famous WebTestRecorder that writes webtests for you while you click through your application and shines with excellent interactive XPath support.

The online documentation lists all steps in their ANT notation (i.e. XML). This exactly maps to the builder calls inside the webtest() methods in MyappTest.groovy. Behind the scenes, there is an AntBuilder that cares for the mapping, effectively producing a Groovy-API on top of Canoo WebTest.

Adapt the lines in MydomainTest.groovy to match the expected behavior of your webapp. If you have any bootstrapped data, your tests can rely on this data being available when starting the tests.

More Tests

You can have many tests like MydomainTest.groovy in the tests directory or its subdirectories.

Every such test must extend grails.util.WebTest and provide a suite method that calls each available test method. In subdirectories, tests must have the according package statements.

Tests will automatically be picked up by TestSuite.groovy. You can customize this logic to define your own suite (see its inlined comments on how to do that).

Customization of the suite is sometimes needed to assert a special sequence of test execution or to restrict the test execution to a subset of availabable tests.

Sources

Plugin sources can be browsed or checked out from http://svn.codehaus.org/grails-plugins/grails-webtest/trunk.

groovy testing
Dierk Koenig