Initial docs

docs/changelog.rst

@@ -0,0 +1,10 @@
+Changelog
+=========
+
+1.1 (in development)
+--------------------
+
+ * The initial release of this fork from `Ben Firshman original project <http://github.com/bfirsh/pytest_django>`_
+ * Added documentation
+ * Uploaded to PyPI for easy installation
+ * Added the ``transaction_test_case`` decorator for tests that needs real transactions

docs/conf.py

@@ -48,9 +48,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '1.1'
 # The full version, including alpha/beta/rc tags.
-release = '1.0'
+release = '1.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -92,6 +92,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'default'
+html_style = 'rtd.css'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/faq.rst

@@ -0,0 +1,42 @@
+FAQ
+===
+
+How can I make sure that all my tests run with a specific locale?
+-----------------------------------------------------------------
+
+Activate a specific locale in your project's ``conftest.py``::
+
+    from django.utils.translation import activate
+
+    def pytest_runtest_setup(item):
+        activate('en')
+
+.. _faq-tests-not-being-picked-up:
+
+My tests are not being picked up when I run py.test from the root directory. Why not?
+-------------------------------------------------------------------------------------
+ By default, py.test looks for tests in files named ``test*.py``. If you have your
+ tests in files with other names, they will not be collected. It is common to put tests under
+ ``app_directory/tests/views.py``. To find those tests, create a ``pytest.ini`` file in your
+ project root with the contents::
+
+    [pytest]
+    python_files=*.py
+
+
+.. _faq-django-settings-module:
+
+How can I avoid having to type DJANGO_SETTINGS_MODULE=... to run the tests?
+---------------------------------------------------------------------------
+
+If you are using virtualenvwrapper, use a postactivate script to set ``DJANGO_SETTINGS_MODULE`` when your project's virtualenv is activated.
+
+This snippet should to the trick (make sure to replace ``YOUR_VIRTUALENV_NAME``)::
+
+    echo "export DJANGO_SETTINGS_MODULE=yourproject.settings" >> $WORKON_HOME/YOUR_VIRTUALENV_NAME/bin/postactivate
+
+
+How does South and pytest-django play together?
+------------------------------------------------
+
+Djangos own syncdb will always be used to create the test database, regardless of wheter South is present or not.

docs/helpers.rst

@@ -0,0 +1,76 @@
+Django helpers
+==============
+
+
+funcargs
+--------
+
+pytest-django provides some pytest funcargs to provide depencies for tests. More information on funcargs is available in the `py.test documentation <http://pytest.org/latest/funcargs.html>`_
+
+
+rf
+~~
+An instance of a `django.test.client.RequestFactory <https://docs.djangoproject.com/en/dev/topics/testing/#django.test.client.RequestFactory>`_.
+
+Example usage::
+
+    from myapp.views import my_view
+
+    def test_details(rf):
+        request = rf.get('/customer/details')
+        response = my_view(request)
+        assert response.status_code == 200
+
+client
+~~~~~~
+An instance of a `django.test.client.Client <https://docs.djangoproject.com/en/dev/topics/testing/#module-django.test.client>`_.
+
+Example usage::
+
+    def test_with_client(client):
+        response = client.get('/')
+        assert response.content == 'Foobar'
+
+
+admin_client
+~~~~~~~~~~~~
+An instance of a `django.test.client.Client <https://docs.djangoproject.com/en/dev/topics/testing/#module-django.test.client>`_, that is logged in as an admin user.
+
+Example usage::
+
+    def test_an_admin_view(admin_client):
+        response = admin_client.get('/admin/')
+        assert response.status_code == 200
+
+
+
+decorators
+----------
+
+transaction_test_case
+~~~~~~~~~~~~~~~~~~~~~
+
+When writing unittest style tests, Django's `django.test.TestCase <https://docs.djangoproject.com/en/dev/topics/testing/#django.test.TestCase> or
+`django.test.TransactionTestCase <https://docs.djangoproject.com/en/dev/topics/testing/#django.test.TransactionTestCase>`_ is the easiest way of
+writing test cases which gets a clean test database.
+
+When transaction behaviour is being tested, the ``transaction_test_case`` decorator can be used (will have the same effect as using `TransactionTestCase <https://docs.djangoproject.com/en/dev/topics/testing/#django.test.TransactionTestCase>`_)::
+
+    from pytest_django import transaction_test_case
+
+    @transaction_test_case
+    def test_database_interaction_with_real_transactions():
+        # This code will not be wrapped in a transaction. Transaction commits/rollbacks
+        # can be tested here. After execution of this test case, the database will be flushed
+        # and reset to its original state.
+        pass
+
+pytest.urls
+~~~~~~~~~~~
+A decorator to change the URLconf for a particular test, similar to the `urls` attribute on Django's `TestCase`.
+
+Example usage::
+
+    @pytest.urls('myapp.test_urls')
+    def test_something(client):
+        assert 'Success!' in client.get('/some_path/')

