improve the testing documentation. Add a section about the alternate test runner ./run.py

test/refactor.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
 """
 Refactoring tests work a little bit similar to Black Box tests. But the idea is
-here to compare two versions of code.
+here to compare two versions of code. **Note: Refactoring is currently not in
+active development (and was never stable), the tests are therefore not really
+valuable - just ignore them.**
 """
 from __future__ import with_statement
 import os

test/run.py

@@ -46,7 +46,20 @@ Run test at line 4, 6, and 8 in ``basic.py``::
 
 See ``py.test --help`` for more information.
 
-If you want to debug a test, just use the --pdb option.
+If you want to debug a test, just use the ``--pdb`` option.
+
+Alternate Test Runner
++++++++++++++++++++++
+
+If you don't like the output of ``py.test``, there's an alternate test runner
+that you can start by running ``./run.py``. The above example could be run by::
+
+    ./run.py basic 4 6 8
+
+The advantage of this runner is simplicity and more customized error reports.
+Using both runners will help you to have a quicker overview of what's
+happening.
+
 
 Auto-Completion
 +++++++++++++++