← 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: Jonathan Lange
  • Date: 2009-05-01 06:42:30 UTC
  • mto: This revision was merged to the branch mainline in revision 4320.
  • Revision ID: jml@canonical.com-20090501064230-kyk7v49xt8cevd25
Remove InstallFailed, it's not needed anymore.

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