Release 2.0.M2 is experimental but fixes critical problems with all past releases causing config files to be reset in some versions of Grails. No documentation available for new 2.0 features yet, but see the source on github for info about the new APITestCase and BrowserTestCase base classes. Note that the "functional-tests" script is still non-functioning under Grails 1.3-2.0, but test-app/test-app :functional is working well.

Overview

This plugin provides really easy functional web testing within the existing framework of JUnit testing under grails.

It is lightweight and leverages the HtmlUnit engine for simulating the client browser - without requiring any specific browser installed.

This means you can:

• Do easy REST functional testing just by issuing GET/POST etc calls and then inspect the result
• Do stateful functional testing of websites, including DOM inspection
• Do any of these against your application that is automatically run locally from WAR under Jetty, or against any other URL for testing production sites

Installation

Run: grails install-plugin functional-test

Usage

1) Run: grails create-functional-test HelloWorld

2) Edit the generated <project>/test/functional/HelloWorldTests.groovy file

3) Add code to the test methods (see reference below)

Here's an example script:

class TwitterTests extends functionaltestplugin.FunctionalTestCase {
  void testSearch() {
    get('http://www.twitter.com')
    click "Search"
    assertStatus 200
    assertContentContains "search"
    form('searchForm') {
      q = "#grails"
      click "Search"
    }
    assertStatus 200
    assertContentContains "#grails"		
  }
}

4) Run: grails test-app -functional

(Optionally specifying a single test name e.g. to run YourTests add Your)

Note: For Grails version 1.2.1: the command requires the use of colon (:) at the end. So use > grails test-app functional:

5) View the output in target/test-reports

Commercial Support

Commercial support is available for this and other Grailsrocks plugins.

Functional Testing Reference

The test class has dynamic methods added by the plugin to make it easy to request content, post content, and interact with forms and page elements.

URLs are resolved in the following ways:

1. Absolute urls are treated "as is"
2. URLs that do not begin with a / are relative to the last page retrieved, or if it is the first page retrieved, relative to the value of the system property "grails.functional.test.baseURL"
3. URLs that begin with / are relative to the application, or the value of grails.functional.test.baseURL system property if it is set.

Property: cookiesEnabled

Controls whether or not cookies are allowed. Default is true. You can change this through the course of your test code.

Property: cookies

Returns all current cookies in a set. Properties on the cookies includ "domain", "name", "value", "secure", "version", "path" and "comment"

Property: javaScriptEnabled

Controls whether or not Javascript code will be executed. Default is true. You can change this through the course of your test code.

Property: redirectEnabled

Controls whether or not redirects are automatically followed. Default is true. You can change this through the course of your test code.

If you want to be able to call assertRedirectUrlXXXX methods and prove that a redirect takes place, you must set this to false

Property: page

This property is available at all times, once a page has been retrieved. It exposes the underlying HtmlUnit page object for more advanced manipulation.

You can also get direct access to any forms of the page:

void testSomething() {
    get('/mycontroller/myAction')
    assertNotNull page.forms['userDetails'] // Make sure form is there
}

Method: get(uri)

This will issue a GET request to the URI which can be relative to the last page retrieved in the test method, or absolute within the application, or a full remote URL starting with http:// or https://

An optional closure can be supplied that will enable you to attach parameters to the request:

void testSomething() {
  get('/mycontroller') {
    headers['X-something-special'] = 'A-value-here'
    // NOTE: you can use this "method call" approach or assignment x = y
    userName "marc"
    email "[email protected]"
  }
  assertContentContains "it worked"
}

Method: post(uri)

As get(uri) but using the HTTP POST method. Note that you for POST and PUT you will usually also want to specify a body:

void testSomething() {
  post('/mycontroller/save') {
	body {
		"""
<cart><item id="3"><title>Xenosapien</title><artist>Cephalic Carnage</artist></item></cart>
"""
	}
  }
  assertStatus 200
}

The body closure expects the closure result to be a string.

Method: put(uri)

As get(uri) but using the HTTP PUT method

Method: delete(uri)

As get(uri) but using the HTTP DELETE method

Method: click(idOrLinkText)

This will click a link in the currently retrieved page, locating the link by an id attribute value, or if not found, by the text of the link.

Method: followRedirect()

Follows the redirect URL specified in the last response. For use after calling assertRedirectUrl with redirectEnabled set to false.

Method: form() or form(nameOrId)

Obtains a reference to a form with name attribute matching the name passed to the method. If no form name or id is specified, it will find the first form in the page.

You can then set or query values of fields in the form:

void testSomething() {
  get('/mycontroller') {
    userName "marc"
    // NOTE: you can use this "method call" approach or assignment x = y
    email "[email protected]"
  }
  form("userDetails") {
    name = "Marc"
    email = "[email protected]"
    click "submit"
  }
  assertContentContains "form submitted"
}

The form object return lets you locate elements by the value of their name attribute, by invoking methods or setting properties. Depending on their type you can interact with them in different ways:

• Simple text fields such as inputs with type text, hidden, password etc can just be set or accessed as the value
• Checkable items - radio buttons and checkboxes - can just be set to true/false
• Selectable items - select boxes - can have their single selection get/set

form("userDetails") {
    name = "Marc"
    email = "[email protected]"
    screenName "the_unknown_guest"
    fields['convoluted.field.name'].value = "have to use setValue here"
}

form("userDetails") {
    name = "Marc"
    country = "uk" // this is a select box!
    selects['currency.id'].select "GBP" // This is a select box retrieved explicitly
}

form("userDetails") {
    name = "Marc"
    agreedTsAndCs true
    click "submit"
}

form("userDetails") {
    name = "Marc"
    radioButtons.typeOfService = "POWERUSER"
    click "submit"
}

