← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/tests/test_help.py

Merge bzr.dev to resolve conflicts

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/tests/test_help.py
 
1
# Copyright (C) 2007-2011 Canonical Ltd
 
2
#
 
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.
 
7
#
 
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.
 
12
#
 
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
 
16
 
 
17
"""Unit tests for the bzrlib.help module."""
 
18
 
 
19
from bzrlib import (
 
20
    builtins,
 
21
    commands,
 
22
    errors,
 
23
    help,
 
24
    help_topics,
 
25
    plugin,
 
26
    tests,
 
27
    )
 
28
 
 
29
 
 
30
class TestHelp(tests.TestCase):
 
31
 
 
32
    def setUp(self):
 
33
        tests.TestCase.setUp(self)
 
34
        commands.install_bzr_command_hooks()
 
35
 
 
36
 
 
37
class TestCommandHelp(tests.TestCase):
 
38
    """Tests for help on commands."""
 
39
 
 
40
    def test_command_help_includes_see_also(self):
 
41
        class cmd_WithSeeAlso(commands.Command):
 
42
            __doc__ = """A sample command."""
 
43
            _see_also = ['foo', 'bar']
 
44
        cmd = cmd_WithSeeAlso()
 
45
        helptext = cmd.get_help_text()
 
46
        self.assertEndsWith(
 
47
            helptext,
 
48
            '  -v, --verbose  Display more information.\n'
 
49
            '  -q, --quiet    Only display errors and warnings.\n'
 
50
            '  -h, --help     Show help message.\n'
 
51
            '\n'
 
52
            'See also: bar, foo\n')
 
53
 
 
54
    def test_get_help_text(self):
 
55
        """Commands have a get_help_text method which returns their help."""
 
56
        class cmd_Demo(commands.Command):
 
57
            __doc__ = """A sample command."""
 
58
        cmd = cmd_Demo()
 
59
        helptext = cmd.get_help_text()
 
60
        self.assertStartsWith(helptext,
 
61
            'Purpose: A sample command.\n'
 
62
            'Usage:   bzr Demo')
 
63
        self.assertEndsWith(helptext,
 
64
            '  -h, --help     Show help message.\n\n')
 
65
 
 
66
    def test_command_with_additional_see_also(self):
 
67
        class cmd_WithSeeAlso(commands.Command):
 
68
            __doc__ = """A sample command."""
 
69
            _see_also = ['foo', 'bar']
 
70
        cmd = cmd_WithSeeAlso()
 
71
        helptext = cmd.get_help_text(['gam'])
 
72
        self.assertEndsWith(
 
73
            helptext,
 
74
            '  -v, --verbose  Display more information.\n'
 
75
            '  -q, --quiet    Only display errors and warnings.\n'
 
76
            '  -h, --help     Show help message.\n'
 
77
            '\n'
 
78
            'See also: bar, foo, gam\n')
 
79
 
 
80
    def test_command_only_additional_see_also(self):
 
81
        class cmd_WithSeeAlso(commands.Command):
 
82
            __doc__ = """A sample command."""
 
83
        cmd = cmd_WithSeeAlso()
 
84
        helptext = cmd.get_help_text(['gam'])
 
85
        self.assertEndsWith(
 
86
            helptext,
 
87
            '  -v, --verbose  Display more information.\n'
 
88
            '  -q, --quiet    Only display errors and warnings.\n'
 
89
            '  -h, --help     Show help message.\n'
 
90
            '\n'
 
91
            'See also: gam\n')
 
92
 
 
93
    def test_get_help_topic(self):
 
94
        """The help topic for a Command is its name()."""
 
95
        class cmd_foo_bar(commands.Command):
 
96
            __doc__ = """A sample command."""
 
97
        cmd = cmd_foo_bar()
 
98
        self.assertEqual(cmd.name(), cmd.get_help_topic())
 
99
 
 
100
    def test_formatted_help_text(self):
 
101
        """Help text should be plain text by default."""
 
102
        class cmd_Demo(commands.Command):
 
103
            __doc__ = """A sample command.
 
104
 
 
105
            :Examples:
 
106
                Example 1::
 
107
 
 
108
                    cmd arg1
 
109
 
 
110
                Example 2::
 
111
 
 
112
                    cmd arg2
 
113
 
 
114
                A code block follows.
 
115
 
 
116
                ::
 
117
 
 
118
                    bzr Demo something
 
119
            """
 
120
        cmd = cmd_Demo()
 
121
        helptext = cmd.get_help_text()
 
