nose: a discovery-based unittest extension.

nose provides an alternate test discovery and running process for
unittest, one that is intended to mimic the behavior of py.test as much as
is reasonably possible without resorting to too much magic.

Basic usage
===========

Use the nosetests script (after installation by setuptools)::

  nosetests [options] [(optional) test files or directories]

You may also use nose in a test script::

  import nose
  nose.main()

If you want the test script to exit with 0 on success and 1 on failure
(like unittest.main), use nose.run_exit() instead::

  import nose
  nose.run_exit()
  
Lastly, you can nose.core directly::

  python /path/to/nose/core.py

Please see the usage message for the nosetests script for information
about how to control which tests nose runs and the test output.
  
Features
========

Run as collect
--------------

nose begins running tests as soon as the first test module is
loaded, it does not wait to collect all tests before running the first.

Output capture
--------------

Unless called with the -s (--nocapture) switch, nose will capture
stdout during each test run, and print the captured output only for
tests that fail or have errors. The captured output is printed immediately
following the error or failure output for the test. (Note that output in
teardown methods is captured, but can't be output with failing tests,
because teardown has not yet run at the time of the failure.)

As of nose 0.7, output capture is implemented by patching a custom
Exception class into exceptions, which allows it to work with the default
unittest test runner, so you can use nose.collector to replace any
unittest.TestSuite in any context (in theory).

Assert introspection
--------------------

When run with the -d (--detailed-errors) switch, nose will try to output
additional information about the assert expression that failed with each
failing test. Currently, this means that names in the assert expression
will be expanded into any values found for them in the locals or globals
in the frame in which the expression executed.

In other words if you have a test like::

  def test_integers():
      a = 2
      assert a == 4, "assert 2 is 4"

You will get output something like::

  File "/path/to/file.py", line XX, in test_integers:
        assert a == 4, "assert 2 is 4"
  InspectAssertionError: assert 2 is 4
    >>  assert 2 == 4, "assert 2 is 4"
    
Setuptools integration
----------------------

nose may be used with setuptools_. Simply specify the default test
collector as the test suite in your setup file::

  setup (
      # ...
      test_suite = 'nose.collector'
  )

Then to find and run tests, you can run::

  python setup.py test

When running under setuptools, you can configure nose settings via the
environment variables detailed in the nosetests script usage message.
    
.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools

Doctest integration
-------------------

doctest_ tests are usually included in the tested package, not grouped
into packages or modules of their own. For this reason, nose will try to
detect and run doctest tests only in the non-test packages it discovers in
the working directory.

doctest tests are run like any other test, with the exception that output
capture does not work, because doctest does its own output capture in the
course of running a test.

.. _doctest: http://docs.python.org/lib/module-doctest.html

Optional code coverage report
-----------------------------

If you have Ned Batchelder's coverage_ module installed, you may activate
a coverage report with the -l or --coverage switch or the NOSE_COVERAGE
environment variable. The coverage report will cover any module that nose
has imported, except modules matching testMatch.

.. _coverage: http://www.nedbatchelder.com/code/modules/coverage.html

Writing tests
=============

As with py.test and TestGears, nose tests need not be subclasses of
TestCase. Any function or class that matches the configured testMatch regular
expression ('(?:^|[_\.-])[Tt]est)'' by default) and lives in a module that
also matches that expression will be run as a test. For the sake of
compatibility with legacy unittest test cases, nose will also load tests from
unittest.TestCase subclasses just like unittest does, and wrap them in
nose.Wrap so that output capture will work for them too. Like py.test and
TestGears, functional tests will be run in the order in which they appear in
the module file. TestCase derived tests and other test classes are run in
alphabetical order.

Fixtures
--------

nose supports fixtures (setup and teardown methods) at the package,
module, and test level. As with py.test or unittest fixtures, setup always
runs before any test (or collection of tests for test packages and modules);
teardown runs if setup has completed successfully, whether or not the test
or tests pass. For more detail on fixtures at each level, see below.

Test packages
-------------

nose allows tests to be grouped into test packages. This allows
package-level setup; for instance, if you need to create a test database
or other data fixture for your tests, you may create it in package setup
and remove it in package teardown once per test run, rather than having to
create and tear it down once per test module or test case.

To create package-level setup and teardown methods, define setup and/or
teardown functions in the __init__.py of a test package. Setup methods may
be named 'setup', 'setup_package', 'setUp',or 'setUpPackage'; teardown may
be named 'teardown', 'teardown_package', 'tearDown' or 'tearDownPackage'.
Execution of tests in a test package begins as soon as the first test
module is loaded from the test package.

Test modules
------------

A test module is a python module that matches the testMatch regular
expression. Test modules offer module-level setup and teardown; define the
method 'setup', 'setup_module', 'setUp' or 'setUpModule' for setup,
'teardown', 'teardown_module', or 'tearDownModule' for teardown. Execution
of tests in a test module begins after all tests are collected.

Test classes
------------

A test class is a class defined in a test module that is either a subclass
of unittest.TestCase, or matches testMatch. Test classes that don't
descend from unittest.TestCase are run in the same way as those that do:
methods in the class that match testMatch are discovered, and a test case
constructed to run each with a fresh instance of the test class. Like
unittest.TestCase subclasses, other test classes may define setUp and
tearDown methods that will be run before and after each test method.

Test functions
--------------

Any function in a test module that matches testMatch will be wrapped in a
FunctionTestCase and run as a test. The simplest possible failing test is
therefore::

  def test():
      assert False

And the simplest passing test::

  def test():
      pass

Test functions may define setup and/or teardown attributes, which will be
run before and after the test function, respectively. A convenient way to
do this, especially when several test functions in the same module need
the same setup, is to use the provided with_setup decorator::

  def setup_func():
      # ...

  def teardown_func():
      # ...

  @with_setup(setup_func,teardown_func)
  def test():
      # ...

For python 2.3, add the attributes by calling the decorator function like
so::

  def test():
      # ...
  test = with_setup(setup_func,teardown_func)(test)
  
About the name
==============

* nose is the least silly short synonym for discover in the dictionary.com
  thesaurus that does not contain the word 'spy'.
* Pythons have noses
* The nose knows where to find your tests
* Nose Obviates Suite Employment

Contact the author
==================

To report bugs, ask questions, or request features, please email the author at
jpellerin+nose at gmail dot com. Patches are welcome!

Similar test runners
====================

nose was inspired mainly by py.test_, which is far more functional than
nose, but is not all that easy to install, and is not based on unittest.

TestGears_ is a similar test runner (now part of TurboGears) that was
released during development of nose. TestGears is a little farther towards
the 'no magic' side of the testing axis, and integrates with setuptools
with a custom action.

Test suites written for use with nose should work equally well with either
py.test or TestGears, and vice versa, except for the differences in output
capture and command line arguments for the respective tools.

.. _py.test: http://codespeak.net/py/current/doc/test.html
.. _TestGears: http://www.turbogears.com/testgears/

License and copyright
=====================

nose is copyright Jason Pellerin 2005

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

TODO
====

* Convert doctest and coverage support into optional plugins using setuptools
  entrypoints
* Docstrings for all classes
* Output better shortDescription()s
* BUG: in some cases, a test module that has a failing import may result
  in an incorrect ImportError referencing the test module (or another
  module along the chain to the failed import) rather than the actual
  failed import
