Web unit testing (the concise help)

To run the current tests, use:

./run_tests [<test>]

<test>: Optionally just run the test named - just like unittest.py.

Configuration

We've found it useful to be able to test different servers with the same test suite. To this end, we've got a simple configuration file setup. See the doc string in webunit.config

Errors

If a request fails with an incorrect response code (the default valid response codes are 200, 301 and 302) then the result body fetched from the server will be appended to the logfile for that server.

Making requests - the WebTestCase class

The WebTestCase is best thought of as a web browser with some added features. To truly emulate a web browser (single-threaded at present) use the "page" methods below. For more fine-grained control and testing, use the other methods.

The WebTestCase objects have a number of attributes (see Setting up fetch defaults):

protocol, server, port -- these default to http://localhost:80 and are used when a relative fetch is performed. Most tests set these vars up with setServer in the setUp method and then use relative URLs.
authinfo -- basic authentication information. Use setBasicAuth to set and clearBasicAuth to clear.
cookies -- the test's store of cookies
images -- cache of images fetched

There are two modes of retrieval using two HTTP methods:

fetch mode: This is the default mode, and just fetches the HTML of a page.
page mode: This is a more browser-like mode. It follows redirections and loads images and stylesheets required to render the page.
GET method: This is the default HTTP method used.
POST method: All GET methods have a HTTP POST analog, usually just with post prefixed.

Now the actual calls that are possible:

assertCode(self, url, code=None, **kw): Perform a HTTP GET and assert that the return code from the server one of the indicated codes.
get = assertCode(self, url, code=None, **kw): Just an alias
assertContent(self, url, content, code=None, **kw): Perform a HTTP GET and assert that the data returned from the server contains the indicated content string.
assertNotContent(self, url, content, code=None, **kw): Perform a HTTP GET and assert that the data returned from the server contains the indicated content string.
getAssertCode = assertCode(self, url, code=None, **kw): Just an alias
getAssertContent = assertContent(self, url, content, code=None, **kw): Just an alias
getAssertNotContent = assertNotContent(self, url, content, code=None, **kw): Just an alias
page(self, url, code=None, **kw): Perform a HTTP GET using the specified URL and then retrieve all image and linked stylesheet components for the resulting HTML page.
post(self, url, params, code=None, **kw): Perform a HTTP POST using the specified URL and form parameters.
postAssertCode(self, url, params, code=None, **kw): Perform a HTTP POST and assert that the return code from the server is one of the indicated codes.
postAssertContent(self, url, params, content, code=None, **kw): Perform a HTTP POST and assert that the data returned from the server contains the indicated content string.
postAssertNotContent(self, url, params, content, code=None, **kw): Perform a HTTP POST and assert that the data returned from the server doesn't contain the indicated content string.
postPage(self, url, params, code=None, **kw): Perform a HTTP POST using the specified URL and form parameters and then retrieve all image and linked stylesheet components for the resulting HTML page.

All of these methods eventually call fetch() - the additional **kw are passed directly to the fetch method:

fetch(self, url, postdata=None, server=None, port=None, protocol=None, ok_codes=None): Run a single test request to the indicated url. Use the POST data if supplied. If the URL is a fully-qualified one (ie. has a server and protocol) then that overrides the session's default, but may be further overridden by the method arguments. Raises failureException if the returned data contains any of the strings indicated to be Error Content. Returns a HTTPReponse object wrapping the response from the server.

HTTP Response objects

The HTTPResponse objects hold all the infomation about the server's response to the request. This information includes:

protocol, server, port, url - the request server and URL
code, message, headers - the information returned by httplib.HTTP.getreply()
body - the response body returned by httplib.HTTP.getfile()

Additionally, the object has several methods:

getDOM(self)

Get a DOM for this page. See the SimpleDOM instructions for details

extractForm(self, path=[], include_submit=0, include_button=0)

Extract a form (as a dictionary) from this page.

The "path" is a list of 2-tuples ('element name', index) to follow to find the form. So:

<html><head>..</head><body>
 <p><form>...</form></p>
 <p><form>...</form></p>
</body></html>

To extract the second form, any of these could be used:

[('html',0), ('body',0), ('p',1), ('form',0)]
[('form',1)]
[('p',1)]

HTTPResponse objects are also able to fetch using WebTestCase methods. They define additional methods:

getForm(self, formnum, getmethod, postargs, *args)

Given this page, extract the "formnum"th form from it, fill the form with the "postargs" and post back to the server using the "getmethod" with additional "args".

NOTE: the form submission will include any "default" values from the form extracted from this page. To "remove" a value from the form, just pass a value None for the elementn and it will be removed from the form submission.

example WebTestCase:

page = self.get('/foo')
page.postForm(0, self.post, {'name': 'blahblah',
        'password': 'foo'})

or the slightly more complex:

page = self.get('/foo')
page.postForm(0, self.postAssertContent, {'name': 'blahblah',
        'password': None}, 'password incorrect')

postForm(self, formnum, postmethod, postargs, *args)

As with getForm, only use a POST request.

Setting up fetch defaults

setServer(self, server, port): Set the server and port number to perform the HTTP requests to.
setBasicAuth(self, username, password): Set the Basic authentication information to the given username and password.
clearBasicAuth(self): Clear the current Basic authentication information
setAcceptCookies(self, accept=1): Indicate whether to accept cookies or not
clearCookies(self): Clear all currently received cookies

Auto-fail error content

You may have the fetcher automatically fail when receiving certain content using:

registerErrorContent(self, content): Register the given string as content that should be considered a test failure (even though the response code is 200).
removeErrorContent(self, content): Remove the given string from the error content list.
clearErrorContent(self): Clear the current list of error content strings.

Cookies

To test for cookies being sent _to_ a server, use:

registerExpectedCookie(self, cookie): Register a cookie name that we expect to send to the server.
removeExpectedCookie(self, cookie): Remove the given cookie from the list of cookies we expect to send to the server.

To test for cookies sent _from_ the server, access the cookies attribute of the test harness. It is a dict of:

cookies[host name][path][cookie name] = string

SimpleDOM

Simple usage:

>>> import SimpleDOM
>>> parser = SimpleDOM.SimpleDOMParser()
>>> parser.parseString("""<html><head><title>My Document</title></head>
... <body>
...  <p>This is a paragraph!!!</p>
...  <p>This is another para!!</p>
... </body>
... </html>""")
>>> dom = parser.getDOM()
>>> dom.getByName('p')
[<SimpleDOMNode "p" {} (1 elements)>, <SimpleDOMNode "p" {} (1 elements)>]
>>> dom.getByName('p')[0][0]
'This is a paragraph!!!'
>>> dom.getByName('title')[0][0]
'My Document'

Form extraction example (see also the tests in the test/ directory of the source):

# fetch the start page
page = self.get('/ekit/home')
page = page.postForm(1, self.postAssertCode, {'__ac_name': 'joebloggs',
    '__ac_password': 'foo'}, [302])
# same as last fetch, but automatically follow the redirect
page = page.postForm(1, self.page, {'__ac_name': 'joebloggs',
    '__ac_password': 'foo'})

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This product includes software developed by Bizar Software.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

This product includes software developed by Digital Creations for use in the Z Object Publishing Environment (http://www.zope.org/).