122
        self.assertEquals(
 
123
            helptext,
 
124
            'Purpose: A sample command.\n'
 
125
            'Usage:   bzr Demo\n'
 
126
            '\n'
 
127
            'Options:\n'
 
128
            '  --usage        Show usage message and options.\n'
 
129
            '  -v, --verbose  Display more information.\n'
 
130
            '  -q, --quiet    Only display errors and warnings.\n'
 
131
            '  -h, --help     Show help message.\n'
 
132
            '\n'
 
133
            'Examples:\n'
 
134
            '    Example 1:\n'
 
135
            '\n'
 
136
            '        cmd arg1\n'
 
137
            '\n'
 
138
            '    Example 2:\n'
 
139
            '\n'
 
140
            '        cmd arg2\n'
 
141
            '\n'
 
142
            '    A code block follows.\n'
 
143
            '\n'
 
144
            '        bzr Demo something\n'
 
145
            '\n')
 
146
        helptext = cmd.get_help_text(plain=False)
 
147
        self.assertEquals(helptext,
 
148
            ':Purpose: A sample command.\n'
 
149
            ':Usage:   bzr Demo\n'
 
150
            '\n'
 
151
            ':Options:\n'
 
152
            '  --usage        Show usage message and options.\n'
 
153
            '  -v, --verbose  Display more information.\n'
 
154
            '  -q, --quiet    Only display errors and warnings.\n'
 
155
            '  -h, --help     Show help message.\n'
 
156
            '\n'
 
157
            ':Examples:\n'
 
158
            '    Example 1::\n'
 
159
            '\n'
 
160
            '        cmd arg1\n'
 
161
            '\n'
 
162
            '    Example 2::\n'
 
163
            '\n'
 
164
            '        cmd arg2\n'
 
165
            '\n'
 
166
            '    A code block follows.\n'
 
167
            '\n'
 
168
            '    ::\n'
 
169
            '\n'
 
170
            '        bzr Demo something\n'
 
171
            '\n')
 
172
 
 
173
    def test_concise_help_text(self):
 
174
        """Concise help text excludes the descriptive sections."""
 
175
        class cmd_Demo(commands.Command):
 
176
            __doc__ = """A sample command.
 
177
 
 
178
            Blah blah blah.
 
179
 
 
180
            :Examples:
 
181
                Example 1::
 
182
 
 
183
                    cmd arg1
 
184
            """
 
185
        cmd = cmd_Demo()
 
186
        helptext = cmd.get_help_text()
 
187
        self.assertEqualDiff(
 
188
            helptext,
 
189
            'Purpose: A sample command.\n'
 
190
            'Usage:   bzr Demo\n'
 
191
            '\n'
 
192
            'Options:\n'
 
193
            '  --usage        Show usage message and options.\n'
 
194
            '  -v, --verbose  Display more information.\n'
 
195
            '  -q, --quiet    Only display errors and warnings.\n'
 
196
            '  -h, --help     Show help message.\n'
 
197
            '\n'
 
198
            'Description:\n'
 
199
            '  Blah blah blah.\n'
 
200
            '\n'
 
201
            'Examples:\n'
 
202
            '    Example 1:\n'
 
203
            '\n'
 
204
            '        cmd arg1\n'
 
205
            '\n')
 
206
        helptext = cmd.get_help_text(verbose=False)
 
207
        self.assertEquals(helptext,
 
208
            'Purpose: A sample command.\n'
 
209
            'Usage:   bzr Demo\n'
 
210
            '\n'
 
211
            'Options:\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'
 
216
            '\n'
 
217
            'See bzr help Demo for more details and examples.\n'
 
218
            '\n')
 
219
 
 
220
    def test_help_custom_section_ordering(self):
 
221
        """Custom descriptive sections should remain in the order given."""
 
222
        class cmd_Demo(commands.Command):
 
223
            __doc__ = """A sample command.
 
224
 
 
225
            Blah blah blah.
 
226
 
 
227
            :Formats:
 
228
              Interesting stuff about formats.
 
229
 
 
230
            :Examples:
 
231
              Example 1::
 
232
 
 
233
                cmd arg1
 
234
 
 
235
            :Tips:
 
236
              Clever things to keep in mind.
 
237
            """
 
238
        cmd = cmd_Demo()
 
239
        helptext = cmd.get_help_text()
 
240
        self.assertEqualDiff(
 
241
            helptext,
 
242
            'Purpose: A sample command.\n'
 
243
            'Usage:   bzr Demo\n'
 
244
            '\n'
 
245
            'Options:\n'
 
246
            '  --usage        Show usage message and options.\n'
 
247
            '  -v, --verbose  Display more information.\n'
 
248
            '  -q, --quiet    Only display errors and warnings.\n'
 
249
            '  -h, --help     Show help message.\n'
 
250
            '\n'
 
251
            'Description:\n'
 
252
            '  Blah blah blah.\n'
 
253
            '\n'
 
254
            'Formats:\n'
 
255
            '  Interesting stuff about formats.\n'
 
256
            '\n'
 
257
            'Examples:\n'
 
258
            '  Example 1:\n'
 
259
            '\n'
 
260
            '    cmd arg1\n'
 
261
            '\n'
 
262
            'Tips:\n'
 
263
            '  Clever things to keep in mind.\n'
 
264
            '\n')
 
