← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/tests/test_help.py

  • Committer: John Arbash Meinel
  • Date: 2010-02-16 16:08:40 UTC
  • mfrom: (4797.2.15 2.1)
  • mto: (4797.2.16 2.1)
  • mto: This revision was merged to the branch mainline in revision 5037.
  • Revision ID: john@arbash-meinel.com-20100216160840-xwbpuu0v89gq8lej
Tags: bzr-2.1.0
bring in the latest 2.1 changes

Show diffs side-by-side

added added

removed removed

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