|
|
.. _testing:
|
|
|
|
|
|
=========================
|
|
|
Writing and running tests
|
|
|
=========================
|
|
|
|
|
|
Overview
|
|
|
========
|
|
|
|
|
|
It is extremely important that all code contributed to IPython has tests.
|
|
|
Tests should be written as unittests, doctests or other entities that the
|
|
|
IPython test system can detect. See below for more details on this.
|
|
|
|
|
|
Each subpackage in IPython should have its own :file:`tests` directory that
|
|
|
contains all of the tests for that subpackage. All of the files in the
|
|
|
:file:`tests` directory should have the word "tests" in them to enable
|
|
|
the testing framework to find them.
|
|
|
|
|
|
If a subpackage has any dependencies beyond the Python standard library, the
|
|
|
tests for that subpackage should be skipped if the dependencies are not found.
|
|
|
This is very important so users don't get tests failing simply because they
|
|
|
don't have dependencies. We are still figuring out the best way for this
|
|
|
to be handled.
|
|
|
|
|
|
Status
|
|
|
======
|
|
|
|
|
|
Currently IPython's testing system is being reworked. In the meantime,
|
|
|
we recommend the following testing practices:
|
|
|
|
|
|
* To run regular tests, use the :command:`nosetests` command that Nose [Nose]_
|
|
|
provides on a per file basis:
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
nosetests -vvs IPython.core.tests.test_component
|
|
|
|
|
|
* To run Twisted-using tests, use the :command:`trial` command on a per file
|
|
|
basis:
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
trial IPython.kernel
|
|
|
|
|
|
* For now, regular tests (of non-Twisted using code) should be written as
|
|
|
unit tests. They should be subclasses of :class:`unittest.TestCase`.
|
|
|
|
|
|
* Tests of Twisted [Twisted]_ using code should be written by subclassing the
|
|
|
``TestCase`` class that comes with ``twisted.trial.unittest``. Furthermore,
|
|
|
all :class:`Deferred` instances that are created in the test must be
|
|
|
properly chained and the final one *must* be the return value of the test
|
|
|
method.
|
|
|
|
|
|
.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/
|
|
|
|
