[TIP] Updates to the unittest2 plugin system

[Michael Foord]

Hello all,

Just some news on updates to the unittest2 plugin, which you will 
probably need to know if you are experimenting with writing plugins for 
it. I'm keeping 'descriptions.txt' up to date in the repo, but it's a 
bit large so scanning it for changes is painful:

http://hg.python.org/unittest2/raw-file/tip/description.txt

There is now a messaging API for plugins. The easiest way to access it 
is via the ``message`` method on event objects. It takes a string 
message and either a single verbosity (0, 1, or 2) or a tuple of 
verbosities. The message will only be output if the verbosity you 
specify matches the verbosity of the test runner. If you output a 
verbosity before the test runner has been created then messages are 
queued until it is created. The default verbosity is (1, 2).

def onTestFail(self, event):
event.message('A test failed.')

onTestFail has changed. It *is* now called for skips and unexpected 
successes (etc), but has an 'internal' attribute to tell you if the 
exception is an internal unittest exception. The reason for this change 
is that plugins may now *modify* the exception / traceback by modifying 
``event.exc_info``. Setting it to None suppresses the exception.

The main names used by the plugin system should now be imported from 
unittest2 rather than from unittest2.events. I'm doing some refactoring 
internally.

The config structure is now populated with info like the verbosity, 
buffer, catch and failfast (corresponding to the options that the test 
run was started with). You can also specify defaults for these in 
unittest.cfg. A plugin can access what verbosity the test run was 
started with using code like:

from unittest2 import getConfig

main_config = getConfig('unittest')
verbosity = main_config.as_int('verbosity')

There are now two new events. 'afterSetUp' fires after the test setUp 
method has run but before the test itself. 'beforeTearDown' fires after 
the test has run but before the tearDown is called.

This has just been a summary, full descriptions of these features can be 
found in descriptions.txt. At the end of descriptions.txt is a list of 
the unimplemented features and open issues, some of which I will start 
discussions about on this list.

All the best,

Michael Foord

-- 
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog

READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.