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
--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.
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
--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.
87
helptext = cmd.get_help_text()
88
self.assertStartsWith(helptext,
89
'Purpose: A sample command.\n'
91
self.assertEndsWith(helptext,
92
' -h, --help Show help message.\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
' -q, --quiet Only display errors and warnings.\n'
103
' -v, --verbose Display more information.\n'
104
' -h, --help Show help message.\n'
106
'See also: bar, foo, gam\n')
108
def test_command_only_additional_see_also(self):
109
class cmd_WithSeeAlso(commands.Command):
110
__doc__ = """A sample command."""
111
cmd = cmd_WithSeeAlso()
112
helptext = cmd.get_help_text(['gam'])
115
' -q, --quiet Only display errors and warnings.\n'
116
' -v, --verbose Display more information.\n'
117
' -h, --help Show help message.\n'
121
def test_get_help_topic(self):
122
"""The help topic for a Command is its name()."""
123
class cmd_foo_bar(commands.Command):
124
__doc__ = """A sample command."""
126
self.assertEqual(cmd.name(), cmd.get_help_topic())
128
def test_formatted_help_text(self):
129
"""Help text should be plain text by default."""
130
class cmd_Demo(commands.Command):
131
__doc__ = """A sample command.
142
A code block follows.
149
helptext = cmd.get_help_text()
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.
175
helptext = cmd.get_help_text(plain=False)
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.
204
def test_concise_help_text(self):
205
"""Concise help text excludes the descriptive sections."""
206
class cmd_Demo(commands.Command):
207
__doc__ = """A sample command.
217
helptext = cmd.get_help_text()
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.
238
helptext = cmd.get_help_text(verbose=False)
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_'
431
class cmd_Demo(commands.Command):
432
__doc__ = """A sample command.
437
Interesting stuff about formats.
445
Clever things to keep in mind.
447
self.assertCmdHelp('''\
448
zz{{:Purpose: zz{{A sample command.}}
449
}}zz{{:Usage: brz Demo
452
--usage zz{{Show usage message and options.}}
453
-q, --quiet zz{{Only display errors and warnings.}}
454
-v, --verbose zz{{Display more information.}}
455
-h, --help zz{{Show help message.}}
458
zz{{zz{{Blah blah blah.}}
461
zz{{Interesting stuff about formats.}}
469
zz{{Clever things to keep in mind.}}
474
def test_help_text_custom_usage(self):
475
"""Help text may contain a custom usage section."""
476
class cmd_Demo(commands.Command):
477
__doc__ = """A sample command.
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()
515
class TestRegisteredTopic(TestHelp):
516
"""Tests for the RegisteredTopic class."""
518
def test_contruct(self):
519
"""Construction takes the help topic name for the registered item."""
521
self.assertTrue('basic' in help_topics.topic_registry)
522
topic = help_topics.RegisteredTopic('basic')
523
self.assertEqual('basic', topic.topic)
525
def test_get_help_text(self):
526
"""RegisteredTopic returns the get_detail results for get_help_text."""
527
topic = help_topics.RegisteredTopic('commands')
528
self.assertEqual(help_topics.topic_registry.get_detail('commands'),
529
topic.get_help_text())
531
def test_get_help_text_with_additional_see_also(self):
532
topic = help_topics.RegisteredTopic('commands')
534
topic.get_help_text(['foo', 'bar']),
536
'See also: bar, foo\n')
538
def test_get_help_text_loaded_from_file(self):
539
# Pick a known topic stored in an external file
540
topic = help_topics.RegisteredTopic('authentication')
541
self.assertStartsWith(topic.get_help_text(),
542
'Authentication Settings\n'
543
'=======================\n'
546
def test_get_help_topic(self):
547
"""The help topic for RegisteredTopic is its topic from construction."""
548
topic = help_topics.RegisteredTopic('foobar')
549
self.assertEqual('foobar', topic.get_help_topic())
550
topic = help_topics.RegisteredTopic('baz')
551
self.assertEqual('baz', topic.get_help_topic())
554
class TestTopicIndex(TestHelp):
555
"""Tests for the HelpTopicIndex class."""
557
def test_default_constructable(self):
558
index = help_topics.HelpTopicIndex()
560
def test_get_topics_None(self):
561
"""Searching for None returns the basic help topic."""
562
index = help_topics.HelpTopicIndex()
563
topics = index.get_topics(None)
564
self.assertEqual(1, len(topics))
565
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
566
self.assertEqual('basic', topics[0].topic)
568
def test_get_topics_topics(self):
569
"""Searching for a string returns the matching string."""
570
index = help_topics.HelpTopicIndex()
571
topics = index.get_topics('topics')
572
self.assertEqual(1, len(topics))
573
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
574
self.assertEqual('topics', topics[0].topic)
576
def test_get_topics_no_topic(self):
577
"""Searching for something not registered returns []."""
578
index = help_topics.HelpTopicIndex()
579
self.assertEqual([], index.get_topics('nothing by this name'))
581
def test_prefix(self):
582
"""TopicIndex has a prefix of ''."""
583
index = help_topics.HelpTopicIndex()
584
self.assertEqual('', index.prefix)
587
class TestConfigOptionIndex(TestHelp):
588
"""Tests for the HelpCommandIndex class."""
591
super(TestConfigOptionIndex, self).setUp()
592
self.index = help_topics.ConfigOptionHelpIndex()
594
def test_get_topics_None(self):
595
"""Searching for None returns an empty list."""
596
self.assertEqual([], self.index.get_topics(None))
598
def test_get_topics_no_topic(self):
599
self.assertEqual([], self.index.get_topics('nothing by this name'))
601
def test_prefix(self):
602
self.assertEqual('configuration/', self.index.prefix)
604
def test_get_topic_with_prefix(self):
605
topics = self.index.get_topics('configuration/default_format')
606
self.assertLength(1, topics)
608
self.assertIsInstance(opt, config.Option)
609
self.assertEqual('default_format', opt.name)
612
class TestCommandIndex(TestHelp):
613
"""Tests for the HelpCommandIndex class."""
615
def test_default_constructable(self):
616
index = commands.HelpCommandIndex()
618
def test_get_topics_None(self):
619
"""Searching for None returns an empty list."""
620
index = commands.HelpCommandIndex()
621
self.assertEqual([], index.get_topics(None))
623
def test_get_topics_rocks(self):
624
"""Searching for 'rocks' returns the cmd_rocks command instance."""
625
index = commands.HelpCommandIndex()
626
topics = index.get_topics('rocks')
627
self.assertEqual(1, len(topics))
628
self.assertIsInstance(topics[0], builtins.cmd_rocks)
630
def test_get_topics_no_topic(self):
631
"""Searching for something that is not a command returns []."""
632
index = commands.HelpCommandIndex()
633
self.assertEqual([], index.get_topics('nothing by this name'))
635
def test_prefix(self):
636
"""CommandIndex has a prefix of 'commands/'."""
637
index = commands.HelpCommandIndex()
638
self.assertEqual('commands/', index.prefix)
640
def test_get_topic_with_prefix(self):
641
"""Searching for commands/rocks returns the rocks command object."""
642
index = commands.HelpCommandIndex()
643
topics = index.get_topics('commands/rocks')
644
self.assertEqual(1, len(topics))
645
self.assertIsInstance(topics[0], builtins.cmd_rocks)
648
class TestHelpIndices(tests.TestCase):
649
"""Tests for the HelpIndices class."""
651
def test_default_search_path(self):
652
"""The default search path should include internal indexs."""
653
indices = help.HelpIndices()
654
self.assertEqual(4, len(indices.search_path))
655
# help topics should be searched in first.
656
self.assertIsInstance(indices.search_path[0],
657
help_topics.HelpTopicIndex)
658
# with commands being search second.
659
self.assertIsInstance(indices.search_path[1],
660
commands.HelpCommandIndex)
661
# plugins are a third index.
662
self.assertIsInstance(indices.search_path[2],
663
plugin.PluginsHelpIndex)
664
# config options are a fourth index
665
self.assertIsInstance(indices.search_path[3],
666
help_topics.ConfigOptionHelpIndex)
668
def test_search_for_unknown_topic_raises(self):
669
"""Searching for an unknown topic should raise NoHelpTopic."""
670
indices = help.HelpIndices()
671
indices.search_path = []
672
error = self.assertRaises(help.NoHelpTopic, indices.search, 'foo')
673
self.assertEqual('foo', error.topic)
675
def test_search_calls_get_topic(self):
676
"""Searching should call get_topics in all indexes in order."""
678
class RecordingIndex(object):
679
def __init__(self, name):
681
def get_topics(self, topic):
682
calls.append(('get_topics', self.prefix, topic))
684
index = help.HelpIndices()
685
index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
689
('get_topics', '1', None),
690
('get_topics', '2', None),
697
('get_topics', '1', 'bar'),
698
('get_topics', '2', 'bar'),
702
def test_search_returns_index_and_results(self):
703
"""Searching should return help topics with their index"""
704
class CannedIndex(object):
705
def __init__(self, prefix, search_result):
707
self.result = search_result
708
def get_topics(self, topic):
710
index = help.HelpIndices()
711
index_one = CannedIndex('1', ['a'])
712
index_two = CannedIndex('2', ['b', 'c'])
713
index.search_path = [index_one, index_two]
714
self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
717
def test_search_checks_for_duplicate_prefixes(self):
718
"""Its an error when there are multiple indices with the same prefix."""
719
indices = help.HelpIndices()
720
indices.search_path = [help_topics.HelpTopicIndex(),
721
help_topics.HelpTopicIndex()]
722
self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)
added
removed
breezy/tests/test_help.py
