← 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: Ian Clatworthy
  • Date: 2007-08-13 14:16:53 UTC
  • mto: (2733.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 2734.
  • Revision ID: ian.clatworthy@internode.on.net-20070813141653-3cbrp00xowq58zv1
Added mini tutorial

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/tests/test_help.py
1
 
# Copyright (C) 2007-2011 Canonical Ltd
 
1
# Copyright (C) 2007 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
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
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
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
17
"""Unit tests for the bzrlib.help module."""
18
18
 
19
 
import textwrap
 
19
from cStringIO import StringIO
20
20
 
21
21
from bzrlib import (
22
22
    builtins,
24
24
    errors,
25
25
    help,
26
26
    help_topics,
27
 
    i18n,
28
27
    plugin,
29
28
    tests,
30
29
    )
31
30
 
32
 
from bzrlib.tests.test_i18n import ZzzTranslations
33
 
import re
34
 
 
35
31
 
36
32
class TestCommandHelp(tests.TestCase):
37
33
    """Tests for help on commands."""
38
34
 
39
 
    def assertCmdHelp(self, expected, cmd):
40
 
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
41
 
 
42
35
    def test_command_help_includes_see_also(self):
43
36
        class cmd_WithSeeAlso(commands.Command):
44
 
            __doc__ = """A sample command."""
 
37
            """A sample command."""
45
38
            _see_also = ['foo', 'bar']
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())
 
39
        cmd = cmd_WithSeeAlso()
 
40
        helptext = cmd.get_help_text()
 
41
        self.assertEndsWith(
 
42
            helptext,
 
43
            '  -h, --help  Show help message.\n'
 
44
            '\n'
 
45
            'See also: bar, foo\n')
59
46
 
60
47
    def test_get_help_text(self):
61
48
        """Commands have a get_help_text method which returns their help."""
62
49
        class cmd_Demo(commands.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())
 
50
            """A sample command."""
76
51
        cmd = cmd_Demo()
77
52
        helptext = cmd.get_help_text()
78
53
        self.assertStartsWith(helptext,
79
54
            'Purpose: A sample command.\n'
80
55
            'Usage:   bzr Demo')
81
 
        self.assertEndsWith(helptext,
82
 
            '  -h, --help     Show help message.\n\n')
 
56
        self.assertEndsWith(helptext, 'Show help message.\n\n')
83
57
 
84
58
    def test_command_with_additional_see_also(self):
85
59
        class cmd_WithSeeAlso(commands.Command):
86
 
            __doc__ = """A sample command."""
 
60
            """A sample command."""
87
61
            _see_also = ['foo', 'bar']
88
62
        cmd = cmd_WithSeeAlso()
89
63
        helptext = cmd.get_help_text(['gam'])
90
64
        self.assertEndsWith(
91
65
            helptext,
92
 
            '  -v, --verbose  Display more information.\n'
93
 
            '  -q, --quiet    Only display errors and warnings.\n'
94
 
            '  -h, --help     Show help message.\n'
 
66
            '  -h, --help  Show help message.\n'
95
67
            '\n'
96
68
            'See also: bar, foo, gam\n')
97
69
 
98
70
    def test_command_only_additional_see_also(self):
99
71
        class cmd_WithSeeAlso(commands.Command):
100
 
            __doc__ = """A sample command."""
 
72
            """A sample command."""
101
73
        cmd = cmd_WithSeeAlso()
102
74
        helptext = cmd.get_help_text(['gam'])
103
75
        self.assertEndsWith(
104
76
            helptext,
105
 
            '  -v, --verbose  Display more information.\n'
106
 
            '  -q, --quiet    Only display errors and warnings.\n'
107
 
            '  -h, --help     Show help message.\n'
 
77
            '  -h, --help  Show help message.\n'
108
78
            '\n'
109
79
            'See also: gam\n')
110
80
 
111
81
    def test_get_help_topic(self):
112
82
        """The help topic for a Command is its name()."""
113
83
        class cmd_foo_bar(commands.Command):
114
 
            __doc__ = """A sample command."""
 
84
            """A sample command."""
115
85
        cmd = cmd_foo_bar()
116
86
        self.assertEqual(cmd.name(), cmd.get_help_topic())
117
87
 
118
88
    def test_formatted_help_text(self):
119
89
        """Help text should be plain text by default."""
120
90
        class cmd_Demo(commands.Command):
121
 
            __doc__ = """A sample command.
122
 
 
 
91
            """A sample command.
 
92
 
123
93
            :Examples:
124
94
                Example 1::
125
 
 
 
95
 
126
96
                    cmd arg1
127
 
 
 
97
 
128
98
                Example 2::
129
 
 
 
