17
17
"""Unit tests for the bzrlib.help module."""
19
from cStringIO import StringIO
21
21
from bzrlib import (
33
from bzrlib.tests.test_i18n import ZzzTranslations
32
class TestHelp(tests.TestCase):
35
tests.TestCase.setUp(self)
36
commands.install_bzr_command_hooks()
37
39
class TestCommandHelp(tests.TestCase):
38
40
"""Tests for help on commands."""
40
def assertCmdHelp(self, expected, cmd):
41
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
43
42
def test_command_help_includes_see_also(self):
44
43
class cmd_WithSeeAlso(commands.Command):
45
44
__doc__ = """A sample command."""
46
45
_see_also = ['foo', 'bar']
47
self.assertCmdHelp('''\
48
Purpose: A sample command.
49
Usage: bzr WithSeeAlso
52
--usage Show usage message and options.
53
-q, --quiet Only display errors and warnings.
54
-v, --verbose Display more information.
55
-h, --help Show help message.
46
cmd = cmd_WithSeeAlso()
47
helptext = cmd.get_help_text()
50
' -v, --verbose Display more information.\n'
51
' -q, --quiet Only display errors and warnings.\n'
52
' -h, --help Show help message.\n'
54
'See also: bar, foo\n')
61
56
def test_get_help_text(self):
62
57
"""Commands have a get_help_text method which returns their help."""
63
58
class cmd_Demo(commands.Command):
64
59
__doc__ = """A sample command."""
65
self.assertCmdHelp('''\
66
Purpose: A sample command.
70
--usage Show usage message and options.
71
-q, --quiet Only display errors and warnings.
72
-v, --verbose Display more information.
73
-h, --help Show help message.
78
61
helptext = cmd.get_help_text()
79
62
self.assertStartsWith(helptext,
140
123
helptext = cmd.get_help_text()
141
self.assertEqualDiff('''\
142
Purpose: A sample command.
146
--usage Show usage message and options.
147
-q, --quiet Only display errors and warnings.
148
-v, --verbose Display more information.
149
-h, --help Show help message.
160
A code block follows.
126
'Purpose: A sample command.\n'
130
' --usage Show usage message and options.\n'
131
' -v, --verbose Display more information.\n'
132
' -q, --quiet Only display errors and warnings.\n'
133
' -h, --help Show help message.\n'
144
' A code block follows.\n'
146
' bzr Demo something\n'
166
148
helptext = cmd.get_help_text(plain=False)
167
self.assertEqualDiff('''\
168
:Purpose: A sample command.
172
--usage Show usage message and options.
173
-q, --quiet Only display errors and warnings.
174
-v, --verbose Display more information.
175
-h, --help Show help message.
186
A code block follows.
149
self.assertEquals(helptext,
150
':Purpose: A sample command.\n'
154
' --usage Show usage message and options.\n'
155
' -v, --verbose Display more information.\n'
156
' -q, --quiet Only display errors and warnings.\n'
157
' -h, --help Show help message.\n'
168
' A code block follows.\n'
172
' bzr Demo something\n'
195
175
def test_concise_help_text(self):
196
176
"""Concise help text excludes the descriptive sections."""
208
188
helptext = cmd.get_help_text()
209
self.assertEqualDiff('''\
210
Purpose: A sample command.
214
--usage Show usage message and options.
215
-q, --quiet Only display errors and warnings.
216
-v, --verbose Display more information.
217
-h, --help Show help message.
189
self.assertEqualDiff(
191
'Purpose: A sample command.\n'
195
' --usage Show usage message and options.\n'
196
' -v, --verbose Display more information.\n'
197
' -q, --quiet Only display errors and warnings.\n'
198
' -h, --help Show help message.\n'
229
208
helptext = cmd.get_help_text(verbose=False)
230
self.assertEqualDiff('''\
231
Purpose: A sample command.
235
--usage Show usage message and options.
236
-q, --quiet Only display errors and warnings.
237
-v, --verbose Display more information.
238
-h, --help Show help message.
240
See bzr help Demo for more details and examples.
245
def test_help_custom_section_ordering(self):
246
"""Custom descriptive sections should remain in the order given."""
247
class cmd_Demo(commands.Command):
254
Interesting stuff about formats.
262
Clever things to keep in mind.
265
helptext = cmd.get_help_text()
266
self.assertEqualDiff('''\
267
Purpose: A sample command.
271
--usage Show usage message and options.
272
-q, --quiet Only display errors and warnings.
273
-v, --verbose Display more information.
274
-h, --help Show help message.
280
Interesting stuff about formats.
288
Clever things to keep in mind.
293
def test_help_text_custom_usage(self):
294
"""Help text may contain a custom usage section."""
295
class cmd_Demo(commands.Command):
296
__doc__ = """A sample command.
306
helptext = cmd.get_help_text()
307
self.assertEqualDiff('''\
308
Purpose: A sample command.
316
--usage Show usage message and options.
317
-q, --quiet Only display errors and warnings.
318
-v, --verbose Display more information.
319
-h, --help Show help message.
328
class ZzzTranslationsForDoc(ZzzTranslations):
330
_section_pat = re.compile(':\w+:\\n\\s+')
331
_indent_pat = re.compile('\\s+')
334
m = self._section_pat.match(s)
336
m = self._indent_pat.match(s)
338
return u'%szz{{%s}}' % (m.group(0), s[m.end():])
339
return u'zz{{%s}}' % s
342
class TestCommandHelpI18n(tests.TestCase):
343
"""Tests for help on translated commands."""
346
super(TestCommandHelpI18n, self).setUp()
347
self.overrideAttr(i18n, '_translations', ZzzTranslationsForDoc())
349
def assertCmdHelp(self, expected, cmd):
350
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
352
def test_command_help_includes_see_also(self):
353
class cmd_WithSeeAlso(commands.Command):
354
__doc__ = """A sample command."""
355
_see_also = ['foo', 'bar']
356
self.assertCmdHelp('''\
357
zz{{:Purpose: zz{{A sample command.}}
358
}}zz{{:Usage: bzr WithSeeAlso
361
--usage zz{{Show usage message and options.}}
362
-q, --quiet zz{{Only display errors and warnings.}}
363
-v, --verbose zz{{Display more information.}}
364
-h, --help zz{{Show help message.}}
366
zz{{:See also: bar, foo}}
370
def test_get_help_text(self):
371
"""Commands have a get_help_text method which returns their help."""
372
class cmd_Demo(commands.Command):
373
__doc__ = """A sample command."""
374
self.assertCmdHelp('''\
375
zz{{:Purpose: zz{{A sample command.}}
376
}}zz{{:Usage: bzr Demo
379
--usage zz{{Show usage message and options.}}
380
-q, --quiet zz{{Only display errors and warnings.}}
381
-v, --verbose zz{{Display more information.}}
382
-h, --help zz{{Show help message.}}
387
def test_command_with_additional_see_also(self):
388
class cmd_WithSeeAlso(commands.Command):
389
__doc__ = """A sample command."""
390
_see_also = ['foo', 'bar']
391
cmd = cmd_WithSeeAlso()
392
helptext = cmd.get_help_text(['gam'])
395
-q, --quiet zz{{Only display errors and warnings.}}
396
-v, --verbose zz{{Display more information.}}
397
-h, --help zz{{Show help message.}}
399
zz{{:See also: bar, foo, gam}}
402
def test_command_only_additional_see_also(self):
403
class cmd_WithSeeAlso(commands.Command):
404
__doc__ = """A sample command."""
405
cmd = cmd_WithSeeAlso()
406
helptext = cmd.get_help_text(['gam'])
410
--usage zz{{Show usage message and options.}}
411
-q, --quiet zz{{Only display errors and warnings.}}
412
-v, --verbose zz{{Display more information.}}
413
-h, --help zz{{Show help message.}}
419
def test_help_custom_section_ordering(self):
420
"""Custom descriptive sections should remain in the order given."""
421
# The help formatter expect the class name to start with 'cmd_'
209
self.assertEquals(helptext,
210
'Purpose: A sample command.\n'
214
' --usage Show usage message and options.\n'
215
' -v, --verbose Display more information.\n'
216
' -q, --quiet Only display errors and warnings.\n'
217
' -h, --help Show help message.\n'
219
'See bzr help Demo for more details and examples.\n'
222
def test_help_custom_section_ordering(self):
223
"""Custom descriptive sections should remain in the order given."""
422
224
class cmd_Demo(commands.Command):
423
225
__doc__ = """A sample command.
477
self.assertCmdHelp('''\
478
zz{{:Purpose: zz{{A sample command.}}
480
zz{{cmd Demo [opts] args}}
486
--usage zz{{Show usage message and options.}}
487
-q, --quiet zz{{Only display errors and warnings.}}
488
-v, --verbose zz{{Display more information.}}
489
-h, --help zz{{Show help message.}}
492
zz{{zz{{Blah blah blah.}}
499
class TestHelp(tests.TestCase):
502
super(TestHelp, self).setUp()
503
commands.install_bzr_command_hooks()
281
helptext = cmd.get_help_text()
282
self.assertEquals(helptext,
283
'Purpose: A sample command.\n'
285
' cmd Demo [opts] args\n'
291
' --usage Show usage message and options.\n'
292
' -v, --verbose Display more information.\n'
293
' -q, --quiet Only display errors and warnings.\n'
294
' -h, --help Show help message.\n'
297
' Blah blah blah.\n\n')
506
300
class TestRegisteredTopic(TestHelp):
642
411
def test_default_search_path(self):
643
412
"""The default search path should include internal indexs."""
644
413
indices = help.HelpIndices()
645
self.assertEqual(4, len(indices.search_path))
414
self.assertEqual(3, len(indices.search_path))
646
415
# help topics should be searched in first.
647
416
self.assertIsInstance(indices.search_path[0],
648
help_topics.HelpTopicIndex)
417
help_topics.HelpTopicIndex)
649
418
# with commands being search second.
650
419
self.assertIsInstance(indices.search_path[1],
651
commands.HelpCommandIndex)
652
# plugins are a third index.
420
commands.HelpCommandIndex)
421
# and plugins are a third index.
653
422
self.assertIsInstance(indices.search_path[2],
654
plugin.PluginsHelpIndex)
655
# config options are a fourth index
656
self.assertIsInstance(indices.search_path[3],
657
help_topics.ConfigOptionHelpIndex)
423
plugin.PluginsHelpIndex)
659
425
def test_search_for_unknown_topic_raises(self):
660
426
"""Searching for an unknown topic should raise NoHelpTopic."""