← 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: Vincent Ladeuil
  • Date: 2011-09-09 13:30:12 UTC
  • mfrom: (5609.48.11 2.3)
  • mto: (6015.33.3 2.4)
  • mto: This revision was merged to the branch mainline in revision 6134.
  • Revision ID: v.ladeuil+lp@free.fr-20110909133012-jc1d1zyqgak57123
Merge 2.3 into 2.4

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,
24
24
    errors,
25
25
    help,
26
26
    help_topics,
 
27
    i18n,
27
28
    plugin,
28
29
    tests,
29
30
    )
30
31
 
31
 
 
32
 
class TestHelp(tests.TestCase):
33
 
 
34
 
    def setUp(self):
35
 
        tests.TestCase.setUp(self)
36
 
        commands.install_bzr_command_hooks()
 
32
from bzrlib.tests.test_i18n import ZzzTranslations
 
33
import re
37
34
 
38
35
 
39
36
class TestCommandHelp(tests.TestCase):
40
37
    """Tests for help on commands."""
41
38
 
 
39
    def assertCmdHelp(self, expected, cmd):
 
40
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
 
41
 
42
42
    def test_command_help_includes_see_also(self):
43
43
        class cmd_WithSeeAlso(commands.Command):
44
 
            """A sample command."""
 
44
            __doc__ = """A sample command."""
45
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')
 
46
        self.assertCmdHelp('''\
 
47
            Purpose: A sample command.
 
48
            Usage:   bzr WithSeeAlso
 
49
            
 
50
            Options:
 
51
              --usage        Show usage message and options.
 
52
              -v, --verbose  Display more information.
 
53
              -q, --quiet    Only display errors and warnings.
 
54
              -h, --help     Show help message.
 
55
            
 
56
            See also: bar, foo
 
57
            ''',
 
58
                           cmd_WithSeeAlso())
55
59
 
56
60
    def test_get_help_text(self):
57
61
        """Commands have a get_help_text method which returns their help."""
58
62
        class cmd_Demo(commands.Command):
59
 
            """A sample command."""
 
63
            __doc__ = """A sample command."""
 
64
        self.assertCmdHelp('''\
 
65
            Purpose: A sample command.
 
66
            Usage:   bzr Demo
 
67
            
 
68
            Options:
 
69
              --usage        Show usage message and options.
 
70
              -v, --verbose  Display more information.
 
71
              -q, --quiet    Only display errors and warnings.
 
72
              -h, --help     Show help message.
 
73
 
 
74
            ''',
 
75
                           cmd_Demo())
60
76
        cmd = cmd_Demo()
61
77
        helptext = cmd.get_help_text()
