Most configuration of nose2 is done via config files. These are
standard, .ini-style config files, with sections marked off by
key = value pairs within those sections.
When the value is a list, put each value into its own line with proper
key_expecting_list = value1 value2
.. cmdoption :: -c CONFIG, --config CONFIG Config files to load. Default behavior is to look for ``unittest.cfg`` and ``nose2.cfg`` in the start directory, as well as any user config files (unless :option:`--no-user-config` is selected).
.. cmdoption :: --no-user-config Do not load user config files. If not specified, in addition to the standard config files and any specified with :option:`-c`, nose2 will look for ``.unittest.cfg`` and ``.nose2.cfg`` in the user's $HOME directory.
Configuring Test Discovery
[unittest] section of nose2 config files is used to configure
nose2 itself. The following options are available to configure test
.. rst:configvar :: start-dir This option configures the default directory to start discovery. The default value is ``"."`` (the current directory where nose2 is executed). This directory is where nose2 will start looking for tests.
.. rst:configvar :: code-directories This option configures nose2 to add the named directories to sys.path and the discovery path. Use this if your project has code in a location other than the top level of the project, or the directories ``lib`` or ``src``. The value here may be a list: put each directory on its own line in the config file.
.. rst:configvar :: test-file-pattern This option configures how nose detects test modules. It is a file glob.
.. rst:configvar :: test-method-prefix This option configures how nose detects test functions and methods. The prefix set here will be matched (via simple string matching) against the start of the name of each method in test cases and each function in test modules.
[unittest] start-dir = tests code-directories = source more_source test-file-pattern = *_test.py test-method-prefix = t
Specifying Plugins to Load
To avoid loading any plugins, use the :option:`--no-plugins` option. Beware, though: nose2 does all test discovery and loading via plugins, so unless you are patching in a custom test loader and runner, when run with :option:`--no-plugins`, nose2 will do nothing.
.. cmdoption :: --no-plugins Do not load any plugins. *This kills the nose2.*
To specify plugins to load beyond the builtin plugins automatically
loaded, add a :config:`plugins` entry under the
section in a config file.
.. rst:configvar :: plugins List of plugins to load. Put one plugin module on each line.
To exclude some plugins that would otherwise be loaded, add an
:config:`exclude-plugins` entry under the
section in a config file.
.. rst:configvar :: exclude-plugins List of plugins to exclude. Put one plugin module on each line.
It bears repeating that in both :config:`plugins` and :config:`exclude-plugins` entries, you specify the plugin module, not the plugin class. The module is specified by the (dot-separated) fully qualified name.
[unittest] plugins = myproject.plugins.frobulate otherproject.contrib.plugins.derper exclude-plugins = nose2.plugins.loader.functions nose2.plugins.outcomes
Most plugins specify a config file section that may be used to
configure the plugin. If nothing else, any plugin that specifies a
config file section can be set to automatically register by including
always-on = True in its config:
[my-plugin] always-on = True
Plugins may accept any number of other config values, which may be
booleans, strings, integers or lists. A polite plugin will document
these options somewhere. Plugins that want to make use of nose2's
Sphinx extension as detailed in :doc:`dev/documenting_plugins`
must extract all of their config values in their
Test Runner Tips and Tweaks
Running Tests in a Single Module
You can use
nose2.main in the same way that
unittest2.main) have historically worked: to run the tests in a
single module. Just put a block like the following at the end of the
if __name__ == '__main__': import nose2 nose2.main()
Then run the module directly -- In other words, do not run the
Rolling Your Own Runner
You can take more control over the test runner by foregoing the
nose2 script and rolling your own. To do that, you just need to
write a script that calls
nose2.discover, for instance:
if __name__ == '__main__': import nose2 nose2.discover()
You can pass several keyword arguments to
nose2.discover, all of
which are detailed in the documentation for
Altering the Default Plugin Set
To add plugin modules to the list of those automatically loaded, you
can pass a list of module names to add (the
plugins) argument or
excludedPlugins). You can also subclass
:class:`nose2.main.PluggableTestProgram` and set the class-level
excludePlugins attributes to alter plugin
When Loading Plugins from Modules is not Enough
None of which will help if you need to register a plugin instance
that you've loaded yourself. For that, use the
nose2.discover. Here, you pass in a list of 2-tuples,
each of which contains a hook name and a plugin instance to register
for that hook. This allows you to register plugins that need runtime
configuration that is not easily passed in through normal channels --
and also to register objects that are not nose2 plugins as hook
targets. Here's a trivial example:
if __name__ == '__main__': import nose2 class Hello(object): def startTestRun(self, event): print("hello!") nose2.discover(extraHooks=[('startTestRun', Hello())])
This can come in handy when integrating with other systems that expect you to provide a test runner that they execute, rather than executing tests yourself (django, for instance).