To click a button or image input in a form, there is a synthetic method "click" method, as well as a click method on clickable elements:

form("userDetails") { 
    name = "Marc" 
    click "send" 
}

form("userDetails") {
    name = "Marc"
    send.click()
}

form("userDetails") {
    name "Marc"
    address {
        street "668 Rue des Mortes"
        country "The U.S. of A"
    }
    send.click()
}

You can directly access fields of certain types using the "fields", "radiobuttons" and "selects" array properties.

Properties and methods that you can access on specific types of field:

1. Text fields: "value" can be get or set
2. Radio buttons: "value" can be get or set - the value of the currently checked item in the group
3. Selects: "select(value)" and "deselect(value)" to change the selection. Property "selected" to get the list of selected values.

You can also submit forms that have no name or ID. Simply leave out the form name:

form {
    name = "Marc"
    click "send"
}

Method: byId(elementID)

Retrieves an element from the current page by its id attribute. Returns null if there is no such element.

Method: byName(elementName)

Retrieves an element from the current page by its name attribute. Returns null if there is no such element. Throws and exception if there are multiple elements in the page with the same name

Method: byXPath(xpathQuery)

Retrieves the first element from the current page matching the XPath query. Returns null if there is no such element.

Method: back()

Reverts to the previous response, like doing "back" in a browser but without making a new request.

Method: clearCache()

Call this if you want to force the clearing of the JS and CSS cache, which may be useful if for example you are dynamically generating CSS or JS code in your test.

Method: assertStatus <value>

Called to assert the numerical status code of the last response:

void testSomething() {
    get('/mycontroller','myAction') {
		userName "marc"
		// NOTE: you can use this "method call" approach or assignment x = y
		email "[email protected]"
    }
	assertStatus 403   // we're not logged in!
}

Method: assertContentContains <value>

Asserts that the content of the last response contains the text supplied, case insensitive and all whitespace ignored.

assertContentContains "user profile"

Method: assertContentContainsStrict <value>

Asserts that the content of the last response contains the text supplied, case sensitive, whitespace matching.

assertContentContainsStrict "User Profile"

Method: assertContent <value>

Asserts that the content of the last response equals the text supplied, case insensitive and all whitespace ignored.

assertContent "<response>ok</response>"

Method: assertContentStrict <value>

Asserts that the content of the last response equals the text supplied, case sensitive, whitespace matching.

assertContentStrict "<response>nOKn</response>n"

Method: assertContentType <value>

Asserts that the content type of the last response starts with the supplied string, eg assertContentType "text/html" will pass even if there is an encoding at the end.

assertContentType "text/html"
assertContentType "text/html; charset=utf-8"

Method: assertContentTypeStrict <value>

Asserts that the content type of the last response matches the supplied string, case and whitespace matching exactly

assertContentTypeStrict "text/html; charset=UTF-8"

Method: assertHeader <headername>, <value>

Asserts that a response header equals the expected content, case and whitespace ignored eg:

assertHeader "Cache-Control", "private, max-age="

Method: assertHeaderStrict <headername>, <value>

Asserts that a response header equals exactly the expected content eg:

assertHeaderStrict "Pragma", "no-cache"

Method: assertHeaderContains <headername>, <value>

Asserts that a response header contains the expected content, case and whitespace ignored eg:

assertHeader "Set-Cookie", "domain=.google.co.uk"

Method: assertHeaderContainsStrict <headername>, <value>

Asserts that a response header contains exactly the expected content eg:

assertHeaderContainsStrict "Set-Cookie", "domain=.google.co.uk"

Method: assertRedirectUrl <value>

Asserts that the response included a redirect to the specified URL

assertRedirectUrl "/auth/login"

Method: assertRedirectUrlContains <value>

Asserts that the response included a redirect that contains the specified string

assertRedirectUrlContains "?id=74"

Method: assertTitle <value>

Asserts that the title of the current page equals the value supplied, ignoring case and whitespace

Method: assertTitleContains <value>

Asserts that the title of the current page contains the value supplied, ignoring case and whitespace

Method: assertMeta <name>, <value>

Asserts that the meta tag of the current page with the specified name equals the value supplied, ignoring case and whitespace

Method: assertMetaContains <name>, <value>

Asserts that the meta tag of the current page with the specified name contains the value supplied, ignoring case and whitespace

Method: assertCookieExists <name>

Asserts that a cookie with that name exists in the browser of the currently executing test

Method: assertCookieExistsInDomain <name>, <domain>

Asserts that a cookie with that name exists in specified domain in the browser of the currently executing test

Method: assertCookieContains <name>, <content>

Asserts that a cookie with that name exists in the browser of the currently executing test, and contains the content expected (loosely - case and whitespace insensitive)

Method: assertCookieContainsStrict <name>, <content>

Asserts that a cookie with that name exists in the browser of the currently executing test, and contains the content expected case and whitespace sensitive

Method: assertElementTextContains <id>, <content>

Asserts that a an element with the id exists and the text nodes of it contain the specified content (loosely - case and whitespace insensitive)

Method: assertElementTextContainsStrict <id>, <content>

Asserts that a an element with the id exists and the text nodes of it contain the specified content with expected case and whitespace sensitive

Roadmap - future stuff

• Add JSON and XML response parsing
• Add JSON and XML request payloads
• Monkey patch functional tests so no need to extend test class
• Support asserting that an alert window pops up
• Fix HTML results and XSLT template says Unit Tests
• Custom test reports - with URL request stack (and all req params)
• Add support for assertElementWithId and assertElememtWithClass
• Add assert variants that take message as first param
• Analyze stacktraces to find line of test that failed and highlight in reports