docs/index.rst

@@ -1,22 +1,54 @@
-.. pytest-django documentation master file, created by
-   sphinx-quickstart on Tue May  1 10:12:50 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to pytest-django's documentation!
 =========================================
 
-Documentation is being written... stay tuned. :)
+pytest-django is a plugin for `py.test <http://pytest.org/>`_ that provides a set of useful tools for testing `Django <http://www.djangoproject.com/>`_ applications and projects.
 
 .. toctree::
    :maxdepth: 2
 
+   tutorial
+   helpers
+   faq
+   changelog
+
+Why would I use this instead of Django's manage.py test command?
+================================================================
+
+Running the test suite with py.test offers some features that are not present in Djangos standard test runner:
+
+ * `Smarter test discovery <http://pytest.org/latest/example/pythoncollection.html>`_ (no need for ``from .foo import *`` in your test modules).
+ * Less boilerplate: no need to import unittest, create a subclass with methods. Just write tests as regular functions.
+ * `Injection of test depencies with funcargs <http://pytest.org/latest/funcargs.html>`_
+ * No need to run all tests, `it is easy to specify which tests to run <http://pytest.org/latest/usage.html#specifying-tests-selecting-tests>`_.
+ * All your existing unittest-style tests will still work without any modifications.
+ * There are a lot of other nice plugins available for py.test.
+
+See the `py.test documentation <http://pytest.org/latest/>`_ for more information on py.test.
+
+Quick Start
+===========
+1. ``pip install pytest-django``
+2. Invoke your tests with the ``py.test`` command.
+3. (Optionally) If you put your tests under a tests directory (the standard Django application layout), and your files are not named ``test_FOO.py``, see the FAQ :ref:`faq-tests-not-being-picked-up`.
+
 
+Requirements
+============
+
+These packages are required to use pytest-django, and should be installed
+separately.
+
+ * Django 1.3+ (1.4 is supported)
+
+ * py.test
+
+
+Bugs? Feature suggestions?
+============================
+Report issues and feature requests at the `github issue tracker <http://github.com/pelme/pytest_django/issues>`_.
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-

docs/tutorial.rst

@@ -0,0 +1,22 @@
+Getting started
+===============
+
+Installation
+------------
+
+pytest-djangos is available at `PyPi <http://pypi.python.org/pypi/pytest-django>`_,
+the preffered installation method is with pip::
+
+    pip install pytest-django
+
+``pytest-django`` uses ``py.test``'s module system and can be used right away after installation, there is nothing more to enable.
+
+Usage
+-----
+
+Tests are invoked directly with the `py.test` command, instead of ``manage.py test``/``django-admin.py test``::
+
+    DJANGO_SETTINGS_MODULE=settings py.test
+
+Don't like typing out DJANGO_SETTINGS_MODULE=...? See :ref:`faq-django-settings-module`.
+