99
 
130
100
                    cmd arg2
131
 
 
132
 
                A code block follows.
133
 
 
134
 
                ::
135
 
 
136
 
                    bzr Demo something
137
101
            """
138
102
        cmd = cmd_Demo()
139
103
        helptext = cmd.get_help_text()
143
107
            'Usage:   bzr Demo\n'
144
108
            '\n'
145
109
            'Options:\n'
146
 
            '  --usage        Show usage message and options.\n'
147
 
            '  -v, --verbose  Display more information.\n'
148
 
            '  -q, --quiet    Only display errors and warnings.\n'
149
 
            '  -h, --help     Show help message.\n'
 
110
            '  -h, --help  Show help message.\n'
150
111
            '\n'
151
112
            'Examples:\n'
152
113
            '    Example 1:\n'
156
117
            '    Example 2:\n'
157
118
            '\n'
158
119
            '        cmd arg2\n'
159
 
            '\n'
160
 
            '    A code block follows.\n'
161
 
            '\n'
162
 
            '        bzr Demo something\n'
163
120
            '\n')
164
121
        helptext = cmd.get_help_text(plain=False)
165
122
        self.assertEquals(helptext,
167
124
            ':Usage:   bzr Demo\n'
168
125
            '\n'
169
126
            ':Options:\n'
170
 
            '  --usage        Show usage message and options.\n'
171
 
            '  -v, --verbose  Display more information.\n'
172
 
            '  -q, --quiet    Only display errors and warnings.\n'
173
 
            '  -h, --help     Show help message.\n'
 
127
            '  -h, --help  Show help message.\n'
174
128
            '\n'
175
129
            ':Examples:\n'
176
130
            '    Example 1::\n'
180
134
            '    Example 2::\n'
181
135
            '\n'
182
136
            '        cmd arg2\n'
183
 
            '\n'
184
 
            '    A code block follows.\n'
185
 
            '\n'
186
 
            '    ::\n'
187
 
            '\n'
188
 
            '        bzr Demo something\n'
189
 
            '\n')
190
 
 
191
 
    def test_concise_help_text(self):
192
 
        """Concise help text excludes the descriptive sections."""
193
 
        class cmd_Demo(commands.Command):
194
 
            __doc__ = """A sample command.
195
 
 
196
 
            Blah blah blah.
197
 
 
198
 
            :Examples:
199
 
                Example 1::
200
 
 
201
 
                    cmd arg1
202
 
            """
203
 
        cmd = cmd_Demo()
204
 
        helptext = cmd.get_help_text()
205
 
        self.assertEqualDiff(
206
 
            helptext,
207
 
            'Purpose: A sample command.\n'
208
 
            'Usage:   bzr Demo\n'
209
 
            '\n'
210
 
            'Options:\n'
211
 
            '  --usage        Show usage message and options.\n'
212
 
            '  -v, --verbose  Display more information.\n'
213
 
            '  -q, --quiet    Only display errors and warnings.\n'
214
 
            '  -h, --help     Show help message.\n'
215
 
            '\n'
216
 
            'Description:\n'
217
 
            '  Blah blah blah.\n'
218
 
            '\n'
219
 
            'Examples:\n'
220
 
            '    Example 1:\n'
221
 
            '\n'
222
 
            '        cmd arg1\n'
223
 
            '\n')
224
 
        helptext = cmd.get_help_text(verbose=False)
225
 
        self.assertEquals(helptext,
226
 
            'Purpose: A sample command.\n'
227
 
            'Usage:   bzr Demo\n'
228
 
            '\n'
229
 
            'Options:\n'
230
 
            '  --usage        Show usage message and options.\n'
231
 
            '  -v, --verbose  Display more information.\n'
232
 
            '  -q, --quiet    Only display errors and warnings.\n'
233
 
            '  -h, --help     Show help message.\n'
234
 
            '\n'
235
 
            'See bzr help Demo for more details and examples.\n'
236
 
            '\n')
237
 
 
238
 
    def test_help_custom_section_ordering(self):
239
 
        """Custom descriptive sections should remain in the order given."""
240
 
        class cmd_Demo(commands.Command):
241
 
            __doc__ = """A sample command.
242
 
 
243
 
            Blah blah blah.
244
 
 
245
 
            :Formats:
246
 
              Interesting stuff about formats.
247
 
 
248
 
            :Examples:
249
 
              Example 1::
250
 
 
251
 
                cmd arg1
252
 
 
253
 
            :Tips:
254
 
              Clever things to keep in mind.
