Testing Applications with WebTest¶

Testing Applications with WebTest — WebTest 1.3.2 documentation

Testing Applications with WebTest¶

author:	Ian Bicking <ianb@colorstudy.com>
maintainer:	Gael Pasgrimaud <gael@gawel.org>

• News
• License
• webtest – Functional Testing of Web Applications
• webtest.sel – Functional Testing with Selenium

Contents

• Testing Applications with WebTest
  • Status & License
  • Installation
  • What This Does
  • TestApp
    • Making Requests
      • Modifying the Environment & Simulating Authentication
      • What Is Tested By Default
    • The Response Object
  • Form Submissions
  • Parsing the Body
  • Framework Hooks

Status & License¶

WebTest is an extraction of paste.fixture.TestApp, rewriting
portions to use WebOb. It is under
active development as part of the Paste cloud of packages.

Feedback and discussion should take place on the Paste list, and bugs should go into the
Bitbucket tracker.

This library is licensed under an MIT-style license.

WebTest is in a mercurial repository at http://bitbucket.org/ianb/webtest. You can check it out with:

$ hg clone https://bitbucket.org/ianb/webtest WebTest

Installation¶

You can use pip or easy_install to get the latest stable release:

$ pip install WebTest
$ easy_install WebTest

Or if you want the development version:

$ pip install "http://bitbucket.org/ianb/webtest/get/tip.tar.gz#egg=WebTest"

What This Does¶

WebTest helps you test your WSGI-based web applications. This can be
any application that has a WSGI interface, including an application
written in a framework that supports WSGI (which includes most
actively developed Python web frameworks – almost anything that even
nominally supports WSGI should be testable).

With this you can test your web applications without starting an HTTP
server, and without poking into the web framework shortcutting
pieces of your application that need to be tested. The tests WebTest
runs are entirely equivalent to how a WSGI HTTP server would call an
application. By testing the full stack of your application, the
WebTest testing model is sometimes called a functional test,
integration test, or acceptance test (though the latter two are
not particularly good descriptions). This is in contrast to a unit
test which tests a particular piece of functionality in your
application. While complex programming tasks are often is suited to
unit tests, template logic and simple web programming is often best
done with functional tests; and regardless of the presence of unit
tests, no testing strategy is complete without high-level tests to
ensure the entire programming system works together.

WebTest helps you create tests by providing a convenient interface to
run WSGI applications and verify the output.

TestApp¶

The most important object in WebTest is TestApp, the wrapper
for WSGI applications. To use it, you simply instantiate it with your WSGI
application. (Note: if your WSGI application requires any configuration, you
must set that up manually in your tests.)

>>> from webtest import TestApp
>>> from webtest.debugapp import debug_app
>>> app = TestApp(debug_app)
>>> res = app.get('/form.html')
>>> res.status
'200 OK'
>>> res.form
<Form />

Making Requests¶

To make a request, use:

app.get('/path', [headers], [extra_environ], ...)

This does a request for /path, with any extra headers or WSGI
environment keys that you indicate. This returns a response object,
based on webob.Response. It has some
additional methods to make it easier to test.

If you want to do a POST request, use:

app.post('/path', {'vars': 'values'}, [headers], [extra_environ],
         [upload_files], ...)

Specifically the second argument is the body of the request. You
can pass in a dictionary (or dictionary-like object), or a string
body (dictionary objects are turned into HTML form submissions).

You can also pass in the keyword argument upload_files, which is a
list of [(fieldname, filename, fild_content)]. File uploads use a
different form submission data type to pass the structured data.

For other verbs you can use:

app.put(path, params, ...)
app.delete(path, ...)

These do PUT and DELETE requests.

Modifying the Environment & Simulating Authentication¶

The best way to simulate authentication is if your application looks
in environ['REMOTE_USER'] to see if someone is authenticated.
Then you can simply set that value, like:

app.get('/secret', extra_environ=dict(REMOTE_USER='bob'))

If you want all your requests to have this key, do:

app = TestApp(my_app, extra_environ=dict(REMOTE_USER='bob'))

What Is Tested By Default¶

A key concept behind WebTest is that there’s lots of things you
shouldn’t have to check everytime you do a request. It is assumed
that the response will either be a 2xx or 3xx response; if it isn’t an
exception will be raised (you can override this for a request, of
course). The WSGI application is tested for WSGI compliance with
a slightly modified version of wsgiref.validate
(modified to support arguments to InputWrapper.readline)
automatically. Also it checks that nothing is printed to the
environ['wsgi.errors'] error stream, which typically indicates a
problem (one that would be non-fatal in a production situation, but if
you are testing is something you should avoid).

To indicate another status is expected, use the keyword argument
status=404 to (for example) check that it is a 404 status, or
status="*" to allow any status.

If you expect errors to be printed, use expect_errors=True.