Merge pull request #417 from kuyan/mock

Testing section improvements

docs/writing/tests.rst

@@ -13,52 +13,53 @@ Some general rules of testing:
   correct.
 
 - Each test unit must be fully independent. Each of them must be able to run
-  alone, and also within the test suite, regardless of the order they are called.
+  alone, and also within the test suite, regardless of the order they are
-  The implication of this rule is that each test must be loaded with a fresh
+  called. The implication of this rule is that each test must be loaded with
-  dataset and may have to do some cleanup afterwards. This is usually
+  a fresh dataset and may have to do some cleanup afterwards. This is
-  handled by ``setUp()`` and ``tearDown()`` methods.
+  usually handled by :meth:`setUp()` and :meth:`tearDown()` methods.
 
 - Try hard to make tests that run fast. If one single test needs more than a
-  few millisecond to run, development will be slowed down or the tests will not
+  few millisecond to run, development will be slowed down or the tests will
-  be run as often as desirable. In some cases, tests can't be fast because they
+  not be run as often as desirable. In some cases, tests can't be fast because
-  need a complex data structure to work on, and this data structure must be
+  they need a complex data structure to work on, and this data structure must
-  loaded every time the test runs. Keep these heavier tests in a separate test
+  be loaded every time the test runs. Keep these heavier tests in a separate
-  suite that is run by some scheduled task, and run all other tests as often
+  test suite that is run by some scheduled task, and run all other tests as
-  as needed.
+  often as needed.
 
 - Learn your tools and learn how to run a single test or a test case. Then,
   when developing a function inside a module, run this function's tests very
   often, ideally automatically when you save the code.
 
 - Always run the full test suite before a coding session, and run it again
-  after. This will give you more confidence that you did not break anything in
+  after. This will give you more confidence that you did not break anything
-  the rest of the code.
+  in the rest of the code.
 
-- It is a good idea to implement a hook that runs all tests before pushing code
+- It is a good idea to implement a hook that runs all tests before pushing
-  to a shared repository.
+  code to a shared repository.
 
-- If you are in the middle of a development session and have to interrupt your work, it
+- If you are in the middle of a development session and have to interrupt
-  is a good idea to write a broken unit test about what you want to develop next.
+  your work, it is a good idea to write a broken unit test about what you
-  When coming back to work, you will have a pointer to where you were and get
+  want to develop next. When coming back to work, you will have a pointer
-  back on track faster.
+  to where you were and get back on track faster.
 
 - The first step when you are debugging your code is to write a new test
   pinpointing the bug. While it is not always possible to do, those bug
   catching test are among the most valuable pieces of code in your project.
 
-- Use long and descriptive names for testing functions. The style guide here is
+- Use long and descriptive names for testing functions. The style guide here
-  slightly different than that of running code, where short names are often
+  is slightly different than that of running code, where short names are
-  preferred. The reason is testing functions are never called explicitly.
+  often preferred. The reason is testing functions are never called explicitly.
   ``square()`` or even ``sqr()`` is ok in running code, but in testing code you
   would have names such as ``test_square_of_number_2()``,
-  ``test_square_negative_number()``. These function names are displayed when a
+  ``test_square_negative_number()``. These function names are displayed when
-  test fail, and should be as descriptive as possible.
+  a test fails, and should be as descriptive as possible.
 
-- When something goes wrong or has to be changed, and if your code has a good
+- When something goes wrong or has to be changed, and if your code has a
-  set of tests, you or other maintainers will rely largely on the testing suite
+  good set of tests, you or other maintainers will rely largely on the
-  to fix the problem or modify a given behavior. Therefore the testing code will
+  testing suite to fix the problem or modify a given behavior. Therefore
-  be read as much as or even more than the running code. A unit test whose
+  the testing code will be read as much as or even more than the running
-  purpose is unclear is not very helpful is this case.
+  code. A unit test whose purpose is unclear is not very helpful is this
+  case.
 
 - Another use of the testing code is as an introduction to new developers. When
   someone will have to work on the code base, running and reading the related
@@ -75,11 +76,11 @@ The Basics
 Unittest
 --------
 
-Unittest is the batteries-included test module in the Python standard library.
+:mod:`unittest` is the batteries-included test module in the Python standard
-Its API will be familiar to anyone who has used any of the JUnit/nUnit/CppUnit
+library. Its API will be familiar to anyone who has used any of the
-series of tools.
+JUnit/nUnit/CppUnit series of tools.
 
-Creating testcases is accomplished by subclassing a TestCase base class
+Creating test cases is accomplished by subclassing :class:`unittest.TestCase`.
 
 .. code-block:: python
 
@@ -100,7 +101,7 @@ As of Python 2.7 unittest also includes its own test discovery mechanisms.
 Doctest
 -------
 
-The doctest module searches for pieces of text that look like interactive
+The :mod:`doctest` module searches for pieces of text that look like interactive
 Python sessions in docstrings, and then executes those sessions to verify that
 they work exactly as shown.
 
@@ -251,8 +252,9 @@ the need to change any other code.
 mock
 ----
 
-``mock`` is a library for testing in Python. As of Python 3.3, it is 
+:mod:`unittest.mock` is a library for testing in Python. As of Python 3.3, it is
-available in the `standard library <http://docs.python.org/dev/library/unittest.mock`_.  
+available in the
+`standard library <https://docs.python.org/dev/library/unittest.mock>`_.
 
 For older versions of Python: