wiki2/tests - commit progress

1 files changed, 53 insertions, 24 deletions

diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst
index 9db95334a..64025421f 100644
--- a/docs/tutorials/wiki2/tests.rst
+++ b/docs/tutorials/wiki2/tests.rst
@@ -2,25 +2,38 @@
 Adding Tests
 ============
 
-We will now add tests for the models and the views and a few functional tests
-in ``tests.py``.  Tests ensure that an application works, and that it
-continues to work when changes are made in the future.
+We will now add tests for the models and views as well as a few functional
+tests in a new ``tests`` subpackage.  Tests ensure that an application works,
+and that it continues to work when changes are made in the future.
+
+The file ``tests.py`` was generated as part of the ``alchemy`` scaffold, but it
+is a common practice to put tests into a ``tests`` subpackage, especially as
+projects grow in size and complexity.  Each module in the test subpackage
+should contain tests for its corresponding module in our application.  Each
+corresponding pair of modules should have the same names, except the test
+module should have the prefix "test_".
+
+We will move parts of ``tests.py`` into appropriate new files in the ``tests``
+subpackage, and add several new tests.
+
 
 Test the models
 ===============
 
-To test the model class ``Page`` we'll add a new ``PageModelTests`` class to
-our ``tests.py`` file that was generated as part of the ``alchemy`` scaffold.
+To test the model class ``Page``, we'll add a new ``PageModelTests`` class to
+a new file ``tests/test_models.py``
+
 
 Test the views
 ==============
 
-We'll modify our ``tests.py`` file, adding tests for each view function we
-added previously.  As a result, we'll *delete* the ``ViewTests`` class that
-the ``alchemy`` scaffold provided, and add four other test classes:
-``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and ``EditPageTests``.
-These test the ``view_wiki``, ``view_page``, ``add_page``, and ``edit_page``
-views.
+We'll create a new ``tests/test_views.py`` file, adding tests for each view
+function we previously added to our application.  As a result, we'll *delete*
+the ``ViewTests`` class that the ``alchemy`` scaffold provided, and add four
+other test classes: ``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and
+``EditPageTests``. These test the ``view_wiki``, ``view_page``, ``add_page``,
+and ``edit_page`` views.
+
 
 Functional tests
 ================
@@ -30,23 +43,41 @@ tested in the unit tests, like logging in, logging out, checking that
 the ``viewer`` user cannot add or edit pages, but the ``editor`` user
 can, and so on.
 
-View the results of all our edits to ``tests.py``
-=================================================
 
-Open the ``tutorial/tests.py`` module, and edit it such that it appears as
+View the results of all our edits to ``tests`` subpackage
+=========================================================
+
+Open ``tutorial/tests/test_models.py``, and edit it such that it appears as
 follows:
 
-.. literalinclude:: src/tests/tutorial/tests.py
+.. literalinclude:: src/tests/tutorial/tests/test_models.py
    :linenos:
    :language: python
 
+Open ``tutorial/tests/test_views.py``, and edit it such that it appears as
+follows:
+
+.. literalinclude:: src/tests/tutorial/tests/test_views.py
+   :linenos:
+   :language: python
+
+Open ``tutorial/tests/test_.py``, and edit it such that it appears as
+follows:
+
+.. literalinclude:: src/tests/tutorial/tests/test_.py
+   :linenos:
+   :language: python
+
+
 Running the tests
 =================
 
 We can run these tests by using ``setup.py test`` in the same way we did in
-:ref:`running_tests`.  However, first we must edit our ``setup.py`` to
-include a dependency on WebTest, which we've used in our ``tests.py``.
-Change the ``requires`` list in ``setup.py`` to include ``WebTest``.
+:ref:`running_tests`.  However, first we must edit our ``setup.py`` to include
+a dependency on `WebTest
+<http://docs.pylonsproject.org/projects/webtest/en/latest/>`_, which we've used
+in our ``tests.py``.  Change the ``requires`` list in ``setup.py`` to include
+``WebTest``.
 
 .. literalinclude:: src/tests/setup.py
    :linenos:
@@ -56,12 +87,11 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``.
 
 After we've added a dependency on WebTest in ``setup.py``, we need to run
 ``setup.py develop`` to get WebTest installed into our virtualenv.  Assuming
-our shell's current working directory is the "tutorial" distribution
-directory:
+our shell's current working directory is the "tutorial" distribution directory:
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python setup.py develop
 
@@ -71,12 +101,11 @@ On Windows:
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
-Once that command has completed successfully, we can run the tests
-themselves:
+Once that command has completed successfully, we can run the tests themselves:
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python setup.py test -q