265
 
 
266
    def test_help_text_custom_usage(self):
 
267
        """Help text may contain a custom usage section."""
 
268
        class cmd_Demo(commands.Command):
 
269
            __doc__ = """A sample command.
 
270
 
 
271
            :Usage:
 
272
                cmd Demo [opts] args
 
273
 
 
274
                cmd Demo -h
 
275
 
 
276
            Blah blah blah.
 
277
            """
 
278
        cmd = cmd_Demo()
 
279
        helptext = cmd.get_help_text()
 
280
        self.assertEquals(helptext,
 
281
            'Purpose: A sample command.\n'
 
282
            'Usage:\n'
 
283
            '    cmd Demo [opts] args\n'
 
284
            '\n'
 
285
            '    cmd Demo -h\n'
 
286
            '\n'
 
287
            '\n'
 
288
            'Options:\n'
 
289
            '  --usage        Show usage message and options.\n'
 
290
            '  -v, --verbose  Display more information.\n'
 
291
            '  -q, --quiet    Only display errors and warnings.\n'
 
292
            '  -h, --help     Show help message.\n'
 
293
            '\n'
 
294
            'Description:\n'
 
295
            '  Blah blah blah.\n\n')
 
296
 
 
297
 
 
298
class TestRegisteredTopic(TestHelp):
 
299
    """Tests for the RegisteredTopic class."""
 
300
 
 
301
    def test_contruct(self):
 
302
        """Construction takes the help topic name for the registered item."""
 
303
        # validate our test
 
304
        self.assertTrue('basic' in help_topics.topic_registry)
 
305
        topic = help_topics.RegisteredTopic('basic')
 
306
        self.assertEqual('basic', topic.topic)
 
307
 
 
308
    def test_get_help_text(self):
 
309
        """A RegisteredTopic returns the get_detail results for get_help_text."""
 
310
        topic = help_topics.RegisteredTopic('commands')
 
311
        self.assertEqual(help_topics.topic_registry.get_detail('commands'),
 
312
            topic.get_help_text())
 
313
 
 
314
    def test_get_help_text_with_additional_see_also(self):
 
315
        topic = help_topics.RegisteredTopic('commands')
 
316
        self.assertEndsWith(
 
317
            topic.get_help_text(['foo', 'bar']),
 
318
            '\n'
 
319
            'See also: bar, foo\n')
 
320
 
 
321
    def test_get_help_text_loaded_from_file(self):
 
322
        # Pick a known topic stored in an external file
 
323
        topic = help_topics.RegisteredTopic('authentication')
 
324
        self.assertStartsWith(topic.get_help_text(),
 
325
            'Authentication Settings\n'
 
326
            '=======================\n'
 
327
            '\n')
 
328
 
 
329
    def test_get_help_topic(self):
 
330
        """The help topic for a RegisteredTopic is its topic from construction."""
 
331
        topic = help_topics.RegisteredTopic('foobar')
 
332
        self.assertEqual('foobar', topic.get_help_topic())
 
333
        topic = help_topics.RegisteredTopic('baz')
 
334
        self.assertEqual('baz', topic.get_help_topic())
 
335
 
 
336
 
 
337
class TestTopicIndex(TestHelp):
 
338
    """Tests for the HelpTopicIndex class."""
 
339
 
 
340
    def test_default_constructable(self):
 
341
        index = help_topics.HelpTopicIndex()
 
342
 
 
343
    def test_get_topics_None(self):
 
344
        """Searching for None returns the basic help topic."""
 
345
        index = help_topics.HelpTopicIndex()
 
346
        topics = index.get_topics(None)
 
347
        self.assertEqual(1, len(topics))
 
348
        self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
 
349
        self.assertEqual('basic', topics[0].topic)
 
350
 
 
351
    def test_get_topics_topics(self):
 
352
        """Searching for a string returns the matching string."""
 
353
        index = help_topics.HelpTopicIndex()
 
354
        topics = index.get_topics('topics')
 
355
        self.assertEqual(1, len(topics))
 
356
        self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
 
357
        self.assertEqual('topics', topics[0].topic)
 
358
 
 
359
    def test_get_topics_no_topic(self):
 
360
        """Searching for something not registered returns []."""
 
361
        index = help_topics.HelpTopicIndex()
 
362
        self.assertEqual([], index.get_topics('nothing by this name'))
 
363
 
 
364
    def test_prefix(self):
 
365
        """TopicIndex has a prefix of ''."""
 
366
        index = help_topics.HelpTopicIndex()
 
367
        self.assertEqual('', index.prefix)
 
368
 
 
369
 
 
370
class TestCommandIndex(TestHelp):
 
