1
# Copyright (C) 2007-2010 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."""
19
from cStringIO import StringIO
32
class TestHelp(tests.TestCase):
35
tests.TestCase.setUp(self)
36
commands.install_bzr_command_hooks()
39
class TestCommandHelp(tests.TestCase):
40
"""Tests for help on commands."""
42
def test_command_help_includes_see_also(self):
43
class cmd_WithSeeAlso(commands.Command):
44
__doc__ = """A sample command."""
45
_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
def test_get_help_text(self):
57
"""Commands have a get_help_text method which returns their help."""
58
class cmd_Demo(commands.Command):
59
__doc__ = """A sample command."""
61
helptext = cmd.get_help_text()
62
self.assertStartsWith(helptext,
63
'Purpose: A sample command.\n'
65
self.assertEndsWith(helptext,
66
' -h, --help Show help message.\n\n')
68
def test_command_with_additional_see_also(self):
69
class cmd_WithSeeAlso(commands.Command):
70
__doc__ = """A sample command."""
71
_see_also = ['foo', 'bar']
72
cmd = cmd_WithSeeAlso()
73
helptext = cmd.get_help_text(['gam'])
76
' -v, --verbose Display more information.\n'
77
' -q, --quiet Only display errors and warnings.\n'
78
' -h, --help Show help message.\n'
80
'See also: bar, foo, gam\n')
82
def test_command_only_additional_see_also(self):
83
class cmd_WithSeeAlso(commands.Command):
84
__doc__ = """A sample command."""
85
cmd = cmd_WithSeeAlso()
86
helptext = cmd.get_help_text(['gam'])
89
' -v, --verbose Display more information.\n'
90
' -q, --quiet Only display errors and warnings.\n'
91
' -h, --help Show help message.\n'
95
def test_get_help_topic(self):
96
"""The help topic for a Command is its name()."""
97
class cmd_foo_bar(commands.Command):
98
__doc__ = """A sample command."""
100
self.assertEqual(cmd.name(), cmd.get_help_topic())
102
def test_formatted_help_text(self):
103
"""Help text should be plain text by default."""
104
class cmd_Demo(commands.Command):
105
__doc__ = """A sample command.
117
helptext = cmd.get_help_text()
120
'Purpose: A sample command.\n'
124
' --usage Show usage message and options.\n'
125
' -0, --null Use an ASCII NUL (\\0) separator rather than a newline.\n'
126
' -v, --verbose Display more information.\n'
127
' -q, --quiet Only display errors and warnings.\n'
128
' -h, --help Show help message.\n'
139
helptext = cmd.get_help_text(plain=False)
140
self.assertEquals(helptext,
141
':Purpose: A sample command.\n'
145
' --usage Show usage message and options.\n'
146
' -0, --null Use an ASCII NUL (\\0) separator rather than a newline.\n'
147
' -v, --verbose Display more information.\n'
148
' -q, --quiet Only display errors and warnings.\n'
149
' -h, --help Show help message.\n'
161
def test_concise_help_text(self):
162
"""Concise help text excludes the descriptive sections."""
163
class cmd_Demo(commands.Command):
164
__doc__ = """A sample command.
174
helptext = cmd.get_help_text()
175
self.assertEqualDiff(
177
'Purpose: A sample command.\n'
181
' --usage Show usage message and options.\n'
182
' -0, --null Use an ASCII NUL (\\0) separator rather than a newline.\n'
183
' -v, --verbose Display more information.\n'
184
' -q, --quiet Only display errors and warnings.\n'
185
' -h, --help Show help message.\n'
195
helptext = cmd.get_help_text(verbose=False)
196
self.assertEquals(helptext,
197
'Purpose: A sample command.\n'
201
' --usage Show usage message and options.\n'
202
' -0, --null Use an ASCII NUL (\\0) separator rather than a newline.\n'
203
' -v, --verbose Display more information.\n'
204
' -q, --quiet Only display errors and warnings.\n'
205
' -h, --help Show help message.\n'
207
'See bzr help Demo for more details and examples.\n'
210
def test_help_custom_section_ordering(self):
211
"""Custom descriptive sections should remain in the order given."""
212
class cmd_Demo(commands.Command):
213
__doc__ = """A sample command.
218
Interesting stuff about formats.
226
Clever things to keep in mind.
229
helptext = cmd.get_help_text()
230
self.assertEqualDiff(
232
'Purpose: A sample command.\n'
236
' --usage Show usage message and options.\n'
237
' -0, --null Use an ASCII NUL (\\0) separator rather than a newline.\n'
238
' -v, --verbose Display more information.\n'
239
' -q, --quiet Only display errors and warnings.\n'
240
' -h, --help Show help message.\n'
246
' Interesting stuff about formats.\n'
254
' Clever things to keep in mind.\n'
257
def test_help_text_custom_usage(self):
258
"""Help text may contain a custom usage section."""
259
class cmd_Demo(commands.Command):
260
__doc__ = """A sample command.
270
helptext = cmd.get_help_text()
271
self.assertEquals(helptext,
272
'Purpose: A sample command.\n'
274
' cmd Demo [opts] args\n'
280
' --usage Show usage message and options.\n'
281
' -0, --null Use an ASCII NUL (\\0) separator rather than a newline.\n'
282
' -v, --verbose Display more information.\n'
283
' -q, --quiet Only display errors and warnings.\n'
284
' -h, --help Show help message.\n'
287
' Blah blah blah.\n\n')
290
class TestRegisteredTopic(TestHelp):
291
"""Tests for the RegisteredTopic class."""
293
def test_contruct(self):
294
"""Construction takes the help topic name for the registered item."""
296
self.assertTrue('basic' in help_topics.topic_registry)
297
topic = help_topics.RegisteredTopic('basic')
298
self.assertEqual('basic', topic.topic)
300
def test_get_help_text(self):
301
"""A RegisteredTopic returns the get_detail results for get_help_text."""
302
topic = help_topics.RegisteredTopic('commands')
303
self.assertEqual(help_topics.topic_registry.get_detail('commands'),
304
topic.get_help_text())
306
def test_get_help_text_with_additional_see_also(self):
307
topic = help_topics.RegisteredTopic('commands')
309
topic.get_help_text(['foo', 'bar']),
311
'See also: bar, foo\n')
313
def test_get_help_text_loaded_from_file(self):
314
# Pick a known topic stored in an external file
315
topic = help_topics.RegisteredTopic('authentication')
316
self.assertStartsWith(topic.get_help_text(),
317
'Authentication Settings\n'
318
'=======================\n'
321
def test_get_help_topic(self):
322
"""The help topic for a RegisteredTopic is its topic from construction."""
323
topic = help_topics.RegisteredTopic('foobar')
324
self.assertEqual('foobar', topic.get_help_topic())
325
topic = help_topics.RegisteredTopic('baz')
326
self.assertEqual('baz', topic.get_help_topic())
329
class TestTopicIndex(TestHelp):
330
"""Tests for the HelpTopicIndex class."""
332
def test_default_constructable(self):
333
index = help_topics.HelpTopicIndex()
335
def test_get_topics_None(self):
336
"""Searching for None returns the basic help topic."""
337
index = help_topics.HelpTopicIndex()
338
topics = index.get_topics(None)
339
self.assertEqual(1, len(topics))
340
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
341
self.assertEqual('basic', topics[0].topic)
343
def test_get_topics_topics(self):
344
"""Searching for a string returns the matching string."""
345
index = help_topics.HelpTopicIndex()
346
topics = index.get_topics('topics')
347
self.assertEqual(1, len(topics))
348
self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
349
self.assertEqual('topics', topics[0].topic)
351
def test_get_topics_no_topic(self):
352
"""Searching for something not registered returns []."""
353
index = help_topics.HelpTopicIndex()
354
self.assertEqual([], index.get_topics('nothing by this name'))
356
def test_prefix(self):
357
"""TopicIndex has a prefix of ''."""
358
index = help_topics.HelpTopicIndex()
359
self.assertEqual('', index.prefix)
362
class TestCommandIndex(TestHelp):
363
"""Tests for the HelpCommandIndex class."""
365
def test_default_constructable(self):
366
index = commands.HelpCommandIndex()
368
def test_get_topics_None(self):
369
"""Searching for None returns an empty list."""
370
index = commands.HelpCommandIndex()
371
self.assertEqual([], index.get_topics(None))
373
def test_get_topics_rocks(self):
374
"""Searching for 'rocks' returns the cmd_rocks command instance."""
375
index = commands.HelpCommandIndex()
376
topics = index.get_topics('rocks')
377
self.assertEqual(1, len(topics))
378
self.assertIsInstance(topics[0], builtins.cmd_rocks)
380
def test_get_topics_no_topic(self):
381
"""Searching for something that is not a command returns []."""
382
index = commands.HelpCommandIndex()
383
self.assertEqual([], index.get_topics('nothing by this name'))
385
def test_prefix(self):
386
"""CommandIndex has a prefix of 'commands/'."""
387
index = commands.HelpCommandIndex()
388
self.assertEqual('commands/', index.prefix)
390
def test_get_topic_with_prefix(self):
391
"""Searching for commands/rocks returns the rocks command object."""
392
index = commands.HelpCommandIndex()
393
topics = index.get_topics('commands/rocks')
394
self.assertEqual(1, len(topics))
395
self.assertIsInstance(topics[0], builtins.cmd_rocks)
398
class TestHelpIndices(tests.TestCase):
399
"""Tests for the HelpIndices class."""
401
def test_default_search_path(self):
402
"""The default search path should include internal indexs."""
403
indices = help.HelpIndices()
404
self.assertEqual(3, len(indices.search_path))
405
# help topics should be searched in first.
406
self.assertIsInstance(indices.search_path[0],
407
help_topics.HelpTopicIndex)
408
# with commands being search second.
409
self.assertIsInstance(indices.search_path[1],
410
commands.HelpCommandIndex)
411
# and plugins are a third index.
412
self.assertIsInstance(indices.search_path[2],
413
plugin.PluginsHelpIndex)
415
def test_search_for_unknown_topic_raises(self):
416
"""Searching for an unknown topic should raise NoHelpTopic."""
417
indices = help.HelpIndices()
418
indices.search_path = []
419
error = self.assertRaises(errors.NoHelpTopic, indices.search, 'foo')
420
self.assertEqual('foo', error.topic)
422
def test_search_calls_get_topic(self):
423
"""Searching should call get_topics in all indexes in order."""
425
class RecordingIndex(object):
426
def __init__(self, name):
428
def get_topics(self, topic):
429
calls.append(('get_topics', self.prefix, topic))
431
index = help.HelpIndices()
432
index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
436
('get_topics', '1', None),
437
('get_topics', '2', None),
444
('get_topics', '1', 'bar'),
445
('get_topics', '2', 'bar'),
449
def test_search_returns_index_and_results(self):
450
"""Searching should return help topics with their index"""
451
class CannedIndex(object):
452
def __init__(self, prefix, search_result):
454
self.result = search_result
455
def get_topics(self, topic):
457
index = help.HelpIndices()
458
index_one = CannedIndex('1', ['a'])
459
index_two = CannedIndex('2', ['b', 'c'])
460
index.search_path = [index_one, index_two]
461
self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
464
def test_search_checks_for_duplicate_prefixes(self):
465
"""Its an error when there are multiple indices with the same prefix."""
466
indices = help.HelpIndices()
467
indices.search_path = [help_topics.HelpTopicIndex(),
468
help_topics.HelpTopicIndex()]
469
self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)
added
removed
bzrlib/tests/test_help.py
