=================================
Testing Applications with WebTest
=================================

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


Status & License
================

WebTest is an extraction of ``paste.fixture.TestApp``, rewriting
portions to use `WebOb <https://webob.org>`_.  It is under
active development as part of the Pylons cloud of packages.

Feedback and discussion should take place on the `Pylons discuss list
<https://groups.google.com/forum/#!forum/pylons-discuss>`_, and bugs
should go into the `Github tracker
<https://github.com/Pylons/webtest/issues>`_.

This library is licensed under an :ref:`MIT-style license <license>`.

Installation
============

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

.. code-block:: sh

    $ pip install WebTest
    $ easy_install WebTest

Or if you want the development version:

.. code-block:: sh

    $ pip install https://nodeload.github.com/Pylons/webtest/tar.gz/main

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 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.

Quick start
===========

The most important object in WebTest is :class:`~webtest.app.TestApp`, the wrapper
for WSGI applications. It also allows you to perform HTTP requests on it.
To use it, you simply instantiate it with your WSGI application.

..
   >>> import os
   >>> with open('docs/form.html', 'rb') as fd:
   ...      body = fd.read()

.. note::

   If your WSGI application requires any configuration,
   you must set that up manually in your tests.

Here is a basic application::

    >>> def application(environ, start_response):
    ...     headers = [('Content-Type', 'text/html; charset=utf8'),
    ...                ('Content-Length', str(len(body)))]
    ...     start_response('200 OK', headers)
    ...     return [body]

Wrap it into a :class:`~webtest.app.TestApp`::

    >>> from webtest import TestApp
    >>> app = TestApp(application)

Then you can get the response of a HTTP GET::

    >>> resp = app.get('/')

And check the results, like response's status::

    >>> assert resp.status == '200 OK'
    >>> assert resp.status_int == 200

Response's headers::

    >>> assert resp.content_type == 'text/html'
    >>> assert resp.content_length > 0

Or response's body::

    >>> resp.mustcontain('<html>')
    >>> assert 'form' in resp

WebTest can do much more. In particular, it can handle :doc:`forms`.


Contents
========


.. toctree::

   webtest.rst
   api.rst
   contributing.rst
   changelog.rst

.. _license:

.. include:: ../license.rst
