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
-q, --quiet Only display errors and warnings.
54
-v, --verbose Display more information.
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
-q, --quiet Only display errors and warnings.
72
-v, --verbose Display more information.
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
' -q, --quiet Only display errors and warnings.\n'
94
' -v, --verbose Display more information.\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
' -q, --quiet Only display errors and warnings.\n'
107
' -v, --verbose Display more information.\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()
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.
166
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.
195
def test_concise_help_text(self):
196
"""Concise help text excludes the descriptive sections."""
197
class cmd_Demo(commands.Command):
198
__doc__ = """A sample command.
208
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.
229
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_'
422
class cmd_Demo(commands.Command):
423
__doc__ = """A sample command.
428
Interesting stuff about formats.
436
Clever things to keep in mind.
438
self.assertCmdHelp('''\
439
zz{{:Purpose: zz{{A sample command.}}
440
}}zz{{:Usage: bzr Demo
443
--usage zz{{Show usage message and options.}}
444
-q, --quiet zz{{Only display errors and warnings.}}
445
-v, --verbose zz{{Display more information.}}
446
-h, --help zz{{Show help message.}}
449
zz{{zz{{Blah blah blah.}}
452
zz{{Interesting stuff about formats.}}
460
zz{{Clever things to keep in mind.}}
465
def test_help_text_custom_usage(self):
466
"""Help text may contain a custom usage section."""
467
class cmd_Demo(commands.Command):
468
__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()
506
class TestRegisteredTopic(TestHelp):
507
"""Tests for the RegisteredTopic class."""
509
def test_contruct(self):
510
"""Construction takes the help topic name for the registered item."""
512
self.assertTrue('basic' in help_topics.topic_registry)
513
topic = help_topics.RegisteredTopic('basic')
514
self.assertEqual('basic', topic.topic)
516
def test_get_help_text(self):
517
"""RegisteredTopic returns the get_detail results for get_help_text."""
518
topic = help_topics.RegisteredTopic('commands')
519
self.assertEqual(help_topics.topic_registry.get_detail('commands'),
520
topic.get_help_text())
522
def test_get_help_text_with_additional_see_also(self):
523
topic = help_topics.RegisteredTopic('commands')
525
topic.get_help_text(['foo', 'bar']),
527
'See also: bar, foo\n')
529
def test_get_help_text_loaded_from_file(self):
530
# Pick a known topic stored in an external file
531
topic = help_topics.RegisteredTopic('authentication')
532
self.assertStartsWith(topic.get_help_text(),
533
'Authentication Settings\n'
534
'=======================\n'
537
def test_get_help_topic(self):
538
"""The help topic for RegisteredTopic is its topic from construction."""
539
topic = help_topics.RegisteredTopic('foobar')
540
self.assertEqual('foobar', topic.get_help_topic())
541
topic = help_topics.RegisteredTopic('baz')
542
self.assertEqual('baz', topic.get_help_topic())
545
class TestTopicIndex(TestHelp):
546
"""Tests for the HelpTopicIndex class."""
548
def test_default_constructable(self):
549
index = help_topics.HelpTopicIndex()
551
def test_get_topics_None(self):
552
"""Searching for None returns the basic help topic."""
553
index = help_topics.HelpTopicIndex()
554
topics = index.get_topics(None)
555
self.assertEqual(1, len(topics))
556
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
557
self.assertEqual('basic', topics[0].topic)
559
def test_get_topics_topics(self):
560
"""Searching for a string returns the matching string."""
561
index = help_topics.HelpTopicIndex()
562
topics = index.get_topics('topics')
563
self.assertEqual(1, len(topics))
564
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
565
self.assertEqual('topics', topics[0].topic)
567
def test_get_topics_no_topic(self):
568
"""Searching for something not registered returns []."""
569
index = help_topics.HelpTopicIndex()
570
self.assertEqual([], index.get_topics('nothing by this name'))
572
def test_prefix(self):
573
"""TopicIndex has a prefix of ''."""
574
index = help_topics.HelpTopicIndex()
575
self.assertEqual('', index.prefix)
578
class TestConfigOptionIndex(TestHelp):
579
"""Tests for the HelpCommandIndex class."""
582
super(TestConfigOptionIndex, self).setUp()
583
self.index = help_topics.ConfigOptionHelpIndex()
585
def test_get_topics_None(self):
586
"""Searching for None returns an empty list."""
587
self.assertEqual([], self.index.get_topics(None))
589
def test_get_topics_no_topic(self):
590
self.assertEqual([], self.index.get_topics('nothing by this name'))
592
def test_prefix(self):
593
self.assertEqual('configuration/', self.index.prefix)
595
def test_get_topic_with_prefix(self):
596
topics = self.index.get_topics('configuration/default_format')
597
self.assertLength(1, topics)
599
self.assertIsInstance(opt, config.Option)
600
self.assertEquals('default_format', opt.name)
603
class TestCommandIndex(TestHelp):
604
"""Tests for the HelpCommandIndex class."""
606
def test_default_constructable(self):
607
index = commands.HelpCommandIndex()
609
def test_get_topics_None(self):
610
"""Searching for None returns an empty list."""
611
index = commands.HelpCommandIndex()
612
self.assertEqual([], index.get_topics(None))
614
def test_get_topics_rocks(self):
615
"""Searching for 'rocks' returns the cmd_rocks command instance."""
616
index = commands.HelpCommandIndex()
617
topics = index.get_topics('rocks')
618
self.assertEqual(1, len(topics))
619
self.assertIsInstance(topics[0], builtins.cmd_rocks)
621
def test_get_topics_no_topic(self):
622
"""Searching for something that is not a command returns []."""
623
index = commands.HelpCommandIndex()
624
self.assertEqual([], index.get_topics('nothing by this name'))
626
def test_prefix(self):
627
"""CommandIndex has a prefix of 'commands/'."""
628
index = commands.HelpCommandIndex()
629
self.assertEqual('commands/', index.prefix)
631
def test_get_topic_with_prefix(self):
632
"""Searching for commands/rocks returns the rocks command object."""
633
index = commands.HelpCommandIndex()
634
topics = index.get_topics('commands/rocks')
635
self.assertEqual(1, len(topics))
636
self.assertIsInstance(topics[0], builtins.cmd_rocks)
639
class TestHelpIndices(tests.TestCase):
640
"""Tests for the HelpIndices class."""
642
def test_default_search_path(self):
643
"""The default search path should include internal indexs."""
644
indices = help.HelpIndices()
645
self.assertEqual(4, len(indices.search_path))
646
# help topics should be searched in first.
647
self.assertIsInstance(indices.search_path[0],
648
help_topics.HelpTopicIndex)
649
# with commands being search second.
650
self.assertIsInstance(indices.search_path[1],
651
commands.HelpCommandIndex)
652
# plugins are a third index.
653
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)
659
def test_search_for_unknown_topic_raises(self):
660
"""Searching for an unknown topic should raise NoHelpTopic."""
661
indices = help.HelpIndices()
662
indices.search_path = []
663
error = self.assertRaises(errors.NoHelpTopic, indices.search, 'foo')
664
self.assertEqual('foo', error.topic)
666
def test_search_calls_get_topic(self):
667
"""Searching should call get_topics in all indexes in order."""
669
class RecordingIndex(object):
670
def __init__(self, name):
672
def get_topics(self, topic):
673
calls.append(('get_topics', self.prefix, topic))
675
index = help.HelpIndices()
676
index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
680
('get_topics', '1', None),
681
('get_topics', '2', None),
688
('get_topics', '1', 'bar'),
689
('get_topics', '2', 'bar'),
693
def test_search_returns_index_and_results(self):
694
"""Searching should return help topics with their index"""
695
class CannedIndex(object):
696
def __init__(self, prefix, search_result):
698
self.result = search_result
699
def get_topics(self, topic):
701
index = help.HelpIndices()
702
index_one = CannedIndex('1', ['a'])
703
index_two = CannedIndex('2', ['b', 'c'])
704
index.search_path = [index_one, index_two]
705
self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
708
def test_search_checks_for_duplicate_prefixes(self):
709
"""Its an error when there are multiple indices with the same prefix."""
710
indices = help.HelpIndices()
711
indices.search_path = [help_topics.HelpTopicIndex(),
712
help_topics.HelpTopicIndex()]
713
self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)
added
removed
bzrlib/tests/test_help.py
