← 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: Patch Queue Manager
  • Date: 2011-09-22 14:12:18 UTC
  • mfrom: (6155.3.1 jam)
  • Revision ID: pqm@pqm.ubuntu.com-20110922141218-86s4uu6nqvourw4f
(jameinel) Cleanup comments bzrlib/smart/__init__.py (John A Meinel)

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
import textwrap
 
20
 
 
21
from bzrlib import (
 
22
    builtins,
 
23
    commands,
 
24
    config,
 
25
    errors,
 
26
    help,
 
27
    help_topics,
 
28
    i18n,
 
29
    plugin,
 
30
    tests,
 
31
    )
 
32
 
 
33
from bzrlib.tests.test_i18n import ZzzTranslations
 
34
import re
 
35
 
 
36
 
 
37
class TestCommandHelp(tests.TestCase):
 
38
    """Tests for help on commands."""
 
39
 
 
40
    def assertCmdHelp(self, expected, cmd):
 
41
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
 
42
 
 
43
    def test_command_help_includes_see_also(self):
 
44
        class cmd_WithSeeAlso(commands.Command):
 
45
            __doc__ = """A sample command."""
 
46
            _see_also = ['foo', 'bar']
 
47
        self.assertCmdHelp('''\
 
48
            Purpose: A sample command.
 
49
            Usage:   bzr WithSeeAlso
 
50
            
 
51
            Options:
 
52
              --usage        Show usage message and options.
 
53
              -v, --verbose  Display more information.
 
54
              -q, --quiet    Only display errors and warnings.
 
55
              -h, --help     Show help message.
 
56
            
 
57
            See also: bar, foo
 
58
            ''',
 
59
                           cmd_WithSeeAlso())
 
60
 
 
61
    def test_get_help_text(self):
 
62
        """Commands have a get_help_text method which returns their help."""
 
63
        class cmd_Demo(commands.Command):
 
64
            __doc__ = """A sample command."""
 
65
        self.assertCmdHelp('''\
 
66
            Purpose: A sample command.
 
67
            Usage:   bzr Demo
 
68
            
 
69
            Options:
 
70
              --usage        Show usage message and options.
 
71
              -v, --verbose  Display more information.
 
72
              -q, --quiet    Only display errors and warnings.
 
73
              -h, --help     Show help message.
 
74
 
 
75
            ''',
 
76
                           cmd_Demo())
 
77
        cmd = cmd_Demo()
 
78
        helptext = cmd.get_help_text()
 
79
        self.assertStartsWith(helptext,
 
80
            'Purpose: A sample command.\n'
 
81
            'Usage:   bzr Demo')
 
82
        self.assertEndsWith(helptext,
 
83
            '  -h, --help     Show help message.\n\n')
 
84
 
 
85
    def test_command_with_additional_see_also(self):
 
86
        class cmd_WithSeeAlso(commands.Command):
 
87
            __doc__ = """A sample command."""
 
88
            _see_also = ['foo', 'bar']
 
89
        cmd = cmd_WithSeeAlso()
 
90
        helptext = cmd.get_help_text(['gam'])
 
91
        self.assertEndsWith(
 
92
            helptext,
 
93
            '  -v, --verbose  Display more information.\n'
 
94
            '  -q, --quiet    Only display errors and warnings.\n'
 
95
            '  -h, --help     Show help message.\n'
 
96
            '\n'
 
97
            'See also: bar, foo, gam\n')
 
98
 
 
99
    def test_command_only_additional_see_also(self):
 
100
        class cmd_WithSeeAlso(commands.Command):
 
101
            __doc__ = """A sample command."""
 
102
        cmd = cmd_WithSeeAlso()
 
103
        helptext = cmd.get_help_text(['gam'])
 
104
        self.assertEndsWith(
 
105
            helptext,
 
106
            '  -v, --verbose  Display more information.\n'
 
107
            '  -q, --quiet    Only display errors and warnings.\n'
 
108
            '  -h, --help     Show help message.\n'
 
109
            '\n'
 
110
            'See also: gam\n')
 
111
 
 
112
    def test_get_help_topic(self):
 
