Make jedi testing explanations better

CHANGELOG.rst

@@ -21,7 +21,7 @@ Changelog
   means that on the class keyword it will now return the docstring of Python's
   builtin function ``help('class')``.
 - The API documentation is now way more readable and complete. Check it out
-  under https://jedi.readthedocs.io.
+  under https://jedi.readthedocs.io. A lot of it has been rewritten.
 - Removed Python 3.4 support
 - Many bugfixes
 

docs/docs/testing.rst

@@ -28,8 +28,8 @@ simple and readable testing structure.
 
 .. _blackbox:
 
-Blackbox Tests (run.py)
+Integration Tests (run.py)
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: test.run
 

test/refactor.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python
 """
-Refactoring tests work a little bit similar to Black Box tests. But the idea is
+Refactoring tests work a little bit similar to integration tests. But the idea
-here to compare two versions of code.
+is here to compare two versions of code. If you want to add a new test case,
+just look at the existing ones in the ``test/refactor`` folder and copy them.
 """
 from __future__ import with_statement
 import os

test/run.py

@@ -1,14 +1,11 @@
 #!/usr/bin/env python
 """
-|jedi| is mostly being tested by what I would call "Blackbox Tests". These
+|jedi| is mostly being tested by what I would call "integration tests". These
-tests are just testing the interface and do input/output testing. This makes a
+tests are testing type inference with the public API. This makes a
-lot of sense for |jedi|. Jedi supports so many different code structures, that
+lot of sense for |jedi|. Also, it is hard to write doctests/unittests for
-it is just stupid to write 200'000 unittests in the manner of
+the internal data structures.
-``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.
 
-There are different kind of tests:
+There are different kinds of tests:
 
 - completions / inference ``#?``
 - goto: ``#!``
@@ -18,29 +15,31 @@ How to run tests?
 +++++++++++++++++
 
 Jedi uses pytest_ to run unit and integration tests.  To run tests,
-simply run ``pytest``.  You can also use tox_ to run tests for
+simply run ``pytest``.
-multiple Python versions.
 
 .. _pytest: http://pytest.org
-.. _tox: http://testrun.org/tox
 
-Integration test cases are located in ``test/completion`` directory
+Most integration test cases are located in the ``test/completion`` directory
-and each test case is indicated by either the comment ``#?`` (completions /
+and each test case starts with one of these comments:
-inference), ``#!`` (goto), or ``#<`` (references).
+
+- ``#?`` (completions / inference)
+- ``#!`` (goto)
+- ``#<`` (references)
+
 There is also support for third party libraries. In a normal test run they are
 not being executed, you have to provide a ``--thirdparty`` option.
 
-In addition to standard `-k` and `-m` options in pytest, you can use the
+In addition to pytest's ``-k`` and ``-m`` options, you can use the
-`-T` (`--test-files`) option to specify integration test cases to run.
+``-T`` (``--test-files`) option to specify which test cases should run.
 It takes the format of ``FILE_NAME[:LINE[,LINE[,...]]]`` where
 ``FILE_NAME`` is a file in ``test/completion`` and ``LINE`` is a line
-number of the test comment.  Here is some recipes:
+number of the test comment.  Here are some examples:
 
-Run tests only in ``basic.py`` and ``imports.py``::
+Run tests only in ``completion/basic.py`` and ``completion/imports.py``::
 
     pytest test/test_integration.py -T basic.py -T imports.py
 
-Run test at line 4, 6, and 8 in ``basic.py``::
+Run test at line 4, 6, and 8 in ``completion/basic.py``::
 
     pytest test/test_integration.py -T basic.py:4,6,8
 
@@ -57,38 +56,30 @@ that you can start by running ``./run.py``. The above example could be run by::
     ./run.py basic 4 6 8 50-80
 
 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 Tests
++++++++++++++++++++++
 
-Auto-Completion
+Uses a comment to specify a test on the next line. The comment defines the
+expected completions. The comment always begins with `#?`. The last row
+symbolizes the cursor. For example::
+
+    #? ['upper']
+    a = 'foo'; a.upp
+
+Inference Tests
 +++++++++++++++
 
-Uses comments to specify a test in the next line. The comment says which
+Inference tests look very simliar. The difference is that inference tests don't
-results are expected. The comment always begins with `#?`. The last row
+use brackets::
-symbolizes the cursor.
-
-For example::
-
-    #? ['real']
-    a = 3; a.rea
-
-Because it follows ``a.rea`` and a is an ``int``, which has a ``real``
-property.
-
-Inference
-+++++++++
-
-Inference tests use the same symbols like completion tests. This is
-possible because the completion tests are defined with a list::
 
     #? int()
     ab = 3; ab
 
-Goto
+Goto Tests
-++++
+++++++++++
 
-Tests look like this::
+Goto Tests look like this::
 
     abc = 1
     #! ['abc=1']
@@ -100,13 +91,13 @@ describes the position of the test (otherwise it's just the end of line)::
     #! 2 ['abc=1']
     abc
 
-References
+Reference Tests
-++++++++++
++++++++++++++++
 
 Tests look like this::
 
     abc = 1
-    #< abc@1,0 abc@3,0
+    #< (1,0), (3,0)
     abc
 """
 import os