diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index e77160c..ae99fd1 100644 --- a/docs/writing/tests.rst +++ b/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. - The implication of this rule is that each test must be loaded with a fresh - dataset and may have to do some cleanup afterwards. This is usually - handled by ``setUp()`` and ``tearDown()`` methods. + alone, and also within the test suite, regardless of the order they are + called. The implication of this rule is that each test must be loaded with + a fresh dataset and may have to do some cleanup afterwards. This is + 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 - be run as often as desirable. In some cases, tests can't be fast because they - need a complex data structure to work on, and this data structure must be - loaded every time the test runs. Keep these heavier tests in a separate test - suite that is run by some scheduled task, and run all other tests as often - as needed. + few millisecond to run, development will be slowed down or the tests will + not be run as often as desirable. In some cases, tests can't be fast because + they need a complex data structure to work on, and this data structure must + be loaded every time the test runs. Keep these heavier tests in a separate + test suite that is run by some scheduled task, and run all other tests as + 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 - the rest of the code. + after. This will give you more confidence that you did not break anything + in the rest of the code. -- It is a good idea to implement a hook that runs all tests before pushing code - to a shared repository. +- It is a good idea to implement a hook that runs all tests before pushing + code to a shared repository. -- If you are in the middle of a development session and have to interrupt your work, it - is a good idea to write a broken unit test about what you want to develop next. - When coming back to work, you will have a pointer to where you were and get - back on track faster. +- If you are in the middle of a development session and have to interrupt + your work, it is a good idea to write a broken unit test about what you + want to develop next. When coming back to work, you will have a pointer + 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 - slightly different than that of running code, where short names are often - preferred. The reason is testing functions are never called explicitly. +- Use long and descriptive names for testing functions. The style guide here + is slightly different than that of running code, where short names are + 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 fail, and should be as descriptive as possible. + ``test_square_negative_number()``. These function names are displayed when + 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 - set of tests, you or other maintainers will rely largely on the testing suite - to fix the problem or modify a given behavior. Therefore the testing code will - be read as much as or even more than the running code. A unit test whose - purpose is unclear is not very helpful is this case. +- When something goes wrong or has to be changed, and if your code has a + good set of tests, you or other maintainers will rely largely on the + testing suite to fix the problem or modify a given behavior. Therefore + the testing code will be read as much as or even more than the running + 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. -Its API will be familiar to anyone who has used any of the JUnit/nUnit/CppUnit -series of tools. +:mod:`unittest` is the batteries-included test module in the Python standard +library. Its API will be familiar to anyone who has used any of the +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 -available in the `standard library `_. For older versions of Python: