← 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: Canonical.com Patch Queue Manager
  • Date: 2011-08-17 18:13:57 UTC
  • mfrom: (5268.7.29 transport-segments)
  • Revision ID: pqm@pqm.ubuntu.com-20110817181357-y5q5eth1hk8bl3om
(jelmer) Allow specifying the colocated branch to use in the branch URL,
 and retrieving the branch name using ControlDir._get_selected_branch.
 (Jelmer Vernooij)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/tests/test_help.py
1
 
# Copyright (C) 2007 Canonical Ltd
 
1
# Copyright (C) 2007-2011 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
16
16
 
17
17
"""Unit tests for the bzrlib.help module."""
18
18
 
19
 
from cStringIO import StringIO
 
19
import textwrap
20
20
 
21
21
from bzrlib import (
22
22
    builtins,
23
23
    commands,
 
24
    config,
24
25
    errors,
25
26
    help,
26
27
    help_topics,
 
28
    i18n,
27
29
    plugin,
28
30
    tests,
29
31
    )
30
32
 
31
 
 
32
 
class TestHelp(tests.TestCase):
33
 
 
34
 
    def setUp(self):
35
 
        tests.TestCase.setUp(self)
36
 
        commands.install_bzr_command_hooks()
 
33
from bzrlib.tests.test_i18n import ZzzTranslations
 
34
import re
37
35
 
38
36
 
39
37
class TestCommandHelp(tests.TestCase):
40
38
    """Tests for help on commands."""
41
39
 
 
40
    def assertCmdHelp(self, expected, cmd):
 
41
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
 
42
 
42
43
    def test_command_help_includes_see_also(self):
43
44
        class cmd_WithSeeAlso(commands.Command):
44
 
            """A sample command."""
 
45
            __doc__ = """A sample command."""
45
46
            _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')
 
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())
55
60
 
56
61
    def test_get_help_text(self):
57
62
        """Commands have a get_help_text method which returns their help."""
58
63
        class cmd_Demo(commands.Command):
59
 
            """A sample 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())
60
77
        cmd = cmd_Demo()
61
78
        helptext = cmd.get_help_text()
62
79
        self.assertStartsWith(helptext,
67
84
 
68
85
    def test_command_with_additional_see_also(self):
69
86
        class cmd_WithSeeAlso(commands.Command):
70
 
            """A sample command."""
 
87
            __doc__ = """A sample command."""
71
88
            _see_also = ['foo', 'bar']
72
89
        cmd = cmd_WithSeeAlso()
73
90
        helptext = cmd.get_help_text(['gam'])
81
98
 
82
99
    def test_command_only_additional_see_also(self):
83
100
        class cmd_WithSeeAlso(commands.Command):
84
 
            """A sample command."""
 
101
            __doc__ = """A sample command."""
85
102
        cmd = cmd_WithSeeAlso()
86
103
        helptext = cmd.get_help_text(['gam'])
87
104
        self.assertEndsWith(
95
112
    def test_get_help_topic(self):
96
113
        """The help topic for a Command is its name()."""
97
114
        class cmd_foo_bar(commands.Command):
98
 
            """A sample command."""
 
115
            __doc__ = """A sample command."""
99
116
        cmd = cmd_foo_bar()
100
117
        self.assertEqual(cmd.name(), cmd.get_help_topic())
101
118
 
102
119
    def test_formatted_help_text(self):
103
120
        """Help text should be plain text by default."""
104
121
        class cmd_Demo(commands.Command):
105
 
            """A sample command.
 
122
            __doc__ = """A sample command.
106
123
 
107
124
            :Examples:
108
125
                Example 1::
112
129
                Example 2::
113
130
 
114
131
                    cmd arg2
 
132
 
 
133
                A code block follows.
 
134
 
 
135
                ::
 
136
 
 
137
                    bzr Demo something
115
138
            """
116
139
        cmd = cmd_Demo()
117
140
        helptext = cmd.get_help_text()
134
157
            '    Example 2:\n'
135
158
            '\n'
136
159
            '        cmd arg2\n'
 
160
            '\n'
 
161
            '    A code block follows.\n'
 
162
            '\n'
 
163
            '        bzr Demo something\n'
137
164
            '\n')
138
165
        helptext = cmd.get_help_text(plain=False)
139
166
        self.assertEquals(helptext,
154
181
            '    Example 2::\n'
155
182
            '\n'
156
183
            '        cmd arg2\n'
 
184
            '\n'
 
185
            '    A code block follows.\n'
 
186
            '\n'
 
187
            '    ::\n'
 
188
            '\n'
 
189
            '        bzr Demo something\n'
157
190
            '\n')
158
191
 
