Merge pull request #1685 from dib-lab/doc/testing-example

[MRG] Add example to "a quick guide for testing"

doc/dev/a-quick-guide-to-testing.rst

@@ -4,24 +4,24 @@
    Copyright (C) 2015 The Regents of the University of California.
    It is licensed under the three-clause BSD license; see LICENSE.
    Contact: [email protected]
-   
+
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are
    met:
-   
+
     * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
-   
+
     * Redistributions in binary form must reproduce the above
       copyright notice, this list of conditions and the following
       disclaimer in the documentation and/or other materials provided
       with the distribution.
-   
+
     * Neither the name of the Michigan State University nor the names
       of its contributors may be used to endorse or promote products
       derived from this software without specific prior written
       permission.
-   
+
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
@@ -33,7 +33,7 @@
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-   
+
    Contact: [email protected]
 
 A quick guide to testing (for khmer)
@@ -114,7 +114,7 @@ For adding tests to **old code**, we recommend a mix of two approaches:
 
 ----
 
-Next, to add a test, you have two options: either write a new one from 
+Next, to add a test, you have two options: either write a new one from
 scratch, or copy an existing one.  (We recommend the latter.)
 
 To write a new one, you'll need to know how to write tests. For
@@ -139,11 +139,33 @@ review.
 
 To run one specific test rather than all of them, you can do::
 
-  ./setup.py test --addopts "tests/test_scripts.py::test_load_into_counting"
+  py.test tests/test_scripts.py::test_load_into_counting
 
 Here, you're running just one test -- the test function named
 ``test_load_into_counting`` in the file ``test_scripts.py``.
 
-You can also use py.test directly, it is a bit less verbose::
+You can also invoke the test via setup.py, which is a bit more verbose::
 
-  py.test tests/test_scripts.py::test_load_into_counting
+  ./setup.py test --addopts "tests/test_scripts.py::test_load_into_counting"
+
+----
+
+Let's consider a simple test as an example.
+The following code ensures that a k-mer and its reverse complement hash to the same value, since they represent the same molecule (just observed from a different orientation).
+
+.. code:: python
+
+    def test_kmer_rc_same_hash():
+        kmer = 'GATTACAGATTACAGATTACA'
+        kmer_rc = 'TGTAATCTGTAATCTGTAATC'
+
+        ct = Counttable(21, 1e5, 2)
+        assert ct.hash(kmer) == ct.hash(kmer_rc)
+
+----
+
+This example tests only a single function.
+Tests that execute entire scripts and tests involving file I/O can require a bit more code.
+Fortunately, we've created some helper functions that make this quite a bit easier in khmer.
+See ``tests/test_scripts.py`` for some examples of code for executing scripts, capturing their output, and tidying up afterwards.
+Also, see ``tests/khmer_tst_utils.py`` for helper functions that assist with loading test data and creating temporary output files.