113
        """The help topic for a Command is its name()."""
 
114
        class cmd_foo_bar(commands.Command):
 
115
            __doc__ = """A sample command."""
 
116
        cmd = cmd_foo_bar()
 
117
        self.assertEqual(cmd.name(), cmd.get_help_topic())
 
118
 
 
119
    def test_formatted_help_text(self):
 
120
        """Help text should be plain text by default."""
 
121
        class cmd_Demo(commands.Command):
 
122
            __doc__ = """A sample command.
 
123
 
 
124
            :Examples:
 
125
                Example 1::
 
126
 
 
127
                    cmd arg1
 
128
 
 
129
                Example 2::
 
130
 
 
131
                    cmd arg2
 
132
 
 
133
                A code block follows.
 
134
 
 
135
                ::
 
136
 
 
137
                    bzr Demo something
 
138
            """
 
139
        cmd = cmd_Demo()
 
140
        helptext = cmd.get_help_text()
 
141
        self.assertEquals(
 
142
            helptext,
 
143
            'Purpose: A sample command.\n'
 
144
            'Usage:   bzr Demo\n'
 
145
            '\n'
 
146
            'Options:\n'
 
147
            '  --usage        Show usage message and options.\n'
 
148
            '  -v, --verbose  Display more information.\n'
 
149
            '  -q, --quiet    Only display errors and warnings.\n'
 
150
            '  -h, --help     Show help message.\n'
 
151
            '\n'
 
152
            'Examples:\n'
 
153
            '    Example 1:\n'
 
154
            '\n'
 
155
            '        cmd arg1\n'
 
156
            '\n'
 
157
            '    Example 2:\n'
 
158
            '\n'
 
159
            '        cmd arg2\n'
 
160
            '\n'
 
161
            '    A code block follows.\n'
 
162
            '\n'
 
163
            '        bzr Demo something\n'
 
164
            '\n')
 
165
        helptext = cmd.get_help_text(plain=False)
 
166
        self.assertEquals(helptext,
 
167
            ':Purpose: A sample command.\n'
 
168
            ':Usage:   bzr Demo\n'
 
169
            '\n'
 
170
            ':Options:\n'
 
171
            '  --usage        Show usage message and options.\n'
 
172
            '  -v, --verbose  Display more information.\n'
 
173
            '  -q, --quiet    Only display errors and warnings.\n'
 
174
            '  -h, --help     Show help message.\n'
 
175
            '\n'
 
176
            ':Examples:\n'
 
177
            '    Example 1::\n'
 
178
            '\n'
 
179
            '        cmd arg1\n'
 
180
            '\n'
 
181
            '    Example 2::\n'
 
182
            '\n'
 
183
            '        cmd arg2\n'
 
184
            '\n'
 
185
            '    A code block follows.\n'
 
186
            '\n'
 
187
            '    ::\n'
 
188
            '\n'
 
189
            '        bzr Demo something\n'
 
190
            '\n')
 
191
 
 
192
    def test_concise_help_text(self):
 
193
        """Concise help text excludes the descriptive sections."""
 
194
        class cmd_Demo(commands.Command):
 
195
            __doc__ = """A sample command.
 
196
 
 
197
            Blah blah blah.
 
198
 
 
199
            :Examples:
 
200
                Example 1::
 
201
 
 
202
                    cmd arg1
 
203
            """
 
204
        cmd = cmd_Demo()
 
205
        helptext = cmd.get_help_text()
 
206
        self.assertEqualDiff(
 
207
            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
            'Description:\n'
 
218
            '  Blah blah blah.\n'
 
219
            '\n'
 
220
            'Examples:\n'
 
221
            '    Example 1:\n'
 
222
            '\n'
 
223
            '        cmd arg1\n'
 
224
            '\n')
 
225
        helptext = cmd.get_help_text(verbose=False)
 
