/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/tests/test_help.py

  • Committer: Ian Clatworthy
  • Date: 2009-02-26 06:15:24 UTC
  • mto: (4157.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 4158.
  • Revision ID: ian.clatworthy@canonical.com-20090226061524-kpy3n8na3mk4ubuy
help xxx is full help; xxx -h is concise help

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