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

docs/docs/testing.rst

@@ -23,6 +23,9 @@ You want to add a test for |jedi|? Great! We love that. Normally you should
 write your tests as :ref:`Blackbox Tests <blackbox>`. Most tests would
 fit right in there.
 
+For specific API testing we're using simple unit tests, with a focus on a
+simple and readable testing structure.
+
 .. _blackbox:
 
 Blackbox Tests (run.py)
@@ -30,12 +33,8 @@ Blackbox Tests (run.py)
 
 .. automodule:: test.run
 
-Regression Tests (test_regression.py)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: test.test_regression
-
 Refactoring Tests (refactor.py)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: test.refactor
+

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