14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
"""Unit tests for the bzrlib.help module."""
19
from cStringIO import StringIO
17
"""Unit tests for the breezy.help module."""
32
class TestHelp(tests.TestCase):
35
tests.TestCase.setUp(self)
36
commands.install_bzr_command_hooks()
33
from .test_i18n import ZzzTranslations
37
class TestErrors(tests.TestCase):
39
def test_no_help_topic(self):
40
error = help.NoHelpTopic("topic")
41
self.assertEqualDiff("No help could be found for 'topic'. "
42
"Please use 'brz help topics' to obtain a list of topics.",
39
46
class TestCommandHelp(tests.TestCase):
40
47
"""Tests for help on commands."""
49
def assertCmdHelp(self, expected, cmd):
50
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
42
52
def test_command_help_includes_see_also(self):
43
53
class cmd_WithSeeAlso(commands.Command):
44
54
__doc__ = """A sample command."""
45
55
_see_also = ['foo', 'bar']
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')
56
self.assertCmdHelp('''\
57
Purpose: A sample command.
58
Usage: brz WithSeeAlso
61
--usage Show usage message and options.
62
-q, --quiet Only display errors and warnings.
63
-v, --verbose Display more information.
64
-h, --help Show help message.
56
70
def test_get_help_text(self):
57
71
"""Commands have a get_help_text method which returns their help."""
58
72
class cmd_Demo(commands.Command):
59
73
__doc__ = """A sample command."""
74
self.assertCmdHelp('''\
75
Purpose: A sample command.
79
--usage Show usage message and options.
80
-q, --quiet Only display errors and warnings.
81
-v, --verbose Display more information.
82
-h, --help Show help message.
61
87
helptext = cmd.get_help_text()
62
88
self.assertStartsWith(helptext,
63
89
'Purpose: A sample command.\n'
65
91
self.assertEndsWith(helptext,
66
92
' -h, --help Show help message.\n\n')
142
A code block follows.
117
149
helptext = cmd.get_help_text()
120
'Purpose: A sample command.\n'
124
' --usage Show usage message and options.\n'
125
' -v, --verbose Display more information.\n'
126
' -q, --quiet Only display errors and warnings.\n'
127
' -h, --help Show help message.\n'
150
self.assertEqualDiff('''\
151
Purpose: A sample command.
155
--usage Show usage message and options.
156
-q, --quiet Only display errors and warnings.
157
-v, --verbose Display more information.
158
-h, --help Show help message.
169
A code block follows.
138
175
helptext = cmd.get_help_text(plain=False)
139
self.assertEquals(helptext,
140
':Purpose: A sample command.\n'
144
' --usage Show usage message and options.\n'
145
' -v, --verbose Display more information.\n'
146
' -q, --quiet Only display errors and warnings.\n'
147
' -h, --help Show help message.\n'
176
self.assertEqualDiff('''\
177
:Purpose: A sample command.
181
--usage Show usage message and options.
182
-q, --quiet Only display errors and warnings.
183
-v, --verbose Display more information.
184
-h, --help Show help message.
195
A code block follows.
159
204
def test_concise_help_text(self):
160
205
"""Concise help text excludes the descriptive sections."""
172
217
helptext = cmd.get_help_text()
173
self.assertEqualDiff(
175
'Purpose: A sample command.\n'
179
' --usage Show usage message and options.\n'
180
' -v, --verbose Display more information.\n'
181
' -q, --quiet Only display errors and warnings.\n'
182
' -h, --help Show help message.\n'
218
self.assertEqualDiff('''\
219
Purpose: A sample command.
223
--usage Show usage message and options.
224
-q, --quiet Only display errors and warnings.
225
-v, --verbose Display more information.
226
-h, --help Show help message.
192
238
helptext = cmd.get_help_text(verbose=False)
193
self.assertEquals(helptext,
194
'Purpose: A sample command.\n'
198
' --usage Show usage message and options.\n'
199
' -v, --verbose Display more information.\n'
200
' -q, --quiet Only display errors and warnings.\n'
201
' -h, --help Show help message.\n'
203
'See bzr help Demo for more details and examples.\n'
206
def test_help_custom_section_ordering(self):
207
"""Custom descriptive sections should remain in the order given."""
239
self.assertEqualDiff('''\
240
Purpose: A sample command.
244
--usage Show usage message and options.
245
-q, --quiet Only display errors and warnings.
246
-v, --verbose Display more information.
247
-h, --help Show help message.
249
See brz help Demo for more details and examples.
254
def test_help_custom_section_ordering(self):
255
"""Custom descriptive sections should remain in the order given."""
256
class cmd_Demo(commands.Command):
263
Interesting stuff about formats.
271
Clever things to keep in mind.
274
helptext = cmd.get_help_text()
275
self.assertEqualDiff('''\
276
Purpose: A sample command.
280
--usage Show usage message and options.
281
-q, --quiet Only display errors and warnings.
282
-v, --verbose Display more information.
283
-h, --help Show help message.
289
Interesting stuff about formats.
297
Clever things to keep in mind.
302
def test_help_text_custom_usage(self):
303
"""Help text may contain a custom usage section."""
304
class cmd_Demo(commands.Command):
305
__doc__ = """A sample command.
315
helptext = cmd.get_help_text()
316
self.assertEqualDiff('''\
317
Purpose: A sample command.
325
--usage Show usage message and options.
326
-q, --quiet Only display errors and warnings.
327
-v, --verbose Display more information.
328
-h, --help Show help message.
337
class ZzzTranslationsForDoc(ZzzTranslations):
339
_section_pat = re.compile(':\\w+:\\n\\s+')
340
_indent_pat = re.compile('\\s+')
343
m = self._section_pat.match(s)
345
m = self._indent_pat.match(s)
347
return u'%szz{{%s}}' % (m.group(0), s[m.end():])
348
return u'zz{{%s}}' % s
351
class TestCommandHelpI18n(tests.TestCase):
352
"""Tests for help on translated commands."""
355
super(TestCommandHelpI18n, self).setUp()
356
self.overrideAttr(i18n, '_translations', ZzzTranslationsForDoc())
358
def assertCmdHelp(self, expected, cmd):
359
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
361
def test_command_help_includes_see_also(self):
362
class cmd_WithSeeAlso(commands.Command):
363
__doc__ = """A sample command."""
364
_see_also = ['foo', 'bar']
365
self.assertCmdHelp('''\
366
zz{{:Purpose: zz{{A sample command.}}
367
}}zz{{:Usage: brz WithSeeAlso
370
--usage zz{{Show usage message and options.}}
371
-q, --quiet zz{{Only display errors and warnings.}}
372
-v, --verbose zz{{Display more information.}}
373
-h, --help zz{{Show help message.}}
375
zz{{:See also: bar, foo}}
379
def test_get_help_text(self):
380
"""Commands have a get_help_text method which returns their help."""
381
class cmd_Demo(commands.Command):
382
__doc__ = """A sample command."""
383
self.assertCmdHelp('''\
384
zz{{:Purpose: zz{{A sample command.}}
385
}}zz{{:Usage: brz Demo
388
--usage zz{{Show usage message and options.}}
389
-q, --quiet zz{{Only display errors and warnings.}}
390
-v, --verbose zz{{Display more information.}}
391
-h, --help zz{{Show help message.}}
396
def test_command_with_additional_see_also(self):
397
class cmd_WithSeeAlso(commands.Command):
398
__doc__ = """A sample command."""
399
_see_also = ['foo', 'bar']
400
cmd = cmd_WithSeeAlso()
401
helptext = cmd.get_help_text(['gam'])
404
-q, --quiet zz{{Only display errors and warnings.}}
405
-v, --verbose zz{{Display more information.}}
406
-h, --help zz{{Show help message.}}
408
zz{{:See also: bar, foo, gam}}
411
def test_command_only_additional_see_also(self):
412
class cmd_WithSeeAlso(commands.Command):
413
__doc__ = """A sample command."""
414
cmd = cmd_WithSeeAlso()
415
helptext = cmd.get_help_text(['gam'])
419
--usage zz{{Show usage message and options.}}
420
-q, --quiet zz{{Only display errors and warnings.}}
421
-v, --verbose zz{{Display more information.}}
422
-h, --help zz{{Show help message.}}
428
def test_help_custom_section_ordering(self):
429
"""Custom descriptive sections should remain in the order given."""
430
# The help formatter expect the class name to start with 'cmd_'
208
431
class cmd_Demo(commands.Command):
209
432
__doc__ = """A sample command.
265
helptext = cmd.get_help_text()
266
self.assertEquals(helptext,
267
'Purpose: A sample command.\n'
269
' cmd Demo [opts] args\n'
275
' --usage Show usage message and options.\n'
276
' -v, --verbose Display more information.\n'
277
' -q, --quiet Only display errors and warnings.\n'
278
' -h, --help Show help message.\n'
281
' Blah blah blah.\n\n')
486
self.assertCmdHelp('''\
487
zz{{:Purpose: zz{{A sample command.}}
489
zz{{cmd Demo [opts] args}}
495
--usage zz{{Show usage message and options.}}
496
-q, --quiet zz{{Only display errors and warnings.}}
497
-v, --verbose zz{{Display more information.}}
498
-h, --help zz{{Show help message.}}
501
zz{{zz{{Blah blah blah.}}
508
class TestHelp(tests.TestCase):
511
super(TestHelp, self).setUp()
512
commands.install_bzr_command_hooks()
284
515
class TestRegisteredTopic(TestHelp):
395
651
def test_default_search_path(self):
396
652
"""The default search path should include internal indexs."""
397
653
indices = help.HelpIndices()
398
self.assertEqual(3, len(indices.search_path))
654
self.assertEqual(4, len(indices.search_path))
399
655
# help topics should be searched in first.
400
656
self.assertIsInstance(indices.search_path[0],
401
help_topics.HelpTopicIndex)
657
help_topics.HelpTopicIndex)
402
658
# with commands being search second.
403
659
self.assertIsInstance(indices.search_path[1],
404
commands.HelpCommandIndex)
405
# and plugins are a third index.
660
commands.HelpCommandIndex)
661
# plugins are a third index.
406
662
self.assertIsInstance(indices.search_path[2],
407
plugin.PluginsHelpIndex)
663
plugin.PluginsHelpIndex)
664
# config options are a fourth index
665
self.assertIsInstance(indices.search_path[3],
666
help_topics.ConfigOptionHelpIndex)
409
668
def test_search_for_unknown_topic_raises(self):
410
669
"""Searching for an unknown topic should raise NoHelpTopic."""
411
670
indices = help.HelpIndices()
412
671
indices.search_path = []
413
error = self.assertRaises(errors.NoHelpTopic, indices.search, 'foo')
672
error = self.assertRaises(help.NoHelpTopic, indices.search, 'foo')
414
673
self.assertEqual('foo', error.topic)
416
675
def test_search_calls_get_topic(self):