fixing docs to remind folks to make sure tests fail for the right reasons

ChangeLog

@@ -1,3 +1,9 @@
+2015-04-15  Susan Steinman  <steinman.tutoring@gmail.com>
+
+   * khmer/tests/khmer_tst_utils.py,doc/dev/a-quick-guide-to-testing.rst
+      edited docstring and docs to remind people to make sure tests test
+      errors correctly
+
 2015-04-15  Michael R. Crusoe  <mcrusoe@msu.edu>
 
    * sandbox/make-coverage.py: tweak for importability

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

@@ -58,6 +58,11 @@ We suggest the following approach to writing tests for **new code**:
    your code -- if statements, fence-post bound errors, etc. -- and write
    tests that exercise those bits of code specifically.
 
+#. Make sure tests that expect a function call to fail (esp. with
+   fail_ok=True) are failing for the expected reason. Run the code from the
+   command line and see what the behavior is. For troubleshooting tests,
+   catch the error with try: ... except: or print err.
+
 For adding tests to **old code**, we recommend a mix of two approaches:
 
 #. use `"stupidity driven testing"

tests/khmer_tst_utils.py

@@ -79,6 +79,8 @@ def runscript(scriptname, args, in_directory=None,
 
     Run the given Python script, with the given args, in the given directory,
     using 'execfile'.
+
+    When using :attr:`fail_ok`=False in tests, specify the expected error.
     """
     sysargs = [scriptname]
     sysargs.extend(args)