172 lines
6.5 KiB
ReStructuredText
172 lines
6.5 KiB
ReStructuredText
Writing tests
|
|
-------------
|
|
|
|
As with py.test_, nose tests need not be subclasses of
|
|
:class:`unittest.TestCase`. Any function or class that matches the configured
|
|
testMatch regular expression (``(?:^|[\\b_\\.-])[Tt]est`` by default -- that
|
|
is, has test or Test at a word boundary or following a - or _) 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 :class:`unittest.TestCase` subclasses just like unittest does. Like
|
|
py.test, nose runs functional tests in the order in which they appear in the
|
|
module file. TestCase-derived tests and other test classes are run in
|
|
alphabetical order.
|
|
|
|
.. _py.test: http://codespeak.net/py/current/doc/test.html
|
|
|
|
.. _fixtures:
|
|
|
|
Fixtures
|
|
========
|
|
|
|
nose supports fixtures (setup and teardown methods) at the package,
|
|
module, class, 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, regardless of the status of the test run. 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 matches testMatch or is
|
|
a subclass of :class:`unittest.TestCase`. All test classes are run the same
|
|
way: Methods in the class that match testMatch are discovered, and a test
|
|
case is constructed to run each method with a fresh instance of the test
|
|
class. Like :class:`unittest.TestCase` subclasses, other test classes can
|
|
define setUp and tearDown methods that will be run before and after each test
|
|
method. Test classes that do not descend from `unittest.TestCase` may also
|
|
include generator methods and class-level fixtures. Class-level setup fixtures
|
|
may be named `setup_class`, `setupClass`, `setUpClass`, `setupAll` or
|
|
`setUpAll`; teardown fixtures may be named `teardown_class`, `teardownClass`,
|
|
`tearDownClass`, `teardownAll` or `tearDownAll`. Class-level setup and teardown
|
|
fixtures must be class methods.
|
|
|
|
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():
|
|
"set up test fixtures"
|
|
|
|
def teardown_func():
|
|
"tear down test fixtures"
|
|
|
|
@with_setup(setup_func, teardown_func)
|
|
def test():
|
|
"test ..."
|
|
|
|
For python 2.3 or earlier, add the attributes by calling the decorator
|
|
function like so::
|
|
|
|
def test():
|
|
"test ... "
|
|
test = with_setup(setup_func, teardown_func)(test)
|
|
|
|
or by direct assignment::
|
|
|
|
test.setup = setup_func
|
|
test.teardown = teardown_func
|
|
|
|
Please note that `with_setup` is useful *only* for test functions, not
|
|
for test methods in `unittest.TestCase` subclasses or other test
|
|
classes. For those cases, define `setUp` and `tearDown` methods in the
|
|
class.
|
|
|
|
Test generators
|
|
===============
|
|
|
|
nose supports test functions and methods that are generators. A simple
|
|
example from nose's selftest suite is probably the best explanation::
|
|
|
|
def test_evens():
|
|
for i in range(0, 5):
|
|
yield check_even, i, i*3
|
|
|
|
def check_even(n, nn):
|
|
assert n % 2 == 0 or nn % 2 == 0
|
|
|
|
This will result in five tests. nose will iterate the generator, creating a
|
|
function test case wrapper for each tuple it yields. As in the example, test
|
|
generators must yield tuples, the first element of which must be a callable
|
|
and the remaining elements the arguments to be passed to the callable.
|
|
|
|
By default, the test name output for a generated test in verbose mode
|
|
will be the name of the generator function or method, followed by the
|
|
args passed to the yielded callable. If you want to show a different test
|
|
name, set the ``description`` attribute of the yielded callable.
|
|
|
|
Setup and teardown functions may be used with test generators. However, please
|
|
note that setup and teardown attributes attached to the *generator function*
|
|
will execute only once. To *execute fixtures for each yielded test*, attach
|
|
the setup and teardown attributes to the function that is yielded, or yield a
|
|
callable object instance with setup and teardown attributes.
|
|
|
|
For example::
|
|
|
|
@with_setup(setup_func, teardown_func)
|
|
def test_generator():
|
|
# ...
|
|
yield func, arg, arg # ...
|
|
|
|
Here, the setup and teardown functions will be executed *once*. Compare to::
|
|
|
|
def test_generator():
|
|
# ...
|
|
yield func, arg, arg # ...
|
|
|
|
@with_setup(setup_func, teardown_func)
|
|
def func(arg):
|
|
assert something_about(arg)
|
|
|
|
In the latter case the setup and teardown functions will execute once for each
|
|
yielded test.
|
|
|
|
For generator methods, the setUp and tearDown methods of the class (if any)
|
|
will be run before and after each generated test case. The setUp and tearDown
|
|
methods *do not* run before the generator method itself, as this would cause
|
|
setUp to run twice before the first test without an intervening tearDown.
|
|
|
|
Please note that method generators *are not* supported in `unittest.TestCase`
|
|
subclasses.
|