226
        self.assertEquals(helptext,
 
227
            'Purpose: A sample command.\n'
 
228
            'Usage:   bzr Demo\n'
 
229
            '\n'
 
230
            'Options:\n'
 
231
            '  --usage        Show usage message and options.\n'
 
232
            '  -v, --verbose  Display more information.\n'
 
233
            '  -q, --quiet    Only display errors and warnings.\n'
 
234
            '  -h, --help     Show help message.\n'
 
235
            '\n'
 
236
            'See bzr help Demo for more details and examples.\n'
 
237
            '\n')
 
238
 
 
239
    def test_help_custom_section_ordering(self):
 
240
        """Custom descriptive sections should remain in the order given."""
 
241
        class cmd_Demo(commands.Command):
 
242
            __doc__ = """A sample command.
 
243
 
 
244
            Blah blah blah.
 
245
 
 
246
            :Formats:
 
247
              Interesting stuff about formats.
 
248
 
 
249
            :Examples:
 
250
              Example 1::
 
251
 
 
252
                cmd arg1
 
253
 
 
254
            :Tips:
 
255
              Clever things to keep in mind.
 
256
            """
 
257
        cmd = cmd_Demo()
 
258
        helptext = cmd.get_help_text()
 
259
        self.assertEqualDiff(
 
260
            helptext,
 
261
            'Purpose: A sample command.\n'
 
262
            'Usage:   bzr Demo\n'
 
263
            '\n'
 
264
            'Options:\n'
 
265
            '  --usage        Show usage message and options.\n'
 
266
            '  -v, --verbose  Display more information.\n'
 
267
            '  -q, --quiet    Only display errors and warnings.\n'
 
268
            '  -h, --help     Show help message.\n'
 
269
            '\n'
 
270
            'Description:\n'
 
271
            '  Blah blah blah.\n'
 
272
            '\n'
 
273
            'Formats:\n'
 
274
            '  Interesting stuff about formats.\n'
 
275
            '\n'
 
276
            'Examples:\n'
 
277
            '  Example 1:\n'
 
278
            '\n'
 
279
            '    cmd arg1\n'
 
280
            '\n'
 
281
            'Tips:\n'
 
282
            '  Clever things to keep in mind.\n'
 
283
            '\n')
 
284
 
 
285
    def test_help_text_custom_usage(self):
 
286
        """Help text may contain a custom usage section."""
 
287
        class cmd_Demo(commands.Command):
 
288
            __doc__ = """A sample command.
 
289
 
 
290
            :Usage:
 
291
                cmd Demo [opts] args
 
292
 
 
293
                cmd Demo -h
 
294
 
 
295
            Blah blah blah.
 
296
            """
 
297
        cmd = cmd_Demo()
 
298
        helptext = cmd.get_help_text()
 
299
        self.assertEquals(helptext,
 
300
            'Purpose: A sample command.\n'
 
301
            'Usage:\n'
 
302
            '    cmd Demo [opts] args\n'
 
303
            '\n'
 
304
            '    cmd Demo -h\n'
 
305
            '\n'
 
306
            '\n'
 
307
            'Options:\n'
 
308
            '  --usage        Show usage message and options.\n'
 
309
            '  -v, --verbose  Display more information.\n'
 
310
            '  -q, --quiet    Only display errors and warnings.\n'
 
311
            '  -h, --help     Show help message.\n'
 
312
            '\n'
 
313
            'Description:\n'
 
314
            '  Blah blah blah.\n\n')
 
315
 
 
316
 
 
317
class ZzzTranslationsForDoc(ZzzTranslations):
 
318
 
 
319
    _section_pat = re.compile(':\w+:\\n\\s+')
 
320
    _indent_pat = re.compile('\\s+')
 
321
 
 
322
    def zzz(self, s):
 
323
        m = self._section_pat.match(s)
 
324
        if m is None:
 
325
            m = self._indent_pat.match(s)
 
326
        if m:
 
327
            return u'%szz{{%s}}' % (m.group(0), s[m.end():])
 
328
        return u'zz{{%s}}' % s
 
329
 
 
330
 
 
331
class TestCommandHelpI18n(tests.TestCase):
 
332
    """Tests for help on translated commands."""
 
333
 
 
334
    def setUp(self):
 
335
        super(TestCommandHelpI18n, self).setUp()
 
