1
# Copyright (C) 2007-2011 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
"""Unit tests for the bzrlib.help module."""
33
from bzrlib.tests.test_i18n import ZzzTranslations
37
class TestCommandHelp(tests.TestCase):
38
"""Tests for help on commands."""
40
def assertCmdHelp(self, expected, cmd):
41
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
43
def test_command_help_includes_see_also(self):
44
class cmd_WithSeeAlso(commands.Command):
45
__doc__ = """A sample command."""
46
_see_also = ['foo', 'bar']
47
self.assertCmdHelp('''\
48
Purpose: A sample command.
49
Usage: bzr WithSeeAlso
52
--usage Show usage message and options.
53
-v, --verbose Display more information.
54
-q, --quiet Only display errors and warnings.
55
-h, --help Show help message.
61
def test_get_help_text(self):
62
"""Commands have a get_help_text method which returns their help."""
63
class cmd_Demo(commands.Command):
64
__doc__ = """A sample command."""
65
self.assertCmdHelp('''\
66
Purpose: A sample command.
70
--usage Show usage message and options.
71
-v, --verbose Display more information.
72
-q, --quiet Only display errors and warnings.
73
-h, --help Show help message.
78
helptext = cmd.get_help_text()
79
self.assertStartsWith(helptext,
80
'Purpose: A sample command.\n'
82
self.assertEndsWith(helptext,
83
' -h, --help Show help message.\n\n')
85
def test_command_with_additional_see_also(self):
86
class cmd_WithSeeAlso(commands.Command):
87
__doc__ = """A sample command."""
88
_see_also = ['foo', 'bar']
89
cmd = cmd_WithSeeAlso()
90
helptext = cmd.get_help_text(['gam'])
93
' -v, --verbose Display more information.\n'
94
' -q, --quiet Only display errors and warnings.\n'
95
' -h, --help Show help message.\n'
97
'See also: bar, foo, gam\n')
99
def test_command_only_additional_see_also(self):
100
class cmd_WithSeeAlso(commands.Command):
101
__doc__ = """A sample command."""
102
cmd = cmd_WithSeeAlso()
103
helptext = cmd.get_help_text(['gam'])
106
' -v, --verbose Display more information.\n'
107
' -q, --quiet Only display errors and warnings.\n'
108
' -h, --help Show help message.\n'
112
def test_get_help_topic(self):
113
"""The help topic for a Command is its name()."""
114
class cmd_foo_bar(commands.Command):
115
__doc__ = """A sample command."""
117
self.assertEqual(cmd.name(), cmd.get_help_topic())
119
def test_formatted_help_text(self):
120
"""Help text should be plain text by default."""
121
class cmd_Demo(commands.Command):
122
__doc__ = """A sample command.
133
A code block follows.
140
helptext = cmd.get_help_text()
143
'Purpose: A sample command.\n'
147
' --usage Show usage message and options.\n'
148
' -v, --verbose Display more information.\n'
149
' -q, --quiet Only display errors and warnings.\n'
150
' -h, --help Show help message.\n'
161
' A code block follows.\n'
163
' bzr Demo something\n'
165
helptext = cmd.get_help_text(plain=False)
166
self.assertEquals(helptext,
167
':Purpose: A sample command.\n'
171
' --usage Show usage message and options.\n'
172
' -v, --verbose Display more information.\n'
173
' -q, --quiet Only display errors and warnings.\n'
174
' -h, --help Show help message.\n'
185
' A code block follows.\n'
189
' bzr Demo something\n'
192
def test_concise_help_text(self):
193
"""Concise help text excludes the descriptive sections."""
194
class cmd_Demo(commands.Command):
195
__doc__ = """A sample command.
205
helptext = cmd.get_help_text()
206
self.assertEqualDiff(
208
'Purpose: A sample command.\n'
212
' --usage Show usage message and options.\n'
213
' -v, --verbose Display more information.\n'
214
' -q, --quiet Only display errors and warnings.\n'
215
' -h, --help Show help message.\n'
225
helptext = cmd.get_help_text(verbose=False)
226
self.assertEquals(helptext,
227
'Purpose: A sample command.\n'
231
' --usage Show usage message and options.\n'
232
' -v, --verbose Display more information.\n'
233
' -q, --quiet Only display errors and warnings.\n'
234
' -h, --help Show help message.\n'
236
'See bzr help Demo for more details and examples.\n'
239
def test_help_custom_section_ordering(self):
240
"""Custom descriptive sections should remain in the order given."""
241
class cmd_Demo(commands.Command):
242
__doc__ = """A sample command.
247
Interesting stuff about formats.
255
Clever things to keep in mind.
258
helptext = cmd.get_help_text()
259
self.assertEqualDiff(
261
'Purpose: A sample command.\n'
265
' --usage Show usage message and options.\n'
266
' -v, --verbose Display more information.\n'
267
' -q, --quiet Only display errors and warnings.\n'
268
' -h, --help Show help message.\n'
274
' Interesting stuff about formats.\n'
282
' Clever things to keep in mind.\n'
285
def test_help_text_custom_usage(self):
286
"""Help text may contain a custom usage section."""
287
class cmd_Demo(commands.Command):
288
__doc__ = """A sample command.
298
helptext = cmd.get_help_text()
299
self.assertEquals(helptext,
300
'Purpose: A sample command.\n'
302
' cmd Demo [opts] args\n'
308
' --usage Show usage message and options.\n'
309
' -v, --verbose Display more information.\n'
310
' -q, --quiet Only display errors and warnings.\n'
311
' -h, --help Show help message.\n'
314
' Blah blah blah.\n\n')
317
class ZzzTranslationsForDoc(ZzzTranslations):
319
_section_pat = re.compile(':\w+:\\n\\s+')
320
_indent_pat = re.compile('\\s+')
323
m = self._section_pat.match(s)
325
m = self._indent_pat.match(s)
327
return u'%szz{{%s}}' % (m.group(0), s[m.end():])
328
return u'zz{{%s}}' % s
331
class TestCommandHelpI18n(tests.TestCase):
332
"""Tests for help on translated commands."""
335
super(TestCommandHelpI18n, self).setUp()
336
self.overrideAttr(i18n, '_translations', ZzzTranslationsForDoc())
338
def assertCmdHelp(self, expected, cmd):
339
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
341
def test_command_help_includes_see_also(self):
342
class cmd_WithSeeAlso(commands.Command):
343
__doc__ = """A sample command."""
344
_see_also = ['foo', 'bar']
345
self.assertCmdHelp('''\
346
zz{{:Purpose: zz{{A sample command.}}
347
}}zz{{:Usage: bzr WithSeeAlso
350
--usage zz{{Show usage message and options.}}
351
-v, --verbose zz{{Display more information.}}
352
-q, --quiet zz{{Only display errors and warnings.}}
353
-h, --help zz{{Show help message.}}
355
zz{{:See also: bar, foo}}
359
def test_get_help_text(self):
360
"""Commands have a get_help_text method which returns their help."""
361
class cmd_Demo(commands.Command):
362
__doc__ = """A sample command."""
363
self.assertCmdHelp('''\
364
zz{{:Purpose: zz{{A sample command.}}
365
}}zz{{:Usage: bzr Demo
368
--usage zz{{Show usage message and options.}}
369
-v, --verbose zz{{Display more information.}}
370
-q, --quiet zz{{Only display errors and warnings.}}
371
-h, --help zz{{Show help message.}}
376
def test_command_with_additional_see_also(self):
377
class cmd_WithSeeAlso(commands.Command):
378
__doc__ = """A sample command."""
379
_see_also = ['foo', 'bar']
380
cmd = cmd_WithSeeAlso()
381
helptext = cmd.get_help_text(['gam'])
384
' -v, --verbose zz{{Display more information.}}\n'
385
' -q, --quiet zz{{Only display errors and warnings.}}\n'
386
' -h, --help zz{{Show help message.}}\n'
388
'zz{{:See also: bar, foo, gam}}\n')
390
def test_command_only_additional_see_also(self):
391
class cmd_WithSeeAlso(commands.Command):
392
__doc__ = """A sample command."""
393
cmd = cmd_WithSeeAlso()
394
helptext = cmd.get_help_text(['gam'])
398
' --usage zz{{Show usage message and options.}}\n'
399
' -v, --verbose zz{{Display more information.}}\n'
400
' -q, --quiet zz{{Only display errors and warnings.}}\n'
401
' -h, --help zz{{Show help message.}}\n'
403
'zz{{:See also: gam}}\n')
406
def test_help_custom_section_ordering(self):
407
"""Custom descriptive sections should remain in the order given."""
408
# The help formatter expect the class name to start with 'cmd_'
409
class cmd_Demo(commands.Command):
410
__doc__ = """A sample command.
415
Interesting stuff about formats.
423
Clever things to keep in mind.
425
self.assertCmdHelp('''\
426
zz{{:Purpose: zz{{A sample command.}}
427
}}zz{{:Usage: bzr Demo
430
--usage zz{{Show usage message and options.}}
431
-v, --verbose zz{{Display more information.}}
432
-q, --quiet zz{{Only display errors and warnings.}}
433
-h, --help zz{{Show help message.}}
436
zz{{zz{{Blah blah blah.}}
439
zz{{Interesting stuff about formats.}}
447
zz{{Clever things to keep in mind.}}
452
def test_help_text_custom_usage(self):
453
"""Help text may contain a custom usage section."""
454
class cmd_Demo(commands.Command):
455
__doc__ = """A sample command.
464
self.assertCmdHelp('''\
465
zz{{:Purpose: zz{{A sample command.}}
467
zz{{cmd Demo [opts] args}}
473
--usage zz{{Show usage message and options.}}
474
-v, --verbose zz{{Display more information.}}
475
-q, --quiet zz{{Only display errors and warnings.}}
476
-h, --help zz{{Show help message.}}
479
zz{{zz{{Blah blah blah.}}
486
class TestHelp(tests.TestCase):
489
tests.TestCase.setUp(self)
490
commands.install_bzr_command_hooks()
493
class TestRegisteredTopic(TestHelp):
494
"""Tests for the RegisteredTopic class."""
496
def test_contruct(self):
497
"""Construction takes the help topic name for the registered item."""
499
self.assertTrue('basic' in help_topics.topic_registry)
500
topic = help_topics.RegisteredTopic('basic')
501
self.assertEqual('basic', topic.topic)
503
def test_get_help_text(self):
504
"""RegisteredTopic returns the get_detail results for get_help_text."""
505
topic = help_topics.RegisteredTopic('commands')
506
self.assertEqual(help_topics.topic_registry.get_detail('commands'),
507
topic.get_help_text())
509
def test_get_help_text_with_additional_see_also(self):
510
topic = help_topics.RegisteredTopic('commands')
512
topic.get_help_text(['foo', 'bar']),
514
'See also: bar, foo\n')
516
def test_get_help_text_loaded_from_file(self):
517
# Pick a known topic stored in an external file
518
topic = help_topics.RegisteredTopic('authentication')
519
self.assertStartsWith(topic.get_help_text(),
520
'Authentication Settings\n'
521
'=======================\n'
524
def test_get_help_topic(self):
525
"""The help topic for RegisteredTopic is its topic from construction."""
526
topic = help_topics.RegisteredTopic('foobar')
527
self.assertEqual('foobar', topic.get_help_topic())
528
topic = help_topics.RegisteredTopic('baz')
529
self.assertEqual('baz', topic.get_help_topic())
532
class TestTopicIndex(TestHelp):
533
"""Tests for the HelpTopicIndex class."""
535
def test_default_constructable(self):
536
index = help_topics.HelpTopicIndex()
538
def test_get_topics_None(self):
539
"""Searching for None returns the basic help topic."""
540
index = help_topics.HelpTopicIndex()
541
topics = index.get_topics(None)
542
self.assertEqual(1, len(topics))
543
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
544
self.assertEqual('basic', topics[0].topic)
546
def test_get_topics_topics(self):
547
"""Searching for a string returns the matching string."""
548
index = help_topics.HelpTopicIndex()
549
topics = index.get_topics('topics')
550
self.assertEqual(1, len(topics))
551
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
552
self.assertEqual('topics', topics[0].topic)
554
def test_get_topics_no_topic(self):
555
"""Searching for something not registered returns []."""
556
index = help_topics.HelpTopicIndex()
557
self.assertEqual([], index.get_topics('nothing by this name'))
559
def test_prefix(self):
560
"""TopicIndex has a prefix of ''."""
561
index = help_topics.HelpTopicIndex()
562
self.assertEqual('', index.prefix)
565
class TestConfigOptionIndex(TestHelp):
566
"""Tests for the HelpCommandIndex class."""
569
super(TestConfigOptionIndex, self).setUp()
570
self.index = help_topics.ConfigOptionHelpIndex()
572
def test_get_topics_None(self):
573
"""Searching for None returns an empty list."""
574
self.assertEqual([], self.index.get_topics(None))
576
def test_get_topics_no_topic(self):
577
self.assertEqual([], self.index.get_topics('nothing by this name'))
579
def test_prefix(self):
580
self.assertEqual('configuration/', self.index.prefix)
582
def test_get_topic_with_prefix(self):
583
topics = self.index.get_topics('configuration/default_format')
584
self.assertLength(1, topics)
586
self.assertIsInstance(opt, config.Option)
587
self.assertEquals('default_format', opt.name)
590
class TestCommandIndex(TestHelp):
591
"""Tests for the HelpCommandIndex class."""
593
def test_default_constructable(self):
594
index = commands.HelpCommandIndex()
596
def test_get_topics_None(self):
597
"""Searching for None returns an empty list."""
598
index = commands.HelpCommandIndex()
599
self.assertEqual([], index.get_topics(None))
601
def test_get_topics_rocks(self):
602
"""Searching for 'rocks' returns the cmd_rocks command instance."""
603
index = commands.HelpCommandIndex()
604
topics = index.get_topics('rocks')
605
self.assertEqual(1, len(topics))
606
self.assertIsInstance(topics[0], builtins.cmd_rocks)
608
def test_get_topics_no_topic(self):
609
"""Searching for something that is not a command returns []."""
610
index = commands.HelpCommandIndex()
611
self.assertEqual([], index.get_topics('nothing by this name'))
613
def test_prefix(self):
614
"""CommandIndex has a prefix of 'commands/'."""
615
index = commands.HelpCommandIndex()
616
self.assertEqual('commands/', index.prefix)
618
def test_get_topic_with_prefix(self):
619
"""Searching for commands/rocks returns the rocks command object."""
620
index = commands.HelpCommandIndex()
621
topics = index.get_topics('commands/rocks')
622
self.assertEqual(1, len(topics))
623
self.assertIsInstance(topics[0], builtins.cmd_rocks)
626
class TestHelpIndices(tests.TestCase):
627
"""Tests for the HelpIndices class."""
629
def test_default_search_path(self):
630
"""The default search path should include internal indexs."""
631
indices = help.HelpIndices()
632
self.assertEqual(4, len(indices.search_path))
633
# help topics should be searched in first.
634
self.assertIsInstance(indices.search_path[0],
635
help_topics.HelpTopicIndex)
636
# with commands being search second.
637
self.assertIsInstance(indices.search_path[1],
638
commands.HelpCommandIndex)
639
# plugins are a third index.
640
self.assertIsInstance(indices.search_path[2],
641
plugin.PluginsHelpIndex)
642
# config options are a fourth index
643
self.assertIsInstance(indices.search_path[3],
644
help_topics.ConfigOptionHelpIndex)
646
def test_search_for_unknown_topic_raises(self):
647
"""Searching for an unknown topic should raise NoHelpTopic."""
648
indices = help.HelpIndices()
649
indices.search_path = []
650
error = self.assertRaises(errors.NoHelpTopic, indices.search, 'foo')
651
self.assertEqual('foo', error.topic)
653
def test_search_calls_get_topic(self):
654
"""Searching should call get_topics in all indexes in order."""
656
class RecordingIndex(object):
657
def __init__(self, name):
659
def get_topics(self, topic):
660
calls.append(('get_topics', self.prefix, topic))
662
index = help.HelpIndices()
663
index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
667
('get_topics', '1', None),
668
('get_topics', '2', None),
675
('get_topics', '1', 'bar'),
676
('get_topics', '2', 'bar'),
680
def test_search_returns_index_and_results(self):
681
"""Searching should return help topics with their index"""
682
class CannedIndex(object):
683
def __init__(self, prefix, search_result):
685
self.result = search_result
686
def get_topics(self, topic):
688
index = help.HelpIndices()
689
index_one = CannedIndex('1', ['a'])
690
index_two = CannedIndex('2', ['b', 'c'])
691
index.search_path = [index_one, index_two]
692
self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
695
def test_search_checks_for_duplicate_prefixes(self):
696
"""Its an error when there are multiple indices with the same prefix."""
697
indices = help.HelpIndices()
698
indices.search_path = [help_topics.HelpTopicIndex(),
699
help_topics.HelpTopicIndex()]
700
self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)
added
removed
bzrlib/tests/test_help.py
