Hook reference
Note
Hooks are listed here in order of execution.
Pre-registration Hooks
- pluginsLoaded(self, event)
- Parameters:
event –
nose2.events.PluginsLoadedEvent
The
pluginsLoaded
hook is called after all config files have been read, and all plugin classes loaded. Plugins that register automatically (those that callnose2.events.Plugin.register()
in__init__
or havealways-on = True
set in their config file sections) will have already been registered with the hooks they implement. Plugins waiting for command-line activation will not yet be registered.Plugins can use this hook to examine or modify the set of loaded plugins, inject their own hook methods using
nose2.events.PluginInterface.addMethod()
, or take other actions to set up or configure themselves or the test run.Since
pluginsLoaded
is a pre-registration hook, it is called for all plugins that implement the method, whether they have registered or not. Plugins that do not automatically register themselves should limit their actions in this hook to configuration, since they may not actually be active during the test run.
- handleArgs(self, event)
- Parameters:
The
handleArgs
hook is called after all arguments from the command line have been parsed. Plugins can use this hook to handle command-line arguments in non-standard ways. They should not use it to try to modify arguments seen by other plugins, since the order in which plugins execute in a hook is not guaranteed.Since
handleArgs
is a pre-registration hook, it is called for all plugins that implement the method, whether they have registered or not. Plugins that do not automatically register themselves should limit their actions in this hook to configuration, since they may not actually be active during the test run.
Standard Hooks
These hooks are called for registered plugins only.
- createTests(self, event)
- Parameters:
event – A
nose2.events.CreateTestsEvent
instance
Plugins can take over test loading by returning a test suite and setting
event.handled
to True.
- loadTestsFromNames(self, event)
- Parameters:
event – A
nose2.events.LoadFromNamesEvent
instance
Plugins can return a test suite or list of test suites and set
event.handled
toTrue
to prevent other plugins from loading tests from the given names, or append tests toevent.extraTests
. Plugins can also remove names fromevent.names
to prevent other plugins from acting on those names.
- loadTestsFromName(self, event)
- Parameters:
event – A
nose2.events.LoadFromNameEvent
instance
Plugins can return a test suite and set
event.handled
toTrue
to prevent other plugins from loading tests from the given name, or append tests toevent.extraTests
.
- handleFile(self, event)
- Parameters:
event – A
nose2.events.HandleFileEvent
instance
Plugins can use this hook to load tests from files that are not Python modules. Plugins may either append tests to
event.extraTest
, or, if they want to prevent other plugins from processing the file, setevent.handled
to True and return a test case or test suite.
- matchPath(self, event)
- Parameters:
event – A
nose2.events.MatchPathEvent
instance
Plugins can use this hook to prevent python modules from being loaded by the test loader or force them to be loaded by the test loader. Set
event.handled
toTrue
and returnFalse
to cause the loader to skip the module. Setevent.handled
toTrue
and returnTrue
to cause the loader to load the module.
- loadTestsFromModule(self, event)
- Parameters:
event – A
nose2.events.LoadFromModuleEvent
instance
Plugins can use this hook to load tests from test modules. To prevent other plugins from loading from the module, set
event.handled
and return a test suite. Plugins can also append tests toevent.extraTests
– usually that’s what you want to do, since that will allow other plugins to load their tests from the module as well.See also this warning about test cases not defined in the module.
- loadTestsFromTestCase(self, event)
- Parameters:
event – A
nose2.events.LoadFromTestCaseEvent
instance
Plugins can use this hook to load tests from a
unittest.TestCase
. To prevent other plugins from loading tests from the test case, setevent.handled
toTrue
and return a test suite. Plugins can also append tests toevent.extraTests
– usually that’s what you want to do, since that will allow other plugins to load their tests from the test case as well.
- getTestCaseNames(self, event)
- Parameters:
event – A
nose2.events.GetTestCaseNamesEvent
instance
Plugins can use this hook to limit or extend the list of test case names that will be loaded from a
unittest.TestCase
by the standard nose2 test loader plugins (and other plugins that respect the results of the hook). To force a specific list of names, setevent.handled
toTrue
and return a list: this exact list will be the only test case names loaded from the test case. Plugins can also extend the list of names by appending test names toevent.extraNames
, and exclude names by appending test names toevent.excludedNames
.
- runnerCreated(self, event)
- Parameters:
event – A
nose2.events.RunnerCreatedEvent
instance
Plugins can use this hook to wrap, capture or replace the test runner. To replace the test runner, set
event.runner
.
- resultCreated(self, event)
- Parameters:
event – A
nose2.events.ResultCreatedEvent
instance
Plugins can use this hook to wrap, capture or replace the test result. To replace the test result, set
event.result
.
- startTestRun(self, event)
- Parameters:
event – A
nose2.events.StartTestRunEvent
instance
Plugins can use this hook to take action before the start of the test run, and to replace or wrap the test executor. To replace the executor, set
event.executeTests
. This must be a callable that takes two arguments: the top-level test and the test result.To prevent the test executor from running at all, set
event.handled
toTrue
.
- startLayerSetup(self, event)
- Parameters:
event – A
nose2.events.StartLayerSetupEvent
instance (only available in suites with layers).
Plugins can use this hook to take action before the start of the
setUp
in a layer.
- stopLayerSetup(self, event)
- Parameters:
event – A
nose2.events.StopLayerSetupEvent
instance (only available in suites with layers).
Plugins can use this hook to take action after
setUp
finishes, in a layer.
- startLayerSetupTest(self, event)
- Parameters:
event – A
nose2.events.StartLayerSetupTestEvent
instance (only available in suites with layers).
Plugins can use this hook to take action before the start of
testSetUp
in a layer.
- stopLayerSetupTest(self, event)
- Parameters:
event – A
nose2.events.StopLayerSetupTestEvent
instance (only available in suites with layers).
Plugins can use this hook to take action after
testSetUp
finishes, in a layer.
- startTest(self, event)
- Parameters:
event – A
nose2.events.StartTestEvent
instance
Plugins can use this hook to take action immediately before a test runs.
- reportStartTest(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to produce output for the user at the start of a test. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- describeTest(self, event)
- Parameters:
event – A
nose2.events.DescribeTestEvent
instance
Plugins can use this hook to alter test descriptions. To return a nonstandard description for a test, set
event.description
. Be aware that other plugins may have set this also!
- setTestOutcome(self, event)
- Parameters:
event – A
nose2.events.TestOutcomeEvent
instance
Plugins can use this hook to alter test outcomes. Plugins can
event.outcome
to change the outcome of the event, tweak, change or removeevent.exc_info
, set or clearevent.expected
, and so on.
- testOutcome(self, event)
- Parameters:
event – A
nose2.events.TestOutcomeEvent
instance
Plugins can use this hook to take action based on the outcome of tests. Plugins must not alter test outcomes in this hook: that’s what
setTestOutcome()
is for. Here, plugins may only react to the outcome event, not alter it.
- reportSuccess(self, event)
- Parameters:
event – A
nose2.events.LoadFromNamesEvent
instance
Plugins can use this hook to report test success to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- reportError(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to report a test error to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- reportFailure(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to report test failure to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- reportSkip(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to report a skipped test to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- reportExpectedFailure(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to report an expected failure to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- reportUnexpectedSuccess(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to report an unexpected success to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.
- reportOtherOutcome(self, event)
- Parameters:
event – A
nose2.events.ReportTestEvent
instance
Plugins can use this hook to report a custom test outcome to the user. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console. To prevent other plugins from reporting to the user, setevent.handled
toTrue
.nose2 will never produce this event by itself. It only gets triggered if a plugin creates a test result with an unrecognized outcome.
- stopTest(self, event)
- Parameters:
event – A
nose2.events.StopTestEvent
instance
Plugins can use this hook to take action after a test has completed running and reported its outcome.
- startLayerTeardownTest(self, event)
- Parameters:
event – A
nose2.events.StartLayerTeardownTestEvent
instance (only available in suites with layers).
Plugins can use this hook to take action before the start of
testTearDown()
in a layer.
- stopLayerTeardownTest(self, event)
- Parameters:
event – A
nose2.events.StopLayerTeardownTestEvent
instance (only available in suites with layers).
Plugins can use this hook to take action after
testTearDown()
finishes, in a layer.
- startLayerTeardown(self, event)
- Parameters:
event – A
nose2.events.StartLayerTeardownEvent
instance (only available in suites with layers).
Plugins can use this hook to take action before the start of the
tearDown()
in a layer.
- stopLayerTeardown(self, event)
- Parameters:
event – A
nose2.events.StopLayerTeardownEvent
instance (only available in suites with layers).
Plugins can use this hook to take action after
tearDown()
finishes, in a layer.
- stopTestRun(self, event)
- Parameters:
event – A
nose2.events.StopTestRunEvent
instance
Plugins can use this hook to take action at the end of a test run.
- afterTestRun(self, event)
- Parameters:
event – A
nose2.events.StopTestRunEvent
instance
Note
New in version 0.2
Plugins can use this hook to take action after the end of a test run, such as printing summary reports like the builtin result reporter plugin
nose2.plugins.result.ResultReporter
.
- resultStop(self, event)
- Parameters:
event – A
nose2.events.ResultStopEvent
instance
Plugins can use this hook to prevent other plugins from stopping a test run. This hook fires when something calls
nose2.result.PluggableTestResult.stop()
. If you want to prevent this from stopping the test run, setevent.shouldStop
toFalse
.
- beforeErrorList(self, event)
- Parameters:
event – A
nose2.events.ReportSummaryEvent
instance
Plugins can use this hook to output or modify summary information before the list of errors and failures is output. To modify the categories of outcomes that will be reported, plugins can modify the
event.reportCategories
dictionary. Plugins can set, wrap, or capture the output stream by reading or settingevent.stream
. If you want to print to the console, write toevent.stream
. Remember to respectself.session.verbosity
when printing to the console.
- outcomeDetail(self, event)
- Parameters:
event – A
nose2.events.OutcomeDetailEvent
instance
Plugins can use this hook to add additional elements to error list output. Append extra detail lines to
event.extraDetail
; these will be joined together with newlines before being output as part of the detailed error/failure message, after the traceback.
- beforeSummaryReport(self, event)
- Parameters:
event – A
nose2.events.ReportSummaryEvent
instance
Plugins can use this hook to output or modify summary information before the summary lines are output. To modify the categories of outcomes that will be reported in the summary, plugins can modify the
event.reportCategories
dictionary. Plugins can set, wrap or capture the output stream by reading or settingevent.stream
. If you want to print to the console, write toevent.stream
. Remember to respectself.session.verbosity
when printing to the console.
- wasSuccessful(self, event)
- Parameters:
event – A
nose2.events.ResultSuccessEvent
instance
Plugins can use this hook to mark a test run as successful or unsuccessful. If not plugin marks the run as successful, the default state is failure. To mark a run as successful, set
event.success
toTrue
. Be ware that other plugins may set this attribute as well!
- afterSummaryReport(self, event)
- Parameters:
event – A
nose2.events.ReportSummaryEvent
instance
Plugins can use this hook to output a report to the user after the summary line is output. If you want to print to the console, write to
event.stream
. Remember to respectself.session.verbosity
when printing to the console.
User Interaction Hooks
These hooks are called when plugins want to interact with the user.
- beforeInteraction(event)
- Parameters:
event – A
nose2.events.UserInteractionEvent
Plugins should respond to this hook by getting out of the way of user interaction, if the need to, or setting
event.handled
and returningFalse
, if they need to but can’t.
- afterInteraction(event)
- Parameters:
event – A
nose2.events.UserInteractionEvent
Plugins can respond to this hook by going back to whatever they were doing before the user stepped in and started poking around.