336
        self.overrideAttr(i18n, '_translations', ZzzTranslationsForDoc())
 
337
 
 
338
    def assertCmdHelp(self, expected, cmd):
 
339
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
 
340
 
 
341
    def test_command_help_includes_see_also(self):
 
342
        class cmd_WithSeeAlso(commands.Command):
 
343
            __doc__ = """A sample command."""
 
344
            _see_also = ['foo', 'bar']
 
345
        self.assertCmdHelp('''\
 
346
            zz{{:Purpose: zz{{A sample command.}}
 
347
            }}zz{{:Usage:   bzr WithSeeAlso
 
348
            }}
 
349
            zz{{:Options:
 
350
              --usage        zz{{Show usage message and options.}}
 
351
              -v, --verbose  zz{{Display more information.}}
 
352
              -q, --quiet    zz{{Only display errors and warnings.}}
 
353
              -h, --help     zz{{Show help message.}}
 
354
            }}
 
355
            zz{{:See also: bar, foo}}
 
356
            ''',
 
357
                           cmd_WithSeeAlso())
 
358
 
 
359
    def test_get_help_text(self):
 
360
        """Commands have a get_help_text method which returns their help."""
 
361
        class cmd_Demo(commands.Command):
 
362
            __doc__ = """A sample command."""
 
363
        self.assertCmdHelp('''\
 
364
            zz{{:Purpose: zz{{A sample command.}}
 
365
            }}zz{{:Usage:   bzr Demo
 
366
            }}
 
367
            zz{{:Options:
 
368
              --usage        zz{{Show usage message and options.}}
 
369
              -v, --verbose  zz{{Display more information.}}
 
370
              -q, --quiet    zz{{Only display errors and warnings.}}
 
371
              -h, --help     zz{{Show help message.}}
 
372
            }}
 
373
            ''',
 
374
                           cmd_Demo())
 
375
 
 
376
    def test_command_with_additional_see_also(self):
 
377
        class cmd_WithSeeAlso(commands.Command):
 
378
            __doc__ = """A sample command."""
 
379
            _see_also = ['foo', 'bar']
 
380
        cmd = cmd_WithSeeAlso()
 
381
        helptext = cmd.get_help_text(['gam'])
 
382
        self.assertEndsWith(
 
383
            helptext,
 
384
            '  -v, --verbose  zz{{Display more information.}}\n'
 
385
            '  -q, --quiet    zz{{Only display errors and warnings.}}\n'
 
386
            '  -h, --help     zz{{Show help message.}}\n'
 
387
            '}}\n'
 
388
            'zz{{:See also: bar, foo, gam}}\n')
 
389
 
 
390
    def test_command_only_additional_see_also(self):
 
391
        class cmd_WithSeeAlso(commands.Command):
 
392
            __doc__ = """A sample command."""
 
393
        cmd = cmd_WithSeeAlso()
 
394
        helptext = cmd.get_help_text(['gam'])
 
395
        self.assertEndsWith(
 
396
            helptext,
 
397
            'zz{{:Options:\n'
 
398
            '  --usage        zz{{Show usage message and options.}}\n'
 
399
            '  -v, --verbose  zz{{Display more information.}}\n'
 
400
            '  -q, --quiet    zz{{Only display errors and warnings.}}\n'
 
401
            '  -h, --help     zz{{Show help message.}}\n'
 
402
            '}}\n'
 
403
            'zz{{:See also: gam}}\n')
 
404
 
 
405
 
 
406
    def test_help_custom_section_ordering(self):
 
407
        """Custom descriptive sections should remain in the order given."""
 
408
        # The help formatter expect the class name to start with 'cmd_'
 
409
        class cmd_Demo(commands.Command):
 
410
            __doc__ = """A sample command.
 
411
 
 
412
            Blah blah blah.
 
413
 
 
414
            :Formats:
 
415
              Interesting stuff about formats.
 
416
 
 
417
            :Examples:
 
418
              Example 1::
 
419
 
 
420
                cmd arg1
 
421
 
 
422
            :Tips:
 
423
              Clever things to keep in mind.
 
424
            """
 
