From 1834ef51b1f6cd31ff07080b073286d3675facad Mon Sep 17 00:00:00 2001
From: David Halter <davidhalter88@gmail.com>
Date: Thu, 28 Feb 2013 23:57:33 +0430
Subject: [PATCH] basic testing docstring for run.py

---
 docs/docs/development.rst |  2 +-
 docs/docs/testing.rst     | 12 ++++++++----
 test/run.py               | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/docs/docs/development.rst b/docs/docs/development.rst
index ffeaad22..a6a8b3d1 100644
--- a/docs/docs/development.rst
+++ b/docs/docs/development.rst
@@ -34,7 +34,7 @@ In five chapters I'm trying to describe the internals of |jedi|:
 - :ref:`Helper modules <dev-helpers>`
 
 .. note:: Testing is not documented here, you'll find that
-   `here <testing.html>`_.
+   `right here <testing.html>`_.
 
 
 .. _core:
diff --git a/docs/docs/testing.rst b/docs/docs/testing.rst
index 5b126e90..f9e3ebf1 100644
--- a/docs/docs/testing.rst
+++ b/docs/docs/testing.rst
@@ -3,19 +3,23 @@
 Jedi Testing
 ============
 
-.. currentmodule:: test
+You want to add a test for |jedi|? Great! We love that. Normally you should
+write your tests as :ref:`Blackbox Tests <blackbox>` tests. Most tests would
+fit in there.
+
+.. _blackbox:
 
 Blackbox Tests (run.py)
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: run
+.. automodule:: test.run
 
 Regression Tests (regression.py)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: regression
+.. automodule:: test.regression
 
 Refactoring Tests (refactor.py)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: refactor
+.. automodule:: test.refactor
diff --git a/test/run.py b/test/run.py
index b9571a80..657dd0e6 100755
--- a/test/run.py
+++ b/test/run.py
@@ -1,4 +1,39 @@
 #!/usr/bin/env python
+"""
+|jedi| is mostly being tested by what I would call "Blackbox Tests". These
+tests are just testing the interface and do input/output testing. This makes a
+lot of sense for |jedi|. Jedi supports so many different code structures, that
+it is just stupid to write 200'000 unittests in the manner of
+``regression.py``. Also, it is impossible to do doctests/unittests on most of
+the internal data structures. That's why |jedi| uses mostly these kind of
+tests.
+
+So basically there are different kind of tests:
+
+- complete / definitions: ``#? ``
+- goto: ``#! ``
+- related names: ``#< ``
+
+Auto-Completion
++++++++++++++++
+
+.. autofunction:: run_completion_test
+
+Definition
+++++++++++
+
+.. autofunction:: run_definition_test
+
+Goto
+++++
+
+.. autofunction:: run_goto_test
+
+Related Names
++++++++++++++
+
+.. autofunction:: run_related_name_test
+"""
 import os
 import sys
 import re