==========
Viewtester
==========

.. contents:: Table of Contents

What is it?
-----------

A django-application to automate creating tests for views.

Requirements
------------

* django-1.1
* jquery_ 1.4+ (optional though advisable). 

It is assumed jquery is already loaded in your template(s). If not add
this line in the (extra)head-section::

    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>

Credits
-------

Based on ideas and code from Eric Holscher's testmaker in test-utils_. 

How to get it?
--------------

You can download compressed archives from bitbucket_ or clone the
repository using mercurial. I hope to make it available via PYPI_
sometime soon.

Usage
-----

Add viewtester to your INSTALLED_APPS and include it in your urls.py
then run::

    $./manage.py run_viewtester [-f fixture.xml] appname

then open your browser and go to http://localhost:8000/.

Click around and see the results in the generated test-file. If all
goes well you should be able to run the resulting tests without any
further ado::

    $./manage.py test appname

.. note:: 
   The __init__.py that comes with viewtester imports all
   TestCase classes from all modules in the tests-directory. It is
   only created if the tests-dir doesn't exist when run_viewtester is
   started.

Overview
--------

Once added to a project's settings and urls.py you can use the
run_viewtester command to run the testserver with an app-name as an
argument and optionally a (set of) fixture to populate the
database. This follows the pattern of a django TestCase_.

The command injects middleware that logs all requests to the specified
app and resulting response status' to a test-module formated as django
TestCases. Tests will be saved to appname/tests/YYYYMMDD-NN.py. You
can override this on the commandline using the -l flag.

The middleware will also track any logging in or out you'll do and
have the test-client log in or out accordingly in the tests.

An html-div, the 'panel', is injected into the response content that
contains information about the current TestCase_: Classname and loaded
fixtures, current test-method-name and user. You can collapse the div
by clicking on the title and it can be dragged to a non-intrusive
place thanks to the magic of jquery-ui_. It will remember where you
dragged it too.

The panel contains a number of forms that allow you to:

* Create a new Class, optionally with a set of fixtures that it will
  also be loaded upon submit. The fixtures can be picked from a
  pre-populated multiselect control which contains all the files in
  appname/fixtures.

* Start a new test-method which will also reset the database to the
  state it will be when the resulting tests are run: It will be
  flushed and the class' fixtures are loaded.

* Check the template context-variables by saving assertEqual
  statements into the tests by selecting variable-names from a
  multi-select control.

* Save the current database-state for the specified app to a fixture
  to use in later tests. Fixtures will be saved to appname/fixtures/
  using the name provided. The fixture name should follow the
  name.format pattern so it can infer the format from the
  extension. Only json and xml are supported. Fixtures are saved with
  --indent==2 for easy perusal.


.. _django: http://www.djangoproject.com/
.. _bitbucket: http://bitbucket.org/pterk/django-testmaker/downloads/
.. _documentation: http://bitbucket.org/pterk/
.. _PYPI: http://pypi.python.org/pypi
.. _test-utils: http://ericholscher.com/projects/django-test-utils/
.. _TestCase: http://docs.djangoproject.com/en/dev/topics/testing/#testcase
.. _jquery: http://jquery.com/
.. _jquery-ui: http://jqueryui.com/