425
        self.assertCmdHelp('''\
 
426
            zz{{:Purpose: zz{{A sample command.}}
 
427
            }}zz{{:Usage:   bzr Demo
 
428
            }}
 
429
            zz{{:Options:
 
430
              --usage        zz{{Show usage message and options.}}
 
431
              -v, --verbose  zz{{Display more information.}}
 
432
              -q, --quiet    zz{{Only display errors and warnings.}}
 
433
              -h, --help     zz{{Show help message.}}
 
434
            }}
 
435
            Description:
 
436
              zz{{zz{{Blah blah blah.}}
 
437
            
 
438
            }}:Formats:
 
439
              zz{{Interesting stuff about formats.}}
 
440
            
 
441
            Examples:
 
442
              zz{{Example 1::}}
 
443
            
 
444
                zz{{cmd arg1}}
 
445
            
 
446
            Tips:
 
447
              zz{{Clever things to keep in mind.}}
 
448
 
 
449
            ''',
 
450
                           cmd_Demo())
 
451
 
 
452
    def test_help_text_custom_usage(self):
 
453
        """Help text may contain a custom usage section."""
 
454
        class cmd_Demo(commands.Command):
 
455
            __doc__ = """A sample command.
 
456
 
 
457
            :Usage:
 
458
                cmd Demo [opts] args
 
459
 
 
460
                cmd Demo -h
 
461
 
 
462
            Blah blah blah.
 
463
            """
 
464
        self.assertCmdHelp('''\
 
465
            zz{{:Purpose: zz{{A sample command.}}
 
466
            }}zz{{:Usage:
 
467
                zz{{cmd Demo [opts] args}}
 
468
            
 
469
                zz{{cmd Demo -h}}
 
470
 
 
471
            }}
 
472
            zz{{:Options:
 
473
              --usage        zz{{Show usage message and options.}}
 
474
              -v, --verbose  zz{{Display more information.}}
 
475
              -q, --quiet    zz{{Only display errors and warnings.}}
 
476
              -h, --help     zz{{Show help message.}}
 
477
            }}
 
478
            Description:
 
479
              zz{{zz{{Blah blah blah.}}
 
480
 
 
481
            }}
 
482
            ''',
 
483
                           cmd_Demo())
 
484
 
 
485
 
 
486
class TestHelp(tests.TestCase):
 
487
 
 
488
    def setUp(self):
 
489
        tests.TestCase.setUp(self)
 
490
        commands.install_bzr_command_hooks()
 
491
 
 
492
 
 
493
class TestRegisteredTopic(TestHelp):
 
494
    """Tests for the RegisteredTopic class."""
 
495
 
 
496
    def test_contruct(self):
 
497
        """Construction takes the help topic name for the registered item."""
 
498
        # validate our test
 
499
        self.assertTrue('basic' in help_topics.topic_registry)
 
500
        topic = help_topics.RegisteredTopic('basic')
 
501
        self.assertEqual('basic', topic.topic)
 
502
 
 
503
    def test_get_help_text(self):
 
504
        """RegisteredTopic returns the get_detail results for get_help_text."""
 
505
        topic = help_topics.RegisteredTopic('commands')
 
506
        self.assertEqual(help_topics.topic_registry.get_detail('commands'),
 
507
                         topic.get_help_text())
 
508
 
 
509
    def test_get_help_text_with_additional_see_also(self):
 
510
        topic = help_topics.RegisteredTopic('commands')
 
511
        self.assertEndsWith(
 
512
            topic.get_help_text(['foo', 'bar']),
 
513
            '\n'
 
514
            'See also: bar, foo\n')
 
515
 
 
516
    def test_get_help_text_loaded_from_file(self):
 
517
        # Pick a known topic stored in an external file
 
518
        topic = help_topics.RegisteredTopic('authentication')
 
519
        self.assertStartsWith(topic.get_help_text(),
 
520
            'Authentication Settings\n'
 
521
            '=======================\n'
 
522
            '\n')
 
523
 
 
524
    def test_get_help_topic(self):
 
525
        """The help topic for RegisteredTopic is its topic from construction."""
 
