Functional Testing
3% of Grails users
Dependency:
compile "org.grails.plugins:functional-test:2.0.0"
Summary
Simple 'pure grails' functional testing for your web applications
Description
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 HelloWorld2) Edit the generated <project>/test/functional/HelloWorldTests.groovy file3) 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" } }
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:- Absolute urls are treated "as is"
- 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"
- 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 }
Method: put(uri)
As get(uri) but using the HTTP PUT methodMethod: delete(uri)
As get(uri) but using the HTTP DELETE methodMethod: 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" }
- 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" }
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:You can also submit forms that have no name or ID. Simply leave out the form name:
- Text fields: "value" can be get or set
- Radio buttons: "value" can be get or set - the value of the currently checked item in the group
- Selects: "select(value)" and "deselect(value)" to change the selection. Property "selected" to get the list of selected values.
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 nameMethod: 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 exactlyassertContentTypeStrict "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 URLassertRedirectUrl "/auth/login"
Method: assertRedirectUrlContains <value>
Asserts that the response included a redirect that contains the specified stringassertRedirectUrlContains "?id=74"
Method: assertTitle <value>
Asserts that the title of the current page equals the value supplied, ignoring case and whitespaceMethod: assertTitleContains <value>
Asserts that the title of the current page contains the value supplied, ignoring case and whitespaceMethod: assertMeta <name>, <value>
Asserts that the meta tag of the current page with the specified name equals the value supplied, ignoring case and whitespaceMethod: assertMetaContains <name>, <value>
Asserts that the meta tag of the current page with the specified name contains the value supplied, ignoring case and whitespaceMethod: assertCookieExists <name>
Asserts that a cookie with that name exists in the browser of the currently executing testMethod: assertCookieExistsInDomain <name>, <domain>
Asserts that a cookie with that name exists in specified domain in the browser of the currently executing testMethod: 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 sensitiveMethod: 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 sensitiveRoadmap - 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