← 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: 2008-09-11 19:36:38 UTC
  • mfrom: (3703 +trunk)
  • mto: (3705.1.1 trunk2)
  • mto: This revision was merged to the branch mainline in revision 3708.
  • Revision ID: v.ladeuil+lp@free.fr-20080911193638-wtjyc1kcmacc6t1f
merge bzr.dev

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,
23
23
    commands,
24
 
    config,
25
24
    errors,
26
25
    help,
27
26
    help_topics,
28
 
    i18n,
29
27
    plugin,
30
28
    tests,
31
29
    )
32
30
 
33
 
from bzrlib.tests.test_i18n import ZzzTranslations
34
 
import re
35
 
 
36
31
 
37
32
class TestCommandHelp(tests.TestCase):
38
33
    """Tests for help on commands."""
39
34
 
40
 
    def assertCmdHelp(self, expected, cmd):
41
 
        self.assertEqualDiff(textwrap.dedent(expected), cmd.get_help_text())
42
 
 
43
35
    def test_command_help_includes_see_also(self):
44
36
        class cmd_WithSeeAlso(commands.Command):
45
 
            __doc__ = """A sample command."""
 
37
            """A sample command."""
46
38
            _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())
 
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')
60
48
 
61
49
    def test_get_help_text(self):
62
50
        """Commands have a get_help_text method which returns their help."""
63
51
        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())
 
52
            """A sample command."""
77
53
        cmd = cmd_Demo()
78
54
        helptext = cmd.get_help_text()
79
55
        self.assertStartsWith(helptext,
84
60
 
85
61
    def test_command_with_additional_see_also(self):
86
62
        class cmd_WithSeeAlso(commands.Command):
87
 
            __doc__ = """A sample command."""
 
63
            """A sample command."""
88
64
            _see_also = ['foo', 'bar']
89
65
        cmd = cmd_WithSeeAlso()
90
66
        helptext = cmd.get_help_text(['gam'])
98
74
 
99
75
    def test_command_only_additional_see_also(self):
100
76
        class cmd_WithSeeAlso(commands.Command):
101
 
            __doc__ = """A sample command."""
 
77
            """A sample command."""
102
78
        cmd = cmd_WithSeeAlso()
103
79
        helptext = cmd.get_help_text(['gam'])
104
80
        self.assertEndsWith(
112
88
    def test_get_help_topic(self):
113
89
        """The help topic for a Command is its name()."""
114
90
        class cmd_foo_bar(commands.Command):
115
 
            __doc__ = """A sample command."""
 
91
            """A sample command."""
116
92
        cmd = cmd_foo_bar()
117
93
        self.assertEqual(cmd.name(), cmd.get_help_topic())
118
94
 
119
95
    def test_formatted_help_text(self):
120
96
        """Help text should be plain text by default."""
121
97
        class cmd_Demo(commands.Command):
122
 
            __doc__ = """A sample command.
123
 
 
 
98
            """A sample command.
 
99
 
124
100
            :Examples:
125
101
                Example 1::
126
 
 
 
102
 
127
103
                    cmd arg1
128
 
 
 
104
 
129
105
                Example 2::
130
 
 
 
106
 
131
107
                    cmd arg2
132
 
 
133
 
                A code block follows.
134
 
 
135
 
                ::
136
 
 
137
 
                    bzr Demo something
138
108
            """
139
109
        cmd = cmd_Demo()
140
110
        helptext = cmd.get_help_text()
144
114
            'Usage:   bzr Demo\n'
145
115
            '\n'
146
116
            'Options:\n'
147
 
            '  --usage        Show usage message and options.\n'
148
117
            '  -v, --verbose  Display more information.\n'
149
118
            '  -q, --quiet    Only display errors and warnings.\n'
150
119
            '  -h, --help     Show help message.\n'
157
126
            '    Example 2:\n'
158
127
            '\n'
159
128
            '        cmd arg2\n'
160
 
            '\n'
161
 
            '    A code block follows.\n'
162
 
            '\n'
163
 
            '        bzr Demo something\n'
164
129
            '\n')
165
130
        helptext = cmd.get_help_text(plain=False)
166
131
        self.assertEquals(helptext,
168
133
            ':Usage:   bzr Demo\n'
169
134
            '\n'
170
135
            ':Options:\n'
171
 
            '  --usage        Show usage message and options.\n'
172
136
            '  -v, --verbose  Display more information.\n'
173
137
            '  -q, --quiet    Only display errors and warnings.\n'
174
138
            '  -h, --help     Show help message.\n'
181
145
            '    Example 2::\n'
182
146
            '\n'
183
147
            '        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
148
            '\n')
284
149
 
285
150
    def test_help_text_custom_usage(self):
286
151
        """Help text may contain a custom usage section."""
287
152
        class cmd_Demo(commands.Command):
288
 
            __doc__ = """A sample command.
289
 
 
 
153
            """A sample command.
 
154
 
290
155
            :Usage:
291
156
                cmd Demo [opts] args
292
 
 
 
157
 
293
158
                cmd Demo -h
294
 
 
 
159
 
295
160
            Blah blah blah.
296
161
            """
297
162
        cmd = cmd_Demo()
305
170
            '\n'
306
171
            '\n'
307
172
            'Options:\n'
308
 
            '  --usage        Show usage message and options.\n'
309
173
            '  -v, --verbose  Display more information.\n'
310
174
            '  -q, --quiet    Only display errors and warnings.\n'
311
175
            '  -h, --help     Show help message.\n'
314
178
            '  Blah blah blah.\n\n')
315
179
 
316
180
 
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
 
 
493
 
class TestRegisteredTopic(TestHelp):
 
181
class TestRegisteredTopic(tests.TestCase):
494
182
    """Tests for the RegisteredTopic class."""
495
183
 
496
184
    def test_contruct(self):
497
185
        """Construction takes the help topic name for the registered item."""
498
 
        # validate our test
 
186
        # validate our test 
499
187
        self.assertTrue('basic' in help_topics.topic_registry)
500
188
        topic = help_topics.RegisteredTopic('basic')
501
189
        self.assertEqual('basic', topic.topic)
502
190
 
503
191
    def test_get_help_text(self):
504
 
        """RegisteredTopic returns the get_detail results for get_help_text."""
 
192
        """A RegisteredTopic returns the get_detail results for get_help_text."""
505
193
        topic = help_topics.RegisteredTopic('commands')
506
194
        self.assertEqual(help_topics.topic_registry.get_detail('commands'),
507
 
                         topic.get_help_text())
 
195
            topic.get_help_text())