255
 
            """
256
 
        cmd = cmd_Demo()
257
 
        helptext = cmd.get_help_text()
258
 
        self.assertEqualDiff(
259
 
            helptext,
260
 
            'Purpose: A sample command.\n'
261
 
            'Usage:   bzr Demo\n'
262
 
            '\n'
263
 
            'Options:\n'
264
 
            '  --usage        Show usage message and options.\n'
265
 
            '  -v, --verbose  Display more information.\n'
266
 
            '  -q, --quiet    Only display errors and warnings.\n'
267
 
            '  -h, --help     Show help message.\n'
268
 
            '\n'
269
 
            'Description:\n'
270
 
            '  Blah blah blah.\n'
271
 
            '\n'
272
 
            'Formats:\n'
273
 
            '  Interesting stuff about formats.\n'
274
 
            '\n'
275
 
            'Examples:\n'
276
 
            '  Example 1:\n'
277
 
            '\n'
278
 
            '    cmd arg1\n'
279
 
            '\n'
280
 
            'Tips:\n'
281
 
            '  Clever things to keep in mind.\n'
282
137
            '\n')
283
138
 
284
139
    def test_help_text_custom_usage(self):
285
140
        """Help text may contain a custom usage section."""
286
141
        class cmd_Demo(commands.Command):
287
 
            __doc__ = """A sample command.
288
 
 
 
142
            """A sample command.
 
143
 
289
144
            :Usage:
290
145
                cmd Demo [opts] args
291
 
 
 
146
 
292
147
                cmd Demo -h
293
 
 
 
148
 
294
149
            Blah blah blah.
295
150
            """
296
151
        cmd = cmd_Demo()
304
159
            '\n'
305
160
            '\n'
306
161
            'Options:\n'
307
 
            '  --usage        Show usage message and options.\n'
308
 
            '  -v, --verbose  Display more information.\n'
309
 
            '  -q, --quiet    Only display errors and warnings.\n'
310
 
            '  -h, --help     Show help message.\n'
 
162
            '  -h, --help  Show help message.\n'
311
163
            '\n'
312
164
            'Description:\n'
313
165
            '  Blah blah blah.\n\n')
314
166
 
315
167
 
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
 
 
492
 
class TestRegisteredTopic(TestHelp):
 
168
class TestRegisteredTopic(tests.TestCase):
493
169
    """Tests for the RegisteredTopic class."""
494
170
 
495
171
    def test_contruct(self):
496
172
        """Construction takes the help topic name for the registered item."""
497
 
        # validate our test
 
173
        # validate our test 
498
174
        self.assertTrue('basic' in help_topics.topic_registry)
499
175
        topic = help_topics.RegisteredTopic('basic')
500
176
        self.assertEqual('basic', topic.topic)
501
177
 
502
178
    def test_get_help_text(self):
503
 
        """RegisteredTopic returns the get_detail results for get_help_text."""
 
179
        """A RegisteredTopic returns the get_detail results for get_help_text."""
504
180
        topic = help_topics.RegisteredTopic('commands')
505
181
        self.assertEqual(help_topics.topic_registry.get_detail('commands'),
506
 
                         topic.get_help_text())
 
182
            topic.get_help_text())
507
183
 
508
184
    def test_get_help_text_with_additional_see_also(self):
509
185
        topic = help_topics.RegisteredTopic('commands')
512
188
            '\n'
513
189
            'See also: bar, foo\n')
514
190
 
515
 
    def test_get_help_text_loaded_from_file(self):
516
 
        # Pick a known topic stored in an external file
517
 
        topic = help_topics.RegisteredTopic('authentication')
518
 
        self.assertStartsWith(topic.get_help_text(),
519
 
            'Authentication Settings\n'
520
 
            '=======================\n'
521
 
            '\n')
522
 
 
523
191
    def test_get_help_topic(self):
524
 
        """The help topic for RegisteredTopic is its topic from construction."""
 
192
        """The help topic for a RegisteredTopic is its topic from construction."""
525
193
        topic = help_topics.RegisteredTopic('foobar')
526
194
        self.assertEqual('foobar', topic.get_help_topic())
527
195
        topic = help_topics.RegisteredTopic('baz')
528
196
        self.assertEqual('baz', topic.get_help_topic())
529
197
 
530
198
 
531
 
class TestTopicIndex(TestHelp):
 
199
class TestTopicIndex(tests.TestCase):
532
200
    """Tests for the HelpTopicIndex class."""
533
201
 
534
202
    def test_default_constructable(self):
561
229
        self.assertEqual('', index.prefix)
562
230
 
563
231
 
564
 
class TestCommandIndex(TestHelp):
 
232
class TestCommandIndex(tests.TestCase):
565
233
    """Tests for the HelpCommandIndex class."""
566
234
 
567
235
    def test_default_constructable(self):