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 call nose2.events.Plugin.register() in __init__ or have always-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

event – nose2.events.CommandLineArgsEvent

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 to True to prevent other plugins from loading tests from the given names, or append tests to event.extraTests. Plugins can also remove names from event.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 to True to prevent other plugins from loading tests from the given name, or append tests to event.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, set event.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 to True and return False to cause the loader to skip the module. Set event.handled to True and return True 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 to event.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, set event.handled to True and return a test suite. Plugins can also append tests to event.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, set event.handled to True 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 to event.extraNames, and exclude names by appending test names to event.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 to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 remove event.exc_info, set or clear event.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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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 respect self.session.verbosity when printing to the console. To prevent other plugins from reporting to the user, set event.handled to True.

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, set event.shouldStop to False.

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 setting event.stream. If you want to print to the console, write to event.stream. Remember to respect self.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 setting event.stream. If you want to print to the console, write to event.stream. Remember to respect self.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 to True. 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 respect self.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 returning False, 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.