508
196
 
509
197
    def test_get_help_text_with_additional_see_also(self):
510
198
        topic = help_topics.RegisteredTopic('commands')
515
203
 
516
204
    def test_get_help_text_loaded_from_file(self):
517
205
        # Pick a known topic stored in an external file
518
 
        topic = help_topics.RegisteredTopic('authentication')
 
206
        topic = help_topics.RegisteredTopic('hooks')
519
207
        self.assertStartsWith(topic.get_help_text(),
520
 
            'Authentication Settings\n'
521
 
            '=======================\n'
 
208
            'Hooks\n'
 
209
            '=====\n'
522
210
            '\n')
523
211
 
524
212
    def test_get_help_topic(self):
525
 
        """The help topic for RegisteredTopic is its topic from construction."""
 
213
        """The help topic for a RegisteredTopic is its topic from construction."""
526
214
        topic = help_topics.RegisteredTopic('foobar')
527
215
        self.assertEqual('foobar', topic.get_help_topic())
528
216
        topic = help_topics.RegisteredTopic('baz')
529
217
        self.assertEqual('baz', topic.get_help_topic())
530
218
 
531
219
 
532
 
class TestTopicIndex(TestHelp):
 
220
class TestTopicIndex(tests.TestCase):
533
221
    """Tests for the HelpTopicIndex class."""
534
222
 
535
223
    def test_default_constructable(self):
562
250
        self.assertEqual('', index.prefix)
563
251
 
564
252
 
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):
 
253
class TestCommandIndex(tests.TestCase):
591
254
    """Tests for the HelpCommandIndex class."""
592
255
 
593
256
    def test_default_constructable(self):
629
292
    def test_default_search_path(self):
630
293
        """The default search path should include internal indexs."""
631
294
        indices = help.HelpIndices()
632
 
        self.assertEqual(4, len(indices.search_path))
 
295
        self.assertEqual(3, len(indices.search_path))
633
296
        # help topics should be searched in first.
634
297
        self.assertIsInstance(indices.search_path[0],
635
 
                              help_topics.HelpTopicIndex)
 
298
            help_topics.HelpTopicIndex)
636
299
        # with commands being search second.
637
300
        self.assertIsInstance(indices.search_path[1],
638
 
                              commands.HelpCommandIndex)
639
 
        # plugins are a third index.
 
301
            commands.HelpCommandIndex)
 
302
        # and plugins are a third index.
640
303
        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)
 
304
            plugin.PluginsHelpIndex)
645
305
 
646
306
    def test_search_for_unknown_topic_raises(self):
647
307
        """Searching for an unknown topic should raise NoHelpTopic."""