Web unit testing  (the concise help)
====================================

To run the current demo tests, use::

   ./run_tests demo


Installation
------------

Install the webunit libraries with::

   python setup.py install

Then make a directory like the demo one in your application with tests in
it, and invoke with::

   ./run_tests <test>

<test>
   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`_):

1. 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.
2. authinfo -- basic authentication information. Use setBasicAuth to set and
   clearBasicAuth to clear.
3. cookies -- the test's store of cookies
4. 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:

1. protocol, server, port, url - the request server and URL
2. code, message, headers - the information returned by httplib.HTTP.getreply()
3. 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'})


Thanks
======

Thanks to everyone who's helped with this package, including supplying
hints, bug reports and (more importantly :) patches:

Gary Capell

Note that this list is nowhere near complete, as I've only just started
maintaining it. If you're miffed that you're not on it, just let me know!


License
=======
Copyright (c) 2003 Richard Jones (http://mechanicalcat.net/richard)

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 Ekit.com Inc.

Copyright (c) 2002 ekit.com Inc (http://www.ekit-inc.com/)

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.

Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)

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.


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