1Using nose2 2=========== 3 4Naming Tests 5------------ 6 7nose2 will look in each directory under the starting directory, unless 8the configuration modifies the included paths. Within directories and 9within any Python packages found in the starting directory and any 10source directories in the starting directory, nose2 will discover 11test modules and load tests from them. "Test modules" means any 12modules whose names start with "test". See the Configuration section 13for ways to modify searching for tests. 14 15Directories nose2 will look in: 16 17* Directory that contains an ``__init__.py`` file (a Python package) 18* Directory name that contains "test" after being lowercased. 19* Directory name that is either ``lib`` or ``src`` 20 21Each of the following test files will be run:: 22 23 test.py 24 test_views.py 25 test_models.py 26 testThingy.py 27 28These files will not be run:: 29 30 not_a_test.py 31 myapp_test.py 32 some_test_file.py 33 34 35Within test modules, nose2 will load tests from 36:class:`unittest.TestCase` subclasses, and from test functions 37(functions whose names begin with "test"). 38 39 40Running Tests 41------------- 42 43In the simplest case, go to the directory that includes your project 44source and run ``nose2`` there:: 45 46 nose2 47 48This will discover tests in packages and test directories under that 49directory, load them, and run them, then output something like:: 50 51 ............................................................................. 52 ---------------------------------------------------------------------- 53 Ran 77 tests in 1.897s 54 55 OK 56 57.. todo :: 58 59 ... and test classes (classes whose names begin with "Test") 60 61To change the place discovery starts, or to change the top-level 62importable directory of the project, use the :option:`-s` and 63:option:`-t` options. 64 65.. cmdoption :: -s START_DIR, --start-dir START_DIR 66 67 Directory to start discovery. Defaults to the current working 68 directory. This directory is where nose2 will start looking for 69 tests. 70 71.. cmdoption :: -t TOP_LEVEL_DIRECTORY, --top-level-directory TOP_LEVEL_DIRECTORY, --project-directory TOP_LEVEL_DIRECTORY 72 73 Top-level directory of the project. Defaults to the starting 74 directory. This is the directory containing importable modules and 75 packages, and is always prepended to ``sys.path`` before test discovery 76 begins. 77 78Specifying Tests to Run 79~~~~~~~~~~~~~~~~~~~~~~~ 80 81Pass *test names* to nose2 on the command line to run individual test 82modules, classes, or tests. 83 84A test name consists of a *python object part* and, for generator or 85parameterized tests, an *argument part*. The *python object part* is a 86dotted name, such as 87``pkg1.tests.test_things.SomeTests.test_ok``. The argument 88part is separated from the python object part by a colon (":") and 89specifies the *index* of the generated test to select, *starting from 901*. For example, ``pkg1.test.test_things.test_params_func:1`` would 91select the *first* test generated from the parameterized test 92``test_params_func``. 93 94Plugins may provide other means of test selection. 95 96Running Tests with ``python setup.py test`` 97~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 98 99nose2 supports distribute/setuptools' ``python setup.py test`` 100standard for running tests. To use nose2 to run your package's tests, 101add the following to your setup.py:: 102 103 setup(... 104 test_suite='nose2.collector.collector', 105 ... 106 ) 107 108(Not literally. Don't put the '...' parts in.) 109 110Two warnings about running tests this way. 111 112One: because the setuptools test command is limited, nose2 returns a "test 113suite" that actually takes over the test running process completely, 114bypassing the test result and test runner that call it. This may be 115incompatible with some packages. 116 117Two: because the command line arguments to the test command may not 118match up properly with nose2's arguments, the nose2 instance started 119by the collector *does not accept any command line arguments*. This 120means that it always runs all tests, and that you cannot configure 121plugins on the command line when running tests this way. As a 122workaround, when running under the test command, nose2 will read 123configuration from ``setup.cfg`` if it is present, in addition to 124``unittest.cfg`` and ``nose2.cfg``. This enables you to put 125configuration specific to the setuptools test command in ``setup.cfg`` 126-- for instance to activate plugins that you would otherwise activate 127via the command line. 128 129 130Getting Help 131------------ 132 133Run:: 134 135 nose2 -h 136 137to get help for nose2 itself and all loaded plugins. 138 139:: 140 141 usage: nose2 [-s START_DIR] [-t TOP_LEVEL_DIRECTORY] [--config [CONFIG]] 142 [--no-user-config] [--no-plugins] [--verbose] [--quiet] [-B] [-D] 143 [--collect-only] [--log-capture] [-P] [-h] 144 [testNames [testNames ...]] 145 146 positional arguments: 147 testNames 148 149 optional arguments: 150 -s START_DIR, --start-dir START_DIR 151 Directory to start discovery ('.' default) 152 -t TOP_LEVEL_DIRECTORY, --top-level-directory TOP_LEVEL_DIRECTORY, --project-directory TOP_LEVEL_DIRECTORY 153 Top level directory of project (defaults to start dir) 154 --config [CONFIG], -c [CONFIG] 155 Config files to load, if they exist. ('unittest.cfg' 156 and 'nose2.cfg' in start directory default) 157 --no-user-config Do not load user config files 158 --no-plugins Do not load any plugins. Warning: nose2 does not do 159 anything if no plugins are loaded 160 --verbose, -v 161 --quiet 162 -h, --help Show this help message and exit 163 164 plugin arguments: 165 Command-line arguments added by plugins: 166 167 -B, --output-buffer Enable output buffer 168 -D, --debugger Enter pdb on test fail or error 169 --collect-only Collect and output test names, do not run any tests 170 --log-capture Enable log capture 171 -P, --print-hooks Print names of hooks in order of execution 172