Canoo WebTest Plugin

• Created by Dierk Koenig, extended by Lee Butts on behalf of Refactor
• See also: Functional Testing Plugin

This plugin requires Java 5 or higher

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

If you are using grails 1.0.x you will need to install webtest 0.6 (grails install-plugin webtest 0.6)

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

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)
    +-- home    (the WebTest distribution)
    +-- reports (readme.txt)
    +-- tests   (TestSuite.groovy, MydomainTest.groovy)
        +-- 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.

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.

setUp and tearDown

This relies on the default suite() method in the WebTest class. If you override suite(), you'll need to roll your own.

classSetUp() and classTearDown() are run as individual test cases. setUp() and tearDown() are run as the first and last steps of each test case.

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.

From the root directory of your application call

grails run-webtest

Since Webtest plugin version 0.6 you can execute a singe webtest.

grails run-webtest <webtest>

You can also filter the individual tests with a second parameter which is applied as regex against each method starting with 'test';

grails run-webtest <webtest> <test pattern>

The class/method filtering relies on the default suite() method in the WebTest class. If you override suite(), you'll need to roll your own.

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. {tip:title=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. {tip}

System properties

System parameters are passed through to WebTest. They need to be placed directly after grails on the command line e.g. grails -Dwt.headless=true run-webtest

-Dwt.headless=true

-Dserver.port=XXXX

Other command line options

The -nostart option allows you to run the tests against a server that is already running. It should come after run-webtest on the command line. Start your server in another terminal first with

grails test  -Ddisable.auto.recompile=true run-app

grails run-webtest -nostart

Sources

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

Dierk Koenig