testing hooks can be better documented

[Neil Martinsen-Burrell]

I would like to test a plugin's post_branch_init hook in a script-based test. Consider a minimal example:

__init__.py:

from bzrlib import branch, trace

def test_hook(branch_params):
    trace.mutter('hook was run')
    branch_params.branch.nick = 'argh'

branch.Branch.hooks.install_named_hook('post_branch_init', test_hook, 'hook is a test')

and the script test:

self.run_script("""
$ bzr hooks
...
post_branch_init:
    hook is a test
...
""")

This test fails showing that the hook is not loaded. A test for the effect of the hook also fails:

self.run_script("""
$ bzr init
...
$ bzr nick
argh
""")

[Martin Pool (mbp)]

mutter output won't show up on stdout, even within tests.

Aside from that, the tests may be isolating the hooks, which is good in
general. You may need to specifically register it in the test.

[Neil Martinsen-Burrell (nmb)]

The script-based test is a red herring. This also fails under run_bzr:

out, err = self.run_bzr('hooks')
self.assertContainsRe(out, 'hook is a test')

Apparently bzrlib.tests.TestCase clears out all of the hooks before it runs. One can work around this by installing the hook in the test as is done in the bzrlib tests. This doesn't allow the same level of integration testing but it is understandable for isolation purposes.

[Martin Pool (mbp)]

I think clearing the hook list is basically good and if you want to
test the effect of a hook you ought to explicitly register it.

If you want to check that having a plugin causes the hook to be
registered, then you can probably look at the saved version of the
hooks, or perhaps patch TestCase to let you see it.

[Vincent Ladeuil (vila)]

TestCase indeed clears the hook for isolation purposes *and* to make sure *required* hooks are registered explicitly (see TestCase for details).

All tests should explicitly register the hooks they want to test.

This is documented in 'TestCase and its subclasses' in doc/developers/testing.txt but could be made more explicit.

I'll re-target the bug to that effect.