526
        topic = help_topics.RegisteredTopic('foobar')
 
527
        self.assertEqual('foobar', topic.get_help_topic())
 
528
        topic = help_topics.RegisteredTopic('baz')
 
529
        self.assertEqual('baz', topic.get_help_topic())
 
530
 
 
531
 
 
532
class TestTopicIndex(TestHelp):
 
533
    """Tests for the HelpTopicIndex class."""
 
534
 
 
535
    def test_default_constructable(self):
 
536
        index = help_topics.HelpTopicIndex()
 
537
 
 
538
    def test_get_topics_None(self):
 
539
        """Searching for None returns the basic help topic."""
 
540
        index = help_topics.HelpTopicIndex()
 
541
        topics = index.get_topics(None)
 
542
        self.assertEqual(1, len(topics))
 
543
        self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
 
544
        self.assertEqual('basic', topics[0].topic)
 
545
 
 
546
    def test_get_topics_topics(self):
 
547
        """Searching for a string returns the matching string."""
 
548
        index = help_topics.HelpTopicIndex()
 
549
        topics = index.get_topics('topics')
 
550
        self.assertEqual(1, len(topics))
 
551
        self.assertIsInstance(topics[0], help_topics.RegisteredTopic)
 
552
        self.assertEqual('topics', topics[0].topic)
 
553
 
 
554
    def test_get_topics_no_topic(self):
 
555
        """Searching for something not registered returns []."""
 
556
        index = help_topics.HelpTopicIndex()
 
557
        self.assertEqual([], index.get_topics('nothing by this name'))
 
558
 
 
559
    def test_prefix(self):
 
560
        """TopicIndex has a prefix of ''."""
 
561
        index = help_topics.HelpTopicIndex()
 
562
        self.assertEqual('', index.prefix)
 
563
 
 
564
 
 
565
class TestConfigOptionIndex(TestHelp):
 
566
    """Tests for the HelpCommandIndex class."""
 
567
 
 
568
    def setUp(self):
 
569
        super(TestConfigOptionIndex, self).setUp()
 
570
        self.index = help_topics.ConfigOptionHelpIndex()
 
571
 
 
572
    def test_get_topics_None(self):
 
573
        """Searching for None returns an empty list."""
 
574
        self.assertEqual([], self.index.get_topics(None))
 
575
 
 
576
    def test_get_topics_no_topic(self):
 
577
        self.assertEqual([], self.index.get_topics('nothing by this name'))
 
578
 
 
579
    def test_prefix(self):
 
580
        self.assertEqual('configuration/', self.index.prefix)
 
581
 
 
582
    def test_get_topic_with_prefix(self):
 
583
        topics = self.index.get_topics('configuration/default_format')
 
584
        self.assertLength(1, topics)
 
585
        opt = topics[0]
 
586
        self.assertIsInstance(opt, config.Option)
 
587
        self.assertEquals('default_format', opt.name)
 
588
 
 
589
 
 
590
class TestCommandIndex(TestHelp):
 
591
    """Tests for the HelpCommandIndex class."""
 
592
 
 
593
    def test_default_constructable(self):
 
594
        index = commands.HelpCommandIndex()
 
595
 
 
596
    def test_get_topics_None(self):
 
597
        """Searching for None returns an empty list."""
 
598
        index = commands.HelpCommandIndex()
 
599
        self.assertEqual([], index.get_topics(None))
 
600
 
 
601
    def test_get_topics_rocks(self):
 
602
        """Searching for 'rocks' returns the cmd_rocks command instance."""
 
603
        index = commands.HelpCommandIndex()
 
604
        topics = index.get_topics('rocks')
 
605
        self.assertEqual(1, len(topics))
 
606
        self.assertIsInstance(topics[0], builtins.cmd_rocks)
 
607
 
 
608
    def test_get_topics_no_topic(self):
 
609
        """Searching for something that is not a command returns []."""
 
610
        index = commands.HelpCommandIndex()
 
611
        self.assertEqual([], index.get_topics('nothing by this name'))
 
612
 
 
613
    def test_prefix(self):
 
