1
# Copyright (C) 2007-2012, 2016 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 breezy.help module."""
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.",
46
class TestCommandHelp(tests.TestCase):
47
"""Tests for help on commands."""
49
def assertCmdHelp(self, expected, cmd):
50
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
52
def test_command_help_includes_see_also(self):
53
class cmd_WithSeeAlso(commands.Command):
54
__doc__ = """A sample command."""
55
_see_also = ['foo', 'bar']
56
self.assertCmdHelp('''\
57
Purpose: A sample command.
58
Usage: brz WithSeeAlso
61
-h, --help Show help message.
62
-q, --quiet Only display errors and warnings.
63
--usage Show usage message and options.
64
-v, --verbose Display more information.
70
def test_get_help_text(self):
71
"""Commands have a get_help_text method which returns their help."""
72
class cmd_Demo(commands.Command):
73
__doc__ = """A sample command."""
74
self.assertCmdHelp('''\
75
Purpose: A sample command.
79
-h, --help Show help message.
80
-q, --quiet Only display errors and warnings.
81
--usage Show usage message and options.
82
-v, --verbose Display more information.
87
helptext = cmd.get_help_text()
88
self.assertStartsWith(helptext,
89
'Purpose: A sample command.\n'
91
self.assertEndsWith(helptext,
92
' -v, --verbose Display more information.\n\n')
94
def test_command_with_additional_see_also(self):
95
class cmd_WithSeeAlso(commands.Command):
96
__doc__ = """A sample command."""
97
_see_also = ['foo', 'bar']
98
cmd = cmd_WithSeeAlso()
99
helptext = cmd.get_help_text(['gam'])
102
' -h, --help Show help message.\n'
103
' -q, --quiet Only display errors and warnings.\n'
104
' --usage Show usage message and options.\n'
105
' -v, --verbose Display more information.\n'
107
'See also: bar, foo, gam\n')
109
def test_command_only_additional_see_also(self):
110
class cmd_WithSeeAlso(commands.Command):
111
__doc__ = """A sample command."""
112
cmd = cmd_WithSeeAlso()
113
helptext = cmd.get_help_text(['gam'])
116
' -v, --verbose Display more information.\n'
120
def test_get_help_topic(self):
121
"""The help topic for a Command is its name()."""
122
class cmd_foo_bar(commands.Command):
123
__doc__ = """A sample command."""
125
self.assertEqual(cmd.name(), cmd.get_help_topic())
127
def test_formatted_help_text(self):
128
"""Help text should be plain text by default."""
129
class cmd_Demo(commands.Command):
130
__doc__ = """A sample command.
141
A code block follows.
148
helptext = cmd.get_help_text()
149
self.assertEqualDiff('''\
150
Purpose: A sample command.
154
-h, --help Show help message.
155
-q, --quiet Only display errors and warnings.
156
--usage Show usage message and options.
157
-v, --verbose Display more information.
168
A code block follows.
174
helptext = cmd.get_help_text(plain=False)
175
self.assertEqualDiff('''\
176
:Purpose: A sample command.
180
-h, --help Show help message.
181
-q, --quiet Only display errors and warnings.
182
--usage Show usage message and options.
183
-v, --verbose Display more information.
194
A code block follows.
203
def test_concise_help_text(self):
204
"""Concise help text excludes the descriptive sections."""
205
class cmd_Demo(commands.Command):
206
__doc__ = """A sample command.
216
helptext = cmd.get_help_text()
217
self.assertEqualDiff('''\
218
Purpose: A sample command.
222
-h, --help Show help message.
223
-q, --quiet Only display errors and warnings.
224
--usage Show usage message and options.
225
-v, --verbose Display more information.
237
helptext = cmd.get_help_text(verbose=False)
238
self.assertEqualDiff('''\
239
Purpose: A sample command.
243
-h, --help Show help message.
244
-q, --quiet Only display errors and warnings.
245
--usage Show usage message and options.
246
-v, --verbose Display more information.
248
See brz help Demo for more details and examples.
253
def test_help_custom_section_ordering(self):
254
"""Custom descriptive sections should remain in the order given."""
255
class cmd_Demo(commands.Command):
262
Interesting stuff about formats.
270
Clever things to keep in mind.
273
helptext = cmd.get_help_text()
274
self.assertEqualDiff('''\
275
Purpose: A sample command.
279
-h, --help Show help message.
280
-q, --quiet Only display errors and warnings.
281
--usage Show usage message and options.
282
-v, --verbose Display more information.
288
Interesting stuff about formats.
296
Clever things to keep in mind.
301
def test_help_text_custom_usage(self):
302
"""Help text may contain a custom usage section."""
303
class cmd_Demo(commands.Command):
304
__doc__ = """A sample command.
314
helptext = cmd.get_help_text()
315
self.assertEqualDiff('''\
316
Purpose: A sample command.
324
-h, --help Show help message.
325
-q, --quiet Only display errors and warnings.
326
--usage Show usage message and options.
327
-v, --verbose Display more information.
336
class ZzzTranslationsForDoc(ZzzTranslations):
338
_section_pat = re.compile(':\\w+:\\n\\s+')
339
_indent_pat = re.compile('\\s+')
342
m = self._section_pat.match(s)
344
m = self._indent_pat.match(s)
346
return u'%szz{{%s}}' % (m.group(0), s[m.end():])
347
return u'zz{{%s}}' % s
350
class TestCommandHelpI18n(tests.TestCase):
351
"""Tests for help on translated commands."""
354
super(TestCommandHelpI18n, self).setUp()
355
self.overrideAttr(i18n, '_translations', ZzzTranslationsForDoc())
357
def assertCmdHelp(self, expected, cmd):
358
self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
360
def test_command_help_includes_see_also(self):
361
class cmd_WithSeeAlso(commands.Command):
362
__doc__ = """A sample command."""
363
_see_also = ['foo', 'bar']
364
self.assertCmdHelp('''\
365
zz{{:Purpose: zz{{A sample command.}}
366
}}zz{{:Usage: brz WithSeeAlso
369
-h, --help zz{{Show help message.}}
370
-q, --quiet zz{{Only display errors and warnings.}}
371
--usage zz{{Show usage message and options.}}
372
-v, --verbose zz{{Display more information.}}
374
zz{{:See also: bar, foo}}
378
def test_get_help_text(self):
379
"""Commands have a get_help_text method which returns their help."""
380
class cmd_Demo(commands.Command):
381
__doc__ = """A sample command."""
382
self.assertCmdHelp('''\
383
zz{{:Purpose: zz{{A sample command.}}
384
}}zz{{:Usage: brz Demo
387
-h, --help zz{{Show help message.}}
388
-q, --quiet zz{{Only display errors and warnings.}}
389
--usage zz{{Show usage message and options.}}
390
-v, --verbose zz{{Display more information.}}
395
def test_command_with_additional_see_also(self):
396
class cmd_WithSeeAlso(commands.Command):
397
__doc__ = """A sample command."""
398
_see_also = ['foo', 'bar']
399
cmd = cmd_WithSeeAlso()
400
helptext = cmd.get_help_text(['gam'])
403
-h, --help zz{{Show help message.}}
404
-q, --quiet zz{{Only display errors and warnings.}}
405
--usage zz{{Show usage message and options.}}
406
-v, --verbose zz{{Display more information.}}
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
-h, --help zz{{Show help message.}}
420
-q, --quiet zz{{Only display errors and warnings.}}
421
--usage zz{{Show usage message and options.}}
422
-v, --verbose zz{{Display more information.}}
427
def test_help_custom_section_ordering(self):
428
"""Custom descriptive sections should remain in the order given."""
429
# The help formatter expect the class name to start with 'cmd_'
430
class cmd_Demo(commands.Command):
431
__doc__ = """A sample command.
436
Interesting stuff about formats.
444
Clever things to keep in mind.
446
self.assertCmdHelp('''\
447
zz{{:Purpose: zz{{A sample command.}}
448
}}zz{{:Usage: brz Demo
451
-h, --help zz{{Show help message.}}
452
-q, --quiet zz{{Only display errors and warnings.}}
453
--usage zz{{Show usage message and options.}}
454
-v, --verbose zz{{Display more information.}}
457
zz{{zz{{Blah blah blah.}}
460
zz{{Interesting stuff about formats.}}
468
zz{{Clever things to keep in mind.}}
473
def test_help_text_custom_usage(self):
474
"""Help text may contain a custom usage section."""
475
class cmd_Demo(commands.Command):
476
__doc__ = """A sample command.
485
self.assertCmdHelp('''\
486
zz{{:Purpose: zz{{A sample command.}}
488
zz{{cmd Demo [opts] args}}
494
-h, --help zz{{Show help message.}}
495
-q, --quiet zz{{Only display errors and warnings.}}
496
--usage zz{{Show usage message and options.}}
497
-v, --verbose zz{{Display more information.}}
500
zz{{zz{{Blah blah blah.}}
507
class TestHelp(tests.TestCase):
510
super(TestHelp, self).setUp()
511
commands.install_bzr_command_hooks()
514
class TestRegisteredTopic(TestHelp):
515
"""Tests for the RegisteredTopic class."""
517
def test_contruct(self):
518
"""Construction takes the help topic name for the registered item."""
520
self.assertTrue('basic' in help_topics.topic_registry)
521
topic = help_topics.RegisteredTopic('basic')
522
self.assertEqual('basic', topic.topic)
524
def test_get_help_text(self):
525
"""RegisteredTopic returns the get_detail results for get_help_text."""
526
topic = help_topics.RegisteredTopic('commands')
527
self.assertEqual(help_topics.topic_registry.get_detail('commands'),
528
topic.get_help_text())
530
def test_get_help_text_with_additional_see_also(self):
531
topic = help_topics.RegisteredTopic('commands')
533
topic.get_help_text(['foo', 'bar']),
535
'See also: bar, foo\n')
537
def test_get_help_text_loaded_from_file(self):
538
# Pick a known topic stored in an external file
539
topic = help_topics.RegisteredTopic('authentication')
540
self.assertStartsWith(topic.get_help_text(),
541
'Authentication Settings\n'
542
'=======================\n'
545
def test_get_help_topic(self):
546
"""The help topic for RegisteredTopic is its topic from construction."""
547
topic = help_topics.RegisteredTopic('foobar')
548
self.assertEqual('foobar', topic.get_help_topic())
549
topic = help_topics.RegisteredTopic('baz')
550
self.assertEqual('baz', topic.get_help_topic())
553
class TestTopicIndex(TestHelp):
554
"""Tests for the HelpTopicIndex class."""
556
def test_default_constructable(self):
557
index = help_topics.HelpTopicIndex()
559
def test_get_topics_None(self):
560
"""Searching for None returns the basic help topic."""
561
index = help_topics.HelpTopicIndex()
562
topics = index.get_topics(None)
563
self.assertEqual(1, len(topics))
564
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
565
self.assertEqual('basic', topics[0].topic)
567
def test_get_topics_topics(self):
568
"""Searching for a string returns the matching string."""
569
index = help_topics.HelpTopicIndex()
570
topics = index.get_topics('topics')
571
self.assertEqual(1, len(topics))
572
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
573
self.assertEqual('topics', topics[0].topic)
575
def test_get_topics_no_topic(self):
576
"""Searching for something not registered returns []."""
577
index = help_topics.HelpTopicIndex()
578
self.assertEqual([], index.get_topics('nothing by this name'))
580
def test_prefix(self):
581
"""TopicIndex has a prefix of ''."""
582
index = help_topics.HelpTopicIndex()
583
self.assertEqual('', index.prefix)
586
class TestConfigOptionIndex(TestHelp):
587
"""Tests for the HelpCommandIndex class."""
590
super(TestConfigOptionIndex, self).setUp()
591
self.index = help_topics.ConfigOptionHelpIndex()
593
def test_get_topics_None(self):
594
"""Searching for None returns an empty list."""
595
self.assertEqual([], self.index.get_topics(None))
597
def test_get_topics_no_topic(self):
598
self.assertEqual([], self.index.get_topics('nothing by this name'))
600
def test_prefix(self):
601
self.assertEqual('configuration/', self.index.prefix)
603
def test_get_topic_with_prefix(self):
604
topics = self.index.get_topics('configuration/default_format')
605
self.assertLength(1, topics)
607
self.assertIsInstance(opt, config.Option)
608
self.assertEqual('default_format', opt.name)
611
class TestCommandIndex(TestHelp):
612
"""Tests for the HelpCommandIndex class."""
614
def test_default_constructable(self):
615
index = commands.HelpCommandIndex()
617
def test_get_topics_None(self):
618
"""Searching for None returns an empty list."""
619
index = commands.HelpCommandIndex()
620
self.assertEqual([], index.get_topics(None))
622
def test_get_topics_rocks(self):
623
"""Searching for 'rocks' returns the cmd_rocks command instance."""
624
index = commands.HelpCommandIndex()
625
topics = index.get_topics('rocks')
626
self.assertEqual(1, len(topics))
627
self.assertIsInstance(topics[0], builtins.cmd_rocks)
629
def test_get_topics_no_topic(self):
630
"""Searching for something that is not a command returns []."""
631
index = commands.HelpCommandIndex()
632
self.assertEqual([], index.get_topics('nothing by this name'))
634
def test_prefix(self):
635
"""CommandIndex has a prefix of 'commands/'."""
636
index = commands.HelpCommandIndex()
637
self.assertEqual('commands/', index.prefix)
639
def test_get_topic_with_prefix(self):
640
"""Searching for commands/rocks returns the rocks command object."""
641
index = commands.HelpCommandIndex()
642
topics = index.get_topics('commands/rocks')
643
self.assertEqual(1, len(topics))
644
self.assertIsInstance(topics[0], builtins.cmd_rocks)
647
class TestHelpIndices(tests.TestCase):
648
"""Tests for the HelpIndices class."""
650
def test_default_search_path(self):
651
"""The default search path should include internal indexs."""
652
indices = help.HelpIndices()
653
self.assertEqual(4, len(indices.search_path))
654
# help topics should be searched in first.
655
self.assertIsInstance(indices.search_path[0],
656
help_topics.HelpTopicIndex)
657
# with commands being search second.
658
self.assertIsInstance(indices.search_path[1],
659
commands.HelpCommandIndex)
660
# plugins are a third index.
661
self.assertIsInstance(indices.search_path[2],
662
plugin.PluginsHelpIndex)
663
# config options are a fourth index
664
self.assertIsInstance(indices.search_path[3],
665
help_topics.ConfigOptionHelpIndex)
667
def test_search_for_unknown_topic_raises(self):
668
"""Searching for an unknown topic should raise NoHelpTopic."""
669
indices = help.HelpIndices()
670
indices.search_path = []
671
error = self.assertRaises(help.NoHelpTopic, indices.search, 'foo')
672
self.assertEqual('foo', error.topic)
674
def test_search_calls_get_topic(self):
675
"""Searching should call get_topics in all indexes in order."""
678
class RecordingIndex(object):
679
def __init__(self, name):
682
def get_topics(self, topic):
683
calls.append(('get_topics', self.prefix, topic))
685
index = help.HelpIndices()
686
index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
690
('get_topics', '1', None),
691
('get_topics', '2', None),
698
('get_topics', '1', 'bar'),
699
('get_topics', '2', 'bar'),
703
def test_search_returns_index_and_results(self):
704
"""Searching should return help topics with their index"""
705
class CannedIndex(object):
706
def __init__(self, prefix, search_result):
708
self.result = search_result
710
def get_topics(self, topic):
712
index = help.HelpIndices()
713
index_one = CannedIndex('1', ['a'])
714
index_two = CannedIndex('2', ['b', 'c'])
715
index.search_path = [index_one, index_two]
716
self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
719
def test_search_checks_for_duplicate_prefixes(self):
720
"""Its an error when there are multiple indices with the same prefix."""
721
indices = help.HelpIndices()
722
indices.search_path = [help_topics.HelpTopicIndex(),
723
help_topics.HelpTopicIndex()]
724
self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)
added
removed
breezy/tests/test_help.py