62
78
        self.assertStartsWith(helptext,
67
83
 
68
84
    def test_command_with_additional_see_also(self):
69
85
        class cmd_WithSeeAlso(commands.Command):
70
 
            """A sample command."""
 
86
            __doc__ = """A sample command."""
71
87
            _see_also = ['foo', 'bar']
72
88
        cmd = cmd_WithSeeAlso()
73
89
        helptext = cmd.get_help_text(['gam'])
81
97
 
82
98
    def test_command_only_additional_see_also(self):
83
99
        class cmd_WithSeeAlso(commands.Command):
84
 
            """A sample command."""
 
100
            __doc__ = """A sample command."""
85
101
        cmd = cmd_WithSeeAlso()
86
102
        helptext = cmd.get_help_text(['gam'])
87
103
        self.assertEndsWith(
95
111
    def test_get_help_topic(self):
96
112
        """The help topic for a Command is its name()."""
97
113
        class cmd_foo_bar(commands.Command):
98
 
            """A sample command."""
 
114
            __doc__ = """A sample command."""
99
115
        cmd = cmd_foo_bar()
100
116
        self.assertEqual(cmd.name(), cmd.get_help_topic())
101
117
 
102
118
    def test_formatted_help_text(self):
103
119
        """Help text should be plain text by default."""
104
120
        class cmd_Demo(commands.Command):
105
 
            """A sample command.
 
121
            __doc__ = """A sample command.
106
122
 
107
123
            :Examples:
108
124
                Example 1::
112
128
                Example 2::
113
129
 
114
130
                    cmd arg2
 
131
 
 
132
                A code block follows.
 
133
 
 
134
                ::
 
135
 
 
136
                    bzr Demo something
115
137
            """
116
138
        cmd = cmd_Demo()
117
139
        helptext = cmd.get_help_text()
134
156
            '    Example 2:\n'
135
157
            '\n'
136
158
            '        cmd arg2\n'
 
159
            '\n'
 
160
            '    A code block follows.\n'
 
161
            '\n'
 
162
            '        bzr Demo something\n'
137
163
            '\n')
138
164
        helptext = cmd.get_help_text(plain=False)
139
165
        self.assertEquals(helptext,
154
180
            '    Example 2::\n'
155
181
            '\n'
156
182
            '        cmd arg2\n'
 
183
            '\n'
 
184
            '    A code block follows.\n'
 
185
            '\n'
 
186
            '    ::\n'
 
187
            '\n'
 
188
            '        bzr Demo something\n'
157
189
            '\n')
158
190
 
159
191
    def test_concise_help_text(self):
160
192
        """Concise help text excludes the descriptive sections."""
161
193
        class cmd_Demo(commands.Command):
162
 
            """A sample command.
 
194
            __doc__ = """A sample command.
163
195
 
164
196
            Blah blah blah.
165
197
 
206
238
    def test_help_custom_section_ordering(self):
207
239
        """Custom descriptive sections should remain in the order given."""
208
240
        class cmd_Demo(commands.Command):
209
 
            """A sample command.
 
241
            __doc__ = """A sample command.
210
242
 
211
243
            Blah blah blah.
212
244
 
252
284
    def test_help_text_custom_usage(self):
253
285
        """Help text may contain a custom usage section."""
254
286
        class cmd_Demo(commands.Command):
255
 
            """A sample command.
 
287
            __doc__ = """A sample command.
256
288
 
257
289
            :Usage:
258
290
                cmd Demo [opts] args
281
313
            '  Blah blah blah.\n\n')
282
314
 
283
315
 
 
316
class ZzzTranslationsForDoc(ZzzTranslations):
 
317
 
 
318
    _section_pat = re.compile(':\w+:\\n\\s+')
 
319
    _indent_pat = re.compile('\\s+')
 
320
 
 
321
    def zzz(self, s):
 
322
        m = self._section_pat.match(s)
 
323
        if m is None:
 
324
            m = self._indent_pat.match(s)
 
325
        if m:
 
326
            return u'%szz{{%s}}' % (m.group(0), s[m.end():])
 
327
        return u'zz{{%s}}' % s
 
328
 
 
329
 
 
330
class TestCommandHelpI18n(tests.TestCase):
 
331
    """Tests for help on translated commands."""
 
332
 
 
333
    def setUp(self):
 
334
        super(TestCommandHelpI18n, self).setUp()
 
335
        self.overrideAttr(i18n, '_translations', ZzzTranslationsForDoc())
 
336
 
 
337
    def assertCmdHelp(self, expected, cmd):
 
338
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
 
339
 
 
340
    def test_command_help_includes_see_also(self):
 
341
        class cmd_WithSeeAlso(commands.Command):
 
342
            __doc__ = """A sample command."""
 
343
            _see_also = ['foo', 'bar']
 
344
        self.assertCmdHelp('''\
 
345
            zz{{:Purpose: zz{{A sample command.}}
 
346
            }}zz{{:Usage:   bzr WithSeeAlso
 
347
            }}
 
348
            zz{{:Options:
 
349
              --usage        Show usage message and options.
 
350
              -v, --verbose  Display more information.
 
351
              -q, --quiet    Only display errors and warnings.
 
352
              -h, --help     Show help message.
 
353
            }}
 
354
            zz{{:See also: bar, foo}}
 
355
            ''',
 
356
                           cmd_WithSeeAlso())
 
357
 
 
358
    def test_get_help_text(self):
 
359
        """Commands have a get_help_text method which returns their help."""
 
360
        class cmd_Demo(commands.Command):
 
361
            __doc__ = """A sample command."""
 
362
        self.assertCmdHelp('''\
 
363
            zz{{:Purpose: zz{{A sample command.}}
 
364
            }}zz{{:Usage:   bzr Demo
 
365
            }}
 
366
            zz{{:Options:
 
367
              --usage        Show usage message and options.
 
368
              -v, --verbose  Display more information.
 
369
              -q, --quiet    Only display errors and warnings.
 
370
              -h, --help     Show help message.
 
371
            }}
 
372
            ''',
 
373
                           cmd_Demo())
 
374
 
 
375
    def test_command_with_additional_see_also(self):
 
376
        class cmd_WithSeeAlso(commands.Command):
 
377
            __doc__ = """A sample command."""
 
378
            _see_also = ['foo', 'bar']
 
379
        cmd = cmd_WithSeeAlso()
 
380
        helptext = cmd.get_help_text(['gam'])
 
381
        self.assertEndsWith(
 
382
            helptext,
 
383
            '  -v, --verbose  Display more information.\n'
 
384
            '  -q, --quiet    Only display errors and warnings.\n'
 
385
            '  -h, --help     Show help message.\n'
 
386
            '}}\n'
 
387
            'zz{{:See also: bar, foo, gam}}\n')
 
388
 
 
389
    def test_command_only_additional_see_also(self):
 
390
        class cmd_WithSeeAlso(commands.Command):
 
391
            __doc__ = """A sample command."""
 
392
        cmd = cmd_WithSeeAlso()
 
393
        helptext = cmd.get_help_text(['gam'])
 
394
        self.assertEndsWith(
 
395
            helptext,
 
396
            'zz{{:Options:\n'
 
397
            '  --usage        Show usage message and options.\n'
 
398
            '  -v, --verbose  Display more information.\n'
 
399
            '  -q, --quiet    Only display errors and warnings.\n'
 
400
            '  -h, --help     Show help message.\n'
 
401
            '}}\n'
 
402
            'zz{{:See also: gam}}\n')
 
403
 
 
404
 
 
405
    def test_help_custom_section_ordering(self):
 
406
        """Custom descriptive sections should remain in the order given."""
 
407
        # The help formatter expect the class name to start with 'cmd_'
 
408
        class cmd_Demo(commands.Command):
 
409
            __doc__ = """A sample command.
 
410
 
 
411
            Blah blah blah.
 
412
 
 
413
            :Formats:
 
414
              Interesting stuff about formats.
 
415
 
 
416
            :Examples:
 
417
              Example 1::
 
418
 
 
419
                cmd arg1
 
420
 
 
421
            :Tips:
 
422
              Clever things to keep in mind.
 
423
            """
 
424
        self.assertCmdHelp('''\
 
425
            zz{{:Purpose: zz{{A sample command.}}
 
426
            }}zz{{:Usage:   bzr Demo
 
427
            }}
 
428
            zz{{:Options:
 
429
              --usage        Show usage message and options.
 
430
              -v, --verbose  Display more information.
 
431
              -q, --quiet    Only display errors and warnings.
 
432
              -h, --help     Show help message.
 
433
            }}
 
434
            Description:
 
435
              zz{{zz{{Blah blah blah.}}
 
436
            
 
437
            }}:Formats:
 
438
              zz{{Interesting stuff about formats.}}
 
439
            
 
440
            Examples:
 
441
              zz{{Example 1::}}
 
442
            
 
443
                zz{{cmd arg1}}
 
444
            
 
445
            Tips:
 
446
              zz{{Clever things to keep in mind.}}
 
447
 
 
448
            ''',
 
449
                           cmd_Demo())
 
450
 
 
451
    def test_help_text_custom_usage(self):
 
452
        """Help text may contain a custom usage section."""
 
453
        class cmd_Demo(commands.Command):
 
454
            __doc__ = """A sample command.
 
455
 
 
456
            :Usage:
 
457
                cmd Demo [opts] args
 
458
 
 
459
                cmd Demo -h
 
460
 
 
461
            Blah blah blah.
 
462
            """
 
463
        self.assertCmdHelp('''\
 
464
            zz{{:Purpose: zz{{A sample command.}}
 
465
            }}zz{{:Usage:
 
466
                zz{{cmd Demo [opts] args}}
 
467
            
 
468
                zz{{cmd Demo -h}}
 
469
 
 
470
            }}
 
471
            zz{{:Options:
 
472
              --usage        Show usage message and options.
 
473
              -v, --verbose  Display more information.
 
474
              -q, --quiet    Only display errors and warnings.
 
475
              -h, --help     Show help message.
 
476
            }}
 
477
            Description:
 
478
              zz{{zz{{Blah blah blah.}}
 
479
 
 
480
            }}
 
481
            ''',
 
482
                           cmd_Demo())
 
483
 
 
484
 
 
485
class TestHelp(tests.TestCase):
 
486
 
 
487
    def setUp(self):
 
488
        tests.TestCase.setUp(self)
 
489
        commands.install_bzr_command_hooks()
 
490
 
 
491
 
284
492
class TestRegisteredTopic(TestHelp):
285
493
    """Tests for the RegisteredTopic class."""
286
494
 
292
500
        self.assertEqual('basic', topic.topic)
293
501
 
294
502
    def test_get_help_text(self):
295
 
        """A RegisteredTopic returns the get_detail results for get_help_text."""
 
503
        """RegisteredTopic returns the get_detail results for get_help_text."""
296
504
        topic = help_topics.RegisteredTopic('commands')
297
505
        self.assertEqual(help_topics.topic_registry.get_detail('commands'),
298
 
            topic.get_help_text())
 
506
                         topic.get_help_text())
299
507
 
300
508
    def test_get_help_text_with_additional_see_also(self):
301
509
        topic = help_topics.RegisteredTopic('commands')
313
521
            '\n')
314
522
 
315
523
    def test_get_help_topic(self):
316
 
        """The help topic for a RegisteredTopic is its topic from construction."""
 
524
        """The help topic for RegisteredTopic is its topic from construction."""
317
525
        topic = help_topics.RegisteredTopic('foobar')
318
526
        self.assertEqual('foobar', topic.get_help_topic())
319
527
        topic = help_topics.RegisteredTopic('baz')