371
    """Tests for the HelpCommandIndex class."""
 
372
 
 
373
    def test_default_constructable(self):
 
374
        index = commands.HelpCommandIndex()
 
375
 
 
376
    def test_get_topics_None(self):
 
377
        """Searching for None returns an empty list."""
 
378
        index = commands.HelpCommandIndex()
 
379
        self.assertEqual([], index.get_topics(None))
 
380
 
 
381
    def test_get_topics_rocks(self):
 
382
        """Searching for 'rocks' returns the cmd_rocks command instance."""
 
383
        index = commands.HelpCommandIndex()
 
384
        topics = index.get_topics('rocks')
 
385
        self.assertEqual(1, len(topics))
 
386
        self.assertIsInstance(topics[0], builtins.cmd_rocks)
 
387
 
 
388
    def test_get_topics_no_topic(self):
 
389
        """Searching for something that is not a command returns []."""
 
390
        index = commands.HelpCommandIndex()
 
391
        self.assertEqual([], index.get_topics('nothing by this name'))
 
392
 
 
393
    def test_prefix(self):
 
394
        """CommandIndex has a prefix of 'commands/'."""
 
395
        index = commands.HelpCommandIndex()
 
396
        self.assertEqual('commands/', index.prefix)
 
397
 
 
398
    def test_get_topic_with_prefix(self):
 
399
        """Searching for commands/rocks returns the rocks command object."""
 
400
        index = commands.HelpCommandIndex()
 
401
        topics = index.get_topics('commands/rocks')
 
402
        self.assertEqual(1, len(topics))
 
403
        self.assertIsInstance(topics[0], builtins.cmd_rocks)
 
404
 
 
405
 
 
406
class TestHelpIndices(tests.TestCase):
 
407
    """Tests for the HelpIndices class."""
 
408
 
 
409
    def test_default_search_path(self):
 
410
        """The default search path should include internal indexs."""
 
411
        indices = help.HelpIndices()
 
412
        self.assertEqual(3, len(indices.search_path))
 
413
        # help topics should be searched in first.
 
414
        self.assertIsInstance(indices.search_path[0],
 
415
            help_topics.HelpTopicIndex)
 
416
        # with commands being search second.
 
417
        self.assertIsInstance(indices.search_path[1],
 
418
            commands.HelpCommandIndex)
 
419
        # and plugins are a third index.
 
420
        self.assertIsInstance(indices.search_path[2],
 
421
            plugin.PluginsHelpIndex)
 
422
 
 
423
    def test_search_for_unknown_topic_raises(self):
 
424
        """Searching for an unknown topic should raise NoHelpTopic."""
 
425
        indices = help.HelpIndices()
 
426
        indices.search_path = []
 
427
        error = self.assertRaises(errors.NoHelpTopic, indices.search, 'foo')
 
428
        self.assertEqual('foo', error.topic)
 
429
 
 
430
    def test_search_calls_get_topic(self):
 
431
        """Searching should call get_topics in all indexes in order."""
 
432
        calls = []
 
433
        class RecordingIndex(object):
 
434
            def __init__(self, name):
 
435
                self.prefix = name
 
436
            def get_topics(self, topic):
 
437
                calls.append(('get_topics', self.prefix, topic))
 
438
                return ['something']
 
439
        index = help.HelpIndices()
 
440
        index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
 
441
        # try with None
 
442
        index.search(None)
 
443
        self.assertEqual([
 
444
            ('get_topics', '1', None),
 
445
            ('get_topics', '2', None),
 
446
            ],
 
447
            calls)
 
448
        # and with a string
 
449
        del calls[:]
 
450
        index.search('bar')
 
451
        self.assertEqual([
 
452
            ('get_topics', '1', 'bar'),
 
453
            ('get_topics', '2', 'bar'),
 
454
            ],
 
455
            calls)
 
456
 
 
457
    def test_search_returns_index_and_results(self):
 
458
        """Searching should return help topics with their index"""
 
459
        class CannedIndex(object):
 
460
            def __init__(self, prefix, search_result):
 
461
                self.prefix = prefix
 
462
                self.result = search_result
 
463
            def get_topics(self, topic):
 
464
                return self.result
 
465
        index = help.HelpIndices()
 
466
        index_one = CannedIndex('1', ['a'])
 
467
        index_two = CannedIndex('2', ['b', 'c'])
 
468
        index.search_path = [index_one, index_two]
 
469
        self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
 
470
            index.search(None))
 
471
 
 
472
    def test_search_checks_for_duplicate_prefixes(self):
 
473
        """Its an error when there are multiple indices with the same prefix."""
 
474
        indices = help.HelpIndices()
 
475
        indices.search_path = [help_topics.HelpTopicIndex(),
 
476
            help_topics.HelpTopicIndex()]
 
477
        self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)