/doc/writing_tests.rst

  1Writing tests
  2-------------
  3
  4As with py.test_, nose tests need not be subclasses of
  5:class:`unittest.TestCase`. Any function or class that matches the configured
  6testMatch regular expression (``(?:^|[\\b_\\.-])[Tt]est)`` by default -- that
  7is, has test or Test at a word boundary or following a - or _) and lives in a
  8module that also matches that expression will be run as a test. For the sake
  9of compatibility with legacy unittest test cases, nose will also load tests
 10from :class:`unittest.TestCase` subclasses just like unittest does. Like
 11py.test, nose runs functional tests in the order in which they appear in the
 12module file. TestCase-derived tests and other test classes are run in
 13alphabetical order.
 14
 15.. _py.test: http://codespeak.net/py/current/doc/test.html
 16
 17.. _fixtures:
 18
 19Fixtures
 20========
 21
 22nose supports fixtures (setup and teardown methods) at the package,
 23module, class, and test level. As with py.test or unittest fixtures,
 24setup always runs before any test (or collection of tests for test
 25packages and modules); teardown runs if setup has completed
 26successfully, regardless of the status of the test run. For more detail
 27on fixtures at each level, see below.
 28
 29Test packages
 30=============
 31
 32nose allows tests to be grouped into test packages. This allows
 33package-level setup; for instance, if you need to create a test database
 34or other data fixture for your tests, you may create it in package setup
 35and remove it in package teardown once per test run, rather than having to
 36create and tear it down once per test module or test case.
 37
 38To create package-level setup and teardown methods, define setup and/or
 39teardown functions in the ``__init__.py`` of a test package. Setup methods may
 40be named `setup`, `setup_package`, `setUp`, or `setUpPackage`; teardown may
 41be named `teardown`, `teardown_package`, `tearDown` or `tearDownPackage`.
 42Execution of tests in a test package begins as soon as the first test
 43module is loaded from the test package.
 44
 45Test modules
 46============
 47
 48A test module is a python module that matches the testMatch regular
 49expression. Test modules offer module-level setup and teardown; define the
 50method `setup`, `setup_module`, `setUp` or `setUpModule` for setup,
 51`teardown`, `teardown_module`, or `tearDownModule` for teardown. Execution
 52of tests in a test module begins after all tests are collected.
 53
 54Test classes
 55============
 56
 57A test class is a class defined in a test module that matches testMatch or is
 58a subclass of :class:`unittest.TestCase`. All test classes are run the same
 59way: Methods in the class that match testMatch are discovered, and a test
 60case is constructed to run each method with a fresh instance of the test
 61class. Like :class:`unittest.TestCase` subclasses, other test classes can
 62define setUp and tearDown methods that will be run before and after each test
 63method. Test classes that do not descend from `unittest.TestCase` may also
 64include generator methods and class-level fixtures. Class-level setup fixtures
 65may be named `setup_class`, `setupClass`, `setUpClass`, `setupAll` or 
 66`setUpAll`; teardown fixtures may be named `teardown_class`, `teardownClass`, 
 67`tearDownClass`, `teardownAll` or `tearDownAll`. Class-level setup and teardown
 68fixtures must be class methods.
 69
 70Test functions
 71==============
 72
 73Any function in a test module that matches testMatch will be wrapped in a
 74`FunctionTestCase` and run as a test. The simplest possible failing test is
 75therefore::
 76
 77  def test():
 78      assert False
 79
 80And the simplest passing test::
 81
 82  def test():
 83      pass
 84
 85Test functions may define setup and/or teardown attributes, which will be
 86run before and after the test function, respectively. A convenient way to
 87do this, especially when several test functions in the same module need
 88the same setup, is to use the provided `with_setup` decorator::
 89
 90  def setup_func():
 91      "set up test fixtures"
 92
 93  def teardown_func():
 94      "tear down test fixtures"
 95
 96  @with_setup(setup_func, teardown_func)
 97  def test():
 98      "test ..."
 99
100For python 2.3 or earlier, add the attributes by calling the decorator
101function like so::
102
103  def test():
104      "test ... "
105  test = with_setup(setup_func, teardown_func)(test)
106
107or by direct assignment::
108
109  test.setup = setup_func
110  test.teardown = teardown_func
111  
112Please note that `with_setup` is useful *only* for test functions, not
113for test methods in `unittest.TestCase` subclasses or other test
114classes. For those cases, define `setUp` and `tearDown` methods in the
115class.
116  
117Test generators
118===============
119
120nose supports test functions and methods that are generators. A simple
121example from nose's selftest suite is probably the best explanation::
122
123  def test_evens():
124      for i in range(0, 5):
125          yield check_even, i, i*3
126
127  def check_even(n, nn):
128      assert n % 2 == 0 or nn % 2 == 0
129
130This will result in five tests. nose will iterate the generator, creating a
131function test case wrapper for each tuple it yields. As in the example, test
132generators must yield tuples, the first element of which must be a callable
133and the remaining elements the arguments to be passed to the callable.
134
135By default, the test name output for a generated test in verbose mode
136will be the name of the generator function or method, followed by the
137args passed to the yielded callable. If you want to show a different test
138name, set the ``description`` attribute of the yielded callable.
139
140Setup and teardown functions may be used with test generators. However, please
141note that setup and teardown attributes attached to the *generator function*
142will execute only once. To *execute fixtures for each yielded test*, attach
143the setup and teardown attributes to the function that is yielded, or yield a
144callable object instance with setup and teardown attributes.
145
146For example::
147
148  @with_setup(setup_func, teardown_func)
149  def test_generator():
150      # ...
151      yield func, arg, arg # ...
152
153Here, the setup and teardown functions will be executed *once*. Compare to::
154
155  def test_generator():
156      # ...
157      yield func, arg, arg # ...
158
159  @with_setup(setup_func, teardown_func)
160  def func(arg):
161      assert something_about(arg)
162
163In the latter case the setup and teardown functions will execute once for each
164yielded test.
165
166For generator methods, the setUp and tearDown methods of the class (if any)
167will be run before and after each generated test case. The setUp and tearDown
168methods *do not* run before the generator method itself, as this would cause
169setUp to run twice before the first test without an intervening tearDown.
170
171Please note that method generators *are not* supported in `unittest.TestCase`
172subclasses.