ReStructuredText | 172 lines | 131 code | 41 blank | 0 comment | 0 complexity | 6255d87a359de1dc0d8473c7e7cd8e19 MD5 | raw file
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.