From 9da09c905893ba1cb439cfa8c15017c3ca5f67e2 Mon Sep 17 00:00:00 2001
From: Dave Halter <davidhalter88@gmail.com>
Date: Tue, 11 Mar 2014 14:27:11 +0100
Subject: [PATCH] improve the testing documentation. Add a section about the
 alternate test runner ./run.py

---
 docs/docs/testing.rst |  9 ++++-----
 test/refactor.py      |  4 +++-
 test/run.py           | 15 ++++++++++++++-
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/docs/docs/testing.rst b/docs/docs/testing.rst
index fe807572..0c666a13 100644
--- a/docs/docs/testing.rst
+++ b/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
+
diff --git a/test/refactor.py b/test/refactor.py
index ec360783..9cc10fda 100755
--- a/test/refactor.py
+++ b/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
diff --git a/test/run.py b/test/run.py
index 4a225532..ab265af0 100755
--- a/test/run.py
+++ b/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
 +++++++++++++++