[Numpy-svn] r5826 - trunk/doc

numpy-svn@scip... numpy-svn@scip...
Wed Sep 17 22:29:59 CDT 2008

Author: alan.mcintyre
Date: 2008-09-17 22:29:56 -0500 (Wed, 17 Sep 2008)
New Revision: 5826

Added documentation for doctests and using the skipif and knownfailureif decorators.
Fixed indentation on the last sample snippet in the "__init__.py and setup.py" 

Modified: trunk/doc/TESTS.txt
--- trunk/doc/TESTS.txt	2008-09-15 09:57:10 UTC (rev 5825)
+++ trunk/doc/TESTS.txt	2008-09-18 03:29:56 UTC (rev 5826)
@@ -150,6 +150,19 @@
 Note that 'check_even' is not itself a test (no 'test' in the name), but 'test_evens' is a generator that returns a series of tests, using 'check_even', across a range of inputs.  Nice.
+Doctests are a convenient way of documenting the behavior a function and allowing that behavior to be tested at the same time.  The output of an interactive Python session can be included in the docstring of a function, and the test framework can run the example and compare the actual output to the expected output.
+The doctests can be run by adding the ``doctests`` argument to the ``test()`` call; for example, to run all tests (including doctests) for numpy.lib::
+>>> import numpy as np
+>>> np.lib.test(doctests=True)
+The doctests are run as if they are in a fresh Python instance which has executed ``import numpy as np`` (tests that are part of the SciPy package also have an implicit ``import scipy as sp``).
@@ -188,13 +201,12 @@
   >>> import scipy
   >>> scipy.xxx.test()
-Also, when invoking the entire SciPy test suite, your tests will be found and run:
+Also, when invoking the entire SciPy test suite, your tests will be found and run::
   >>> import scipy
   >>> scipy.test() 
   # your tests are included and run automatically!
 Tips & Tricks
@@ -230,9 +242,29 @@
 In this case, we wanted to test solving a linear algebra problem using matrices of several data types, using ``linalg.solve`` and ``linalg.inv``.  The common test cases (for single-precision, double-precision, etc. matrices) are collected in ``LinalgTestCase``.  Note that ``LinalgTestCase`` is not descended from ``TestCase``--if it were, then nose would attempt to run ``LinalgTestCase.test_single`` and ``LinalgTestCase.test_double``, which would fail because ``LinalgTestCase`` has no ``do`` method.  Since ``TestSolve`` and ``TestInv`` inherit from ``LinalgTestCase`` and ``TestCase``, nose will run ``test_single`` and ``test_double`` for each class. 
+Known failures & skipping tests
+Sometimes you might want to skip a test or mark it as a known failure, such as when the test suite is being written before the code it's meant to test, or if a test only fails on a particular architecture.  The decorators from numpy.testing.dec can be used to do this.
+To skip a test, simply use ``skipif``::
+  from numpy.testing import *
+  @dec.skipif(SkipMyTest, "Skipping this test because...")
+  def test_something(foo):
+      ...
+The test is marked as skipped if ``SkipMyTest`` evaluates to nonzero, and the message in verbose test output is the second argument given to ``skipif``.  Similarly, a test can be marked as a known failure by using ``knownfailureif``::
+  from numpy.testing import *
+  @dec.knownfailureif(MyTestFails, "This test is known to fail because...")
+  def test_something_else(foo):
+      ...
+Of course, a test can be unconditionally skipped or marked as a known failure by passing ``True`` as the first argument to ``skipif`` or ``knownfailureif``, respectively.
+A total of the number of skipped and known failing tests is displayed at the end of the test run.  Skipped tests are marked as ``'S'`` in the test results (or ``'SKIPPED'`` for ``verbosity > 1``), and known failing tests are marked as ``'K'`` (or ``'KNOWN'`` if ``verbosity > 1``).

More information about the Numpy-svn mailing list