159
192
    def test_concise_help_text(self):
160
193
        """Concise help text excludes the descriptive sections."""
161
194
        class cmd_Demo(commands.Command):
162
 
            """A sample command.
 
195
            __doc__ = """A sample command.
163
196
 
164
197
            Blah blah blah.
165
198
 
206
239
    def test_help_custom_section_ordering(self):
207
240
        """Custom descriptive sections should remain in the order given."""
208
241
        class cmd_Demo(commands.Command):
209
 
            """A sample command.
 
242
            __doc__ = """A sample command.
210
243
 
211
244
            Blah blah blah.
212
245
 
252
285
    def test_help_text_custom_usage(self):
253
286
        """Help text may contain a custom usage section."""
254
287
        class cmd_Demo(commands.Command):
255
 
            """A sample command.
 
288
            __doc__ = """A sample command.
256
289
 
257
290
            :Usage:
258
291
                cmd Demo [opts] args
281
314
            '  Blah blah blah.\n\n')
282
315
 
283
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        Show usage message and options.
 
351
              -v, --verbose  Display more information.
 
352
              -q, --quiet    Only display errors and warnings.
 
353
              -h, --help     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        Show usage message and options.
 
369
              -v, --verbose  Display more information.
 
370
              -q, --quiet    Only display errors and warnings.
 
371
              -h, --help     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  Display more information.\n'
 
385
            '  -q, --quiet    Only display errors and warnings.\n'
 
386
            '  -h, --help     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        Show usage message and options.\n'
 
399
            '  -v, --verbose  Display more information.\n'
 
400
            '  -q, --quiet    Only display errors and warnings.\n'
 
401
            '  -h, --help     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        Show usage message and options.
 
431
              -v, --verbose  Display more information.
 
432
              -q, --quiet    Only display errors and warnings.
 
433
              -h, --help     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        Show usage message and options.
 
474
              -v, --verbose  Display more information.
 
475
              -q, --quiet    Only display errors and warnings.
 
476
              -h, --help     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
 
284
493
class TestRegisteredTopic(TestHelp):
285
494
    """Tests for the RegisteredTopic class."""
286
495
 
292
501
        self.assertEqual('basic', topic.topic)
293
502
 
294
503
    def test_get_help_text(self):
295
 
        """A RegisteredTopic returns the get_detail results for get_help_text."""
 
504
        """RegisteredTopic returns the get_detail results for get_help_text."""
296
505
        topic = help_topics.RegisteredTopic('commands')
297
506
        self.assertEqual(help_topics.topic_registry.get_detail('commands'),
298
 
            topic.get_help_text())
 
507
                         topic.get_help_text())
299
508
 
300
509
    def test_get_help_text_with_additional_see_also(self):
301
510
        topic = help_topics.RegisteredTopic('commands')
313
522
            '\n')
314
523
 
315
524
    def test_get_help_topic(self):
316
 
        """The help topic for a RegisteredTopic is its topic from construction."""
 
525
        """The help topic for RegisteredTopic is its topic from construction."""
317
526
        topic = help_topics.RegisteredTopic('foobar')
318
527
        self.assertEqual('foobar', topic.get_help_topic())
319
528
        topic = help_topics.RegisteredTopic('baz')
353
562
        self.assertEqual('', index.prefix)
354
563
 
355
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
 
356
590
class TestCommandIndex(TestHelp):
357
591
    """Tests for the HelpCommandIndex class."""
358
592
 
395
629
    def test_default_search_path(self):
396
630
        """The default search path should include internal indexs."""
397
631
        indices = help.HelpIndices()
398
 
        self.assertEqual(3, len(indices.search_path))
 
632
        self.assertEqual(4, len(indices.search_path))
399
633
        # help topics should be searched in first.
400
634
        self.assertIsInstance(indices.search_path[0],
401
 
            help_topics.HelpTopicIndex)
 
635
                              help_topics.HelpTopicIndex)
402
636
        # with commands being search second.
403
637
        self.assertIsInstance(indices.search_path[1],
404
 
            commands.HelpCommandIndex)
405
 
        # and plugins are a third index.
 
638
                              commands.HelpCommandIndex)
 
639
        # plugins are a third index.
406
640
        self.assertIsInstance(indices.search_path[2],
407
 
            plugin.PluginsHelpIndex)
 
641
                              plugin.PluginsHelpIndex)
 
642
        # config options are a fourth index
 
643
        self.assertIsInstance(indices.search_path[3],
 
644
                              help_topics.ConfigOptionHelpIndex)
408
645
 
409
646
    def test_search_for_unknown_topic_raises(self):
410
647
        """Searching for an unknown topic should raise NoHelpTopic."""