Canoo WebTest Plugin

• Created by Dierk Koenig, extended by Lee Butts on behalf of Refactor
• Contributions by Gert Wohlgemuth : exception logging and porting to grails 1.3.5
• See also: Functional Testing Plugin

This plugin requires Java 5 or higher

Version 2.0 requires Grails 1.2.RC2+

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

• 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 a webtest skeleton

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
+-- test/webtest
    +-- conf    (webtest.properties)
    +-- steps (Custom WebTest steps)

Adapting the test logic

MydomainTest.groovy will initially contain lines like

class MydomainTest extends grails.util.WebTest {
    def testMydomainListNewDelete() {
            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 …
}

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 test 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. In subdirectories, tests must have the according package statements.

setUp and tearDown

You can run common steps before and after each test using setUp and tearDown as you would via junit.

Custom Steps

If you need to perform an action that the core WebTest steps do not provide (e.g. checking an email address) you can extend com.canoo.webtest.steps.Step and place the class in tests/steps. It will automatically get loaded and be made available for use in your tests.

Running the tests.

The old run-webtest script is now deprecated (since 1.2.0). Running tests via test-app is recommended. Hopefully the all existing functionality of run-webtest will become available via test-app over time.

From the root directory of your application call

grails test-app -functional

You can also run only WebTests (in cases where you are using a mixture of functional tools) via

grails test-app functional:webtest

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

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

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.

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.

System properties

System parameters are passed through to WebTest. They need to be placed directly after grails on the command line e.g.

-Dserver.port=XXXX

Other command line options

The -headless option allows you to turn off the default Swing progress monitor and browser launch.

grails <run-webtest or test-app> -headless

Sources

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