doc/writing_tests.rst

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