614
        """CommandIndex has a prefix of 'commands/'."""
 
615
        index = commands.HelpCommandIndex()
 
616
        self.assertEqual('commands/', index.prefix)
 
617
 
 
618
    def test_get_topic_with_prefix(self):
 
619
        """Searching for commands/rocks returns the rocks command object."""
 
620
        index = commands.HelpCommandIndex()
 
621
        topics = index.get_topics('commands/rocks')
 
622
        self.assertEqual(1, len(topics))
 
623
        self.assertIsInstance(topics[0], builtins.cmd_rocks)
 
624
 
 
625
 
 
626
class TestHelpIndices(tests.TestCase):
 
627
    """Tests for the HelpIndices class."""
 
628
 
 
629
    def test_default_search_path(self):
 
630
        """The default search path should include internal indexs."""
 
631
        indices = help.HelpIndices()
 
632
        self.assertEqual(4, len(indices.search_path))
 
633
        # help topics should be searched in first.
 
634
        self.assertIsInstance(indices.search_path[0],
 
635
                              help_topics.HelpTopicIndex)
 
636
        # with commands being search second.
 
637
        self.assertIsInstance(indices.search_path[1],
 
638
                              commands.HelpCommandIndex)
 
639
        # plugins are a third index.
 
640
        self.assertIsInstance(indices.search_path[2],
 
641
                              plugin.PluginsHelpIndex)
 
642
        # config options are a fourth index
 
643
        self.assertIsInstance(indices.search_path[3],
 
644
                              help_topics.ConfigOptionHelpIndex)
 
645
 
 
646
    def test_search_for_unknown_topic_raises(self):
 
647
        """Searching for an unknown topic should raise NoHelpTopic."""
 
648
        indices = help.HelpIndices()
 
649
        indices.search_path = []
 
650
        error = self.assertRaises(errors.NoHelpTopic, indices.search, 'foo')
 
651
        self.assertEqual('foo', error.topic)
 
652
 
 
653
    def test_search_calls_get_topic(self):
 
654
        """Searching should call get_topics in all indexes in order."""
 
655
        calls = []
 
656
        class RecordingIndex(object):
 
657
            def __init__(self, name):
 
658
                self.prefix = name
 
659
            def get_topics(self, topic):
 
660
                calls.append(('get_topics', self.prefix, topic))
 
661
                return ['something']
 
662
        index = help.HelpIndices()
 
663
        index.search_path = [RecordingIndex('1'), RecordingIndex('2')]
 
664
        # try with None
 
665
        index.search(None)
 
666
        self.assertEqual([
 
667
            ('get_topics', '1', None),
 
668
            ('get_topics', '2', None),
 
669
            ],
 
670
            calls)
 
671
        # and with a string
 
672
        del calls[:]
 
673
        index.search('bar')
 
674
        self.assertEqual([
 
675
            ('get_topics', '1', 'bar'),
 
676
            ('get_topics', '2', 'bar'),
 
677
            ],
 
678
            calls)
 
679
 
 
680
    def test_search_returns_index_and_results(self):
 
681
        """Searching should return help topics with their index"""
 
682
        class CannedIndex(object):
 
683
            def __init__(self, prefix, search_result):
 
684
                self.prefix = prefix
 
685
                self.result = search_result
 
686
            def get_topics(self, topic):
 
687
                return self.result
 
688
        index = help.HelpIndices()
 
689
        index_one = CannedIndex('1', ['a'])
 
690
        index_two = CannedIndex('2', ['b', 'c'])
 
691
        index.search_path = [index_one, index_two]
 
692
        self.assertEqual([(index_one, 'a'), (index_two, 'b'), (index_two, 'c')],
 
693
            index.search(None))
 
694
 
 
695
    def test_search_checks_for_duplicate_prefixes(self):
 
696
        """Its an error when there are multiple indices with the same prefix."""
 
697
        indices = help.HelpIndices()
 
698
        indices.search_path = [help_topics.HelpTopicIndex(),
 
699
            help_topics.HelpTopicIndex()]
 
700
        self.assertRaises(errors.DuplicateHelpPrefix, indices.search, None)