blob: 443c9624987c628768379ac796346e7d49206494 [file] [log] [blame]
Tim Peters8485b562004-08-04 18:46:34 +00001"""
2Test script for doctest.
3"""
4
Barry Warsaw04f357c2002-07-23 19:04:11 +00005from test import test_support
Tim Peters8485b562004-08-04 18:46:34 +00006import doctest
Tim Petersa7def722004-08-23 22:13:22 +00007import warnings
Tim Peters8485b562004-08-04 18:46:34 +00008
9######################################################################
10## Sample Objects (used by test cases)
11######################################################################
12
13def sample_func(v):
14 """
Tim Peters19397e52004-08-06 22:02:59 +000015 Blah blah
16
Tim Peters8485b562004-08-04 18:46:34 +000017 >>> print sample_func(22)
18 44
Tim Peters19397e52004-08-06 22:02:59 +000019
20 Yee ha!
Tim Peters8485b562004-08-04 18:46:34 +000021 """
22 return v+v
23
24class SampleClass:
25 """
26 >>> print 1
27 1
Edward Loper4ae900f2004-09-21 03:20:34 +000028
29 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
30 >>>
31 ...
32
33 Multiline example:
34 >>> sc = SampleClass(3)
35 >>> for i in range(10):
36 ... sc = sc.double()
37 ... print sc.get(),
38 6 12 24 48 96 192 384 768 1536 3072
Tim Peters8485b562004-08-04 18:46:34 +000039 """
40 def __init__(self, val):
41 """
42 >>> print SampleClass(12).get()
43 12
44 """
45 self.val = val
46
47 def double(self):
48 """
49 >>> print SampleClass(12).double().get()
50 24
51 """
52 return SampleClass(self.val + self.val)
53
54 def get(self):
55 """
56 >>> print SampleClass(-5).get()
57 -5
58 """
59 return self.val
60
61 def a_staticmethod(v):
62 """
63 >>> print SampleClass.a_staticmethod(10)
64 11
65 """
66 return v+1
67 a_staticmethod = staticmethod(a_staticmethod)
68
69 def a_classmethod(cls, v):
70 """
71 >>> print SampleClass.a_classmethod(10)
72 12
73 >>> print SampleClass(0).a_classmethod(10)
74 12
75 """
76 return v+2
77 a_classmethod = classmethod(a_classmethod)
78
79 a_property = property(get, doc="""
80 >>> print SampleClass(22).a_property
81 22
82 """)
83
84 class NestedClass:
85 """
86 >>> x = SampleClass.NestedClass(5)
87 >>> y = x.square()
88 >>> print y.get()
89 25
90 """
91 def __init__(self, val=0):
92 """
93 >>> print SampleClass.NestedClass().get()
94 0
95 """
96 self.val = val
97 def square(self):
98 return SampleClass.NestedClass(self.val*self.val)
99 def get(self):
100 return self.val
101
102class SampleNewStyleClass(object):
103 r"""
104 >>> print '1\n2\n3'
105 1
106 2
107 3
108 """
109 def __init__(self, val):
110 """
111 >>> print SampleNewStyleClass(12).get()
112 12
113 """
114 self.val = val
115
116 def double(self):
117 """
118 >>> print SampleNewStyleClass(12).double().get()
119 24
120 """
121 return SampleNewStyleClass(self.val + self.val)
122
123 def get(self):
124 """
125 >>> print SampleNewStyleClass(-5).get()
126 -5
127 """
128 return self.val
129
130######################################################################
Edward Loper2de91ba2004-08-27 02:07:46 +0000131## Fake stdin (for testing interactive debugging)
132######################################################################
133
134class _FakeInput:
135 """
136 A fake input stream for pdb's interactive debugger. Whenever a
137 line is read, print it (to simulate the user typing it), and then
138 return it. The set of lines to return is specified in the
139 constructor; they should not have trailing newlines.
140 """
141 def __init__(self, lines):
142 self.lines = lines
143
144 def readline(self):
145 line = self.lines.pop(0)
146 print line
147 return line+'\n'
148
149######################################################################
Tim Peters8485b562004-08-04 18:46:34 +0000150## Test Cases
151######################################################################
152
153def test_Example(): r"""
154Unit tests for the `Example` class.
155
Edward Lopera6b68322004-08-26 00:05:43 +0000156Example is a simple container class that holds:
157 - `source`: A source string.
158 - `want`: An expected output string.
159 - `exc_msg`: An expected exception message string (or None if no
160 exception is expected).
161 - `lineno`: A line number (within the docstring).
162 - `indent`: The example's indentation in the input string.
163 - `options`: An option dictionary, mapping option flags to True or
164 False.
Tim Peters8485b562004-08-04 18:46:34 +0000165
Edward Lopera6b68322004-08-26 00:05:43 +0000166These attributes are set by the constructor. `source` and `want` are
167required; the other attributes all have default values:
Tim Peters8485b562004-08-04 18:46:34 +0000168
Edward Lopera6b68322004-08-26 00:05:43 +0000169 >>> example = doctest.Example('print 1', '1\n')
170 >>> (example.source, example.want, example.exc_msg,
171 ... example.lineno, example.indent, example.options)
172 ('print 1\n', '1\n', None, 0, 0, {})
173
174The first three attributes (`source`, `want`, and `exc_msg`) may be
175specified positionally; the remaining arguments should be specified as
176keyword arguments:
177
178 >>> exc_msg = 'IndexError: pop from an empty list'
179 >>> example = doctest.Example('[].pop()', '', exc_msg,
180 ... lineno=5, indent=4,
181 ... options={doctest.ELLIPSIS: True})
182 >>> (example.source, example.want, example.exc_msg,
183 ... example.lineno, example.indent, example.options)
184 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
185
186The constructor normalizes the `source` string to end in a newline:
Tim Peters8485b562004-08-04 18:46:34 +0000187
Tim Petersbb431472004-08-09 03:51:46 +0000188 Source spans a single line: no terminating newline.
Edward Lopera6b68322004-08-26 00:05:43 +0000189 >>> e = doctest.Example('print 1', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000190 >>> e.source, e.want
191 ('print 1\n', '1\n')
192
Edward Lopera6b68322004-08-26 00:05:43 +0000193 >>> e = doctest.Example('print 1\n', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000194 >>> e.source, e.want
195 ('print 1\n', '1\n')
Tim Peters8485b562004-08-04 18:46:34 +0000196
Tim Petersbb431472004-08-09 03:51:46 +0000197 Source spans multiple lines: require terminating newline.
Edward Lopera6b68322004-08-26 00:05:43 +0000198 >>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000199 >>> e.source, e.want
200 ('print 1;\nprint 2\n', '1\n2\n')
Tim Peters8485b562004-08-04 18:46:34 +0000201
Edward Lopera6b68322004-08-26 00:05:43 +0000202 >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000203 >>> e.source, e.want
204 ('print 1;\nprint 2\n', '1\n2\n')
205
Edward Lopera6b68322004-08-26 00:05:43 +0000206 Empty source string (which should never appear in real examples)
207 >>> e = doctest.Example('', '')
208 >>> e.source, e.want
209 ('\n', '')
Tim Peters8485b562004-08-04 18:46:34 +0000210
Edward Lopera6b68322004-08-26 00:05:43 +0000211The constructor normalizes the `want` string to end in a newline,
212unless it's the empty string:
213
214 >>> e = doctest.Example('print 1', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000215 >>> e.source, e.want
216 ('print 1\n', '1\n')
217
Edward Lopera6b68322004-08-26 00:05:43 +0000218 >>> e = doctest.Example('print 1', '1')
Tim Petersbb431472004-08-09 03:51:46 +0000219 >>> e.source, e.want
220 ('print 1\n', '1\n')
221
Edward Lopera6b68322004-08-26 00:05:43 +0000222 >>> e = doctest.Example('print', '')
Tim Petersbb431472004-08-09 03:51:46 +0000223 >>> e.source, e.want
224 ('print\n', '')
Edward Lopera6b68322004-08-26 00:05:43 +0000225
226The constructor normalizes the `exc_msg` string to end in a newline,
227unless it's `None`:
228
229 Message spans one line
230 >>> exc_msg = 'IndexError: pop from an empty list'
231 >>> e = doctest.Example('[].pop()', '', exc_msg)
232 >>> e.exc_msg
233 'IndexError: pop from an empty list\n'
234
235 >>> exc_msg = 'IndexError: pop from an empty list\n'
236 >>> e = doctest.Example('[].pop()', '', exc_msg)
237 >>> e.exc_msg
238 'IndexError: pop from an empty list\n'
239
240 Message spans multiple lines
241 >>> exc_msg = 'ValueError: 1\n 2'
242 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
243 >>> e.exc_msg
244 'ValueError: 1\n 2\n'
245
246 >>> exc_msg = 'ValueError: 1\n 2\n'
247 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
248 >>> e.exc_msg
249 'ValueError: 1\n 2\n'
250
251 Empty (but non-None) exception message (which should never appear
252 in real examples)
253 >>> exc_msg = ''
254 >>> e = doctest.Example('raise X()', '', exc_msg)
255 >>> e.exc_msg
256 '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000257"""
258
259def test_DocTest(): r"""
260Unit tests for the `DocTest` class.
261
262DocTest is a collection of examples, extracted from a docstring, along
263with information about where the docstring comes from (a name,
264filename, and line number). The docstring is parsed by the `DocTest`
265constructor:
266
267 >>> docstring = '''
268 ... >>> print 12
269 ... 12
270 ...
271 ... Non-example text.
272 ...
273 ... >>> print 'another\example'
274 ... another
275 ... example
276 ... '''
277 >>> globs = {} # globals to run the test in.
Edward Lopera1ef6112004-08-09 16:14:41 +0000278 >>> parser = doctest.DocTestParser()
279 >>> test = parser.get_doctest(docstring, globs, 'some_test',
280 ... 'some_file', 20)
Tim Peters8485b562004-08-04 18:46:34 +0000281 >>> print test
282 <DocTest some_test from some_file:20 (2 examples)>
283 >>> len(test.examples)
284 2
285 >>> e1, e2 = test.examples
286 >>> (e1.source, e1.want, e1.lineno)
Tim Petersbb431472004-08-09 03:51:46 +0000287 ('print 12\n', '12\n', 1)
Tim Peters8485b562004-08-04 18:46:34 +0000288 >>> (e2.source, e2.want, e2.lineno)
Tim Petersbb431472004-08-09 03:51:46 +0000289 ("print 'another\\example'\n", 'another\nexample\n', 6)
Tim Peters8485b562004-08-04 18:46:34 +0000290
291Source information (name, filename, and line number) is available as
292attributes on the doctest object:
293
294 >>> (test.name, test.filename, test.lineno)
295 ('some_test', 'some_file', 20)
296
297The line number of an example within its containing file is found by
298adding the line number of the example and the line number of its
299containing test:
300
301 >>> test.lineno + e1.lineno
302 21
303 >>> test.lineno + e2.lineno
304 26
305
306If the docstring contains inconsistant leading whitespace in the
307expected output of an example, then `DocTest` will raise a ValueError:
308
309 >>> docstring = r'''
310 ... >>> print 'bad\nindentation'
311 ... bad
312 ... indentation
313 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000314 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000315 Traceback (most recent call last):
Edward Loper00f8da72004-08-26 18:05:07 +0000316 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
Tim Peters8485b562004-08-04 18:46:34 +0000317
318If the docstring contains inconsistent leading whitespace on
319continuation lines, then `DocTest` will raise a ValueError:
320
321 >>> docstring = r'''
322 ... >>> print ('bad indentation',
323 ... ... 2)
324 ... ('bad', 'indentation')
325 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000326 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000327 Traceback (most recent call last):
Edward Loper00f8da72004-08-26 18:05:07 +0000328 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2)'
Tim Peters8485b562004-08-04 18:46:34 +0000329
330If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
331will raise a ValueError:
332
333 >>> docstring = '>>>print 1\n1'
Edward Lopera1ef6112004-08-09 16:14:41 +0000334 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000335 Traceback (most recent call last):
Edward Loper7c748462004-08-09 02:06:06 +0000336 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1'
337
338If there's no blank space after a PS2 prompt ('...'), then `DocTest`
339will raise a ValueError:
340
341 >>> docstring = '>>> if 1:\n...print 1\n1'
Edward Lopera1ef6112004-08-09 16:14:41 +0000342 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Edward Loper7c748462004-08-09 02:06:06 +0000343 Traceback (most recent call last):
344 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1'
345
Tim Peters8485b562004-08-04 18:46:34 +0000346"""
347
Tim Peters8485b562004-08-04 18:46:34 +0000348def test_DocTestFinder(): r"""
349Unit tests for the `DocTestFinder` class.
350
351DocTestFinder is used to extract DocTests from an object's docstring
352and the docstrings of its contained objects. It can be used with
353modules, functions, classes, methods, staticmethods, classmethods, and
354properties.
355
356Finding Tests in Functions
357~~~~~~~~~~~~~~~~~~~~~~~~~~
358For a function whose docstring contains examples, DocTestFinder.find()
359will return a single test (for that function's docstring):
360
Tim Peters8485b562004-08-04 18:46:34 +0000361 >>> finder = doctest.DocTestFinder()
Jim Fulton07a349c2004-08-22 14:10:00 +0000362
363We'll simulate a __file__ attr that ends in pyc:
364
365 >>> import test.test_doctest
366 >>> old = test.test_doctest.__file__
367 >>> test.test_doctest.__file__ = 'test_doctest.pyc'
368
Tim Peters8485b562004-08-04 18:46:34 +0000369 >>> tests = finder.find(sample_func)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000370
Edward Loper74bca7a2004-08-12 02:27:44 +0000371 >>> print tests # doctest: +ELLIPSIS
Tim Petersa7def722004-08-23 22:13:22 +0000372 [<DocTest sample_func from ...:13 (1 example)>]
Edward Loper8e4a34b2004-08-12 02:34:27 +0000373
Tim Peters4de7c5c2004-08-23 22:38:05 +0000374The exact name depends on how test_doctest was invoked, so allow for
375leading path components.
376
377 >>> tests[0].filename # doctest: +ELLIPSIS
378 '...test_doctest.py'
Jim Fulton07a349c2004-08-22 14:10:00 +0000379
380 >>> test.test_doctest.__file__ = old
Tim Petersc6cbab02004-08-22 19:43:28 +0000381
Jim Fulton07a349c2004-08-22 14:10:00 +0000382
Tim Peters8485b562004-08-04 18:46:34 +0000383 >>> e = tests[0].examples[0]
Tim Petersbb431472004-08-09 03:51:46 +0000384 >>> (e.source, e.want, e.lineno)
385 ('print sample_func(22)\n', '44\n', 3)
Tim Peters8485b562004-08-04 18:46:34 +0000386
Edward Loper32ddbf72004-09-13 05:47:24 +0000387By default, tests are created for objects with no docstring:
Tim Peters8485b562004-08-04 18:46:34 +0000388
389 >>> def no_docstring(v):
390 ... pass
Tim Peters958cc892004-09-13 14:53:28 +0000391 >>> finder.find(no_docstring)
392 []
Edward Loper32ddbf72004-09-13 05:47:24 +0000393
394However, the optional argument `exclude_empty` to the DocTestFinder
395constructor can be used to exclude tests for objects with empty
396docstrings:
397
398 >>> def no_docstring(v):
399 ... pass
400 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
401 >>> excl_empty_finder.find(no_docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000402 []
403
404If the function has a docstring with no examples, then a test with no
405examples is returned. (This lets `DocTestRunner` collect statistics
406about which functions have no tests -- but is that useful? And should
407an empty test also be created when there's no docstring?)
408
409 >>> def no_examples(v):
410 ... ''' no doctest examples '''
Tim Peters17b56372004-09-11 17:33:27 +0000411 >>> finder.find(no_examples) # doctest: +ELLIPSIS
412 [<DocTest no_examples from ...:1 (no examples)>]
Tim Peters8485b562004-08-04 18:46:34 +0000413
414Finding Tests in Classes
415~~~~~~~~~~~~~~~~~~~~~~~~
416For a class, DocTestFinder will create a test for the class's
417docstring, and will recursively explore its contents, including
418methods, classmethods, staticmethods, properties, and nested classes.
419
420 >>> finder = doctest.DocTestFinder()
421 >>> tests = finder.find(SampleClass)
422 >>> tests.sort()
423 >>> for t in tests:
424 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000425 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000426 3 SampleClass.NestedClass
427 1 SampleClass.NestedClass.__init__
428 1 SampleClass.__init__
429 2 SampleClass.a_classmethod
430 1 SampleClass.a_property
431 1 SampleClass.a_staticmethod
432 1 SampleClass.double
433 1 SampleClass.get
434
435New-style classes are also supported:
436
437 >>> tests = finder.find(SampleNewStyleClass)
438 >>> tests.sort()
439 >>> for t in tests:
440 ... print '%2s %s' % (len(t.examples), t.name)
441 1 SampleNewStyleClass
442 1 SampleNewStyleClass.__init__
443 1 SampleNewStyleClass.double
444 1 SampleNewStyleClass.get
445
446Finding Tests in Modules
447~~~~~~~~~~~~~~~~~~~~~~~~
448For a module, DocTestFinder will create a test for the class's
449docstring, and will recursively explore its contents, including
450functions, classes, and the `__test__` dictionary, if it exists:
451
452 >>> # A module
453 >>> import new
454 >>> m = new.module('some_module')
455 >>> def triple(val):
456 ... '''
Edward Loper4ae900f2004-09-21 03:20:34 +0000457 ... >>> print triple(11)
Tim Peters8485b562004-08-04 18:46:34 +0000458 ... 33
459 ... '''
460 ... return val*3
461 >>> m.__dict__.update({
462 ... 'sample_func': sample_func,
463 ... 'SampleClass': SampleClass,
464 ... '__doc__': '''
465 ... Module docstring.
466 ... >>> print 'module'
467 ... module
468 ... ''',
469 ... '__test__': {
470 ... 'd': '>>> print 6\n6\n>>> print 7\n7\n',
471 ... 'c': triple}})
472
473 >>> finder = doctest.DocTestFinder()
474 >>> # Use module=test.test_doctest, to prevent doctest from
475 >>> # ignoring the objects since they weren't defined in m.
476 >>> import test.test_doctest
477 >>> tests = finder.find(m, module=test.test_doctest)
478 >>> tests.sort()
479 >>> for t in tests:
480 ... print '%2s %s' % (len(t.examples), t.name)
481 1 some_module
Edward Loper4ae900f2004-09-21 03:20:34 +0000482 3 some_module.SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000483 3 some_module.SampleClass.NestedClass
484 1 some_module.SampleClass.NestedClass.__init__
485 1 some_module.SampleClass.__init__
486 2 some_module.SampleClass.a_classmethod
487 1 some_module.SampleClass.a_property
488 1 some_module.SampleClass.a_staticmethod
489 1 some_module.SampleClass.double
490 1 some_module.SampleClass.get
Tim Petersc5684782004-09-13 01:07:12 +0000491 1 some_module.__test__.c
492 2 some_module.__test__.d
Tim Peters8485b562004-08-04 18:46:34 +0000493 1 some_module.sample_func
494
495Duplicate Removal
496~~~~~~~~~~~~~~~~~
497If a single object is listed twice (under different names), then tests
498will only be generated for it once:
499
Tim Petersf3f57472004-08-08 06:11:48 +0000500 >>> from test import doctest_aliases
Edward Loper32ddbf72004-09-13 05:47:24 +0000501 >>> tests = excl_empty_finder.find(doctest_aliases)
Tim Peters8485b562004-08-04 18:46:34 +0000502 >>> tests.sort()
503 >>> print len(tests)
504 2
505 >>> print tests[0].name
Tim Petersf3f57472004-08-08 06:11:48 +0000506 test.doctest_aliases.TwoNames
507
508 TwoNames.f and TwoNames.g are bound to the same object.
509 We can't guess which will be found in doctest's traversal of
510 TwoNames.__dict__ first, so we have to allow for either.
511
512 >>> tests[1].name.split('.')[-1] in ['f', 'g']
Tim Peters8485b562004-08-04 18:46:34 +0000513 True
514
515Filter Functions
516~~~~~~~~~~~~~~~~
Tim Petersf727c6c2004-08-08 01:48:59 +0000517A filter function can be used to restrict which objects get examined,
518but this is temporary, undocumented internal support for testmod's
519deprecated isprivate gimmick.
Tim Peters8485b562004-08-04 18:46:34 +0000520
521 >>> def namefilter(prefix, base):
522 ... return base.startswith('a_')
Tim Petersf727c6c2004-08-08 01:48:59 +0000523 >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000524 >>> tests.sort()
525 >>> for t in tests:
526 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000527 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000528 3 SampleClass.NestedClass
529 1 SampleClass.NestedClass.__init__
Tim Peters958cc892004-09-13 14:53:28 +0000530 1 SampleClass.__init__
531 1 SampleClass.double
532 1 SampleClass.get
533
534By default, that excluded objects with no doctests. exclude_empty=False
535tells it to include (empty) tests for objects with no doctests. This feature
536is really to support backward compatibility in what doctest.master.summarize()
537displays.
538
539 >>> tests = doctest.DocTestFinder(_namefilter=namefilter,
540 ... exclude_empty=False).find(SampleClass)
541 >>> tests.sort()
542 >>> for t in tests:
543 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000544 3 SampleClass
Tim Peters958cc892004-09-13 14:53:28 +0000545 3 SampleClass.NestedClass
546 1 SampleClass.NestedClass.__init__
Edward Loper32ddbf72004-09-13 05:47:24 +0000547 0 SampleClass.NestedClass.get
548 0 SampleClass.NestedClass.square
Tim Peters8485b562004-08-04 18:46:34 +0000549 1 SampleClass.__init__
550 1 SampleClass.double
551 1 SampleClass.get
552
Tim Peters8485b562004-08-04 18:46:34 +0000553If a given object is filtered out, then none of the objects that it
554contains will be added either:
555
556 >>> def namefilter(prefix, base):
557 ... return base == 'NestedClass'
Tim Petersf727c6c2004-08-08 01:48:59 +0000558 >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000559 >>> tests.sort()
560 >>> for t in tests:
561 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000562 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000563 1 SampleClass.__init__
564 2 SampleClass.a_classmethod
565 1 SampleClass.a_property
566 1 SampleClass.a_staticmethod
567 1 SampleClass.double
568 1 SampleClass.get
569
Tim Petersf727c6c2004-08-08 01:48:59 +0000570The filter function apply to contained objects, and *not* to the
Tim Peters8485b562004-08-04 18:46:34 +0000571object explicitly passed to DocTestFinder:
572
573 >>> def namefilter(prefix, base):
574 ... return base == 'SampleClass'
Tim Petersf727c6c2004-08-08 01:48:59 +0000575 >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000576 >>> len(tests)
Tim Peters958cc892004-09-13 14:53:28 +0000577 9
Tim Peters8485b562004-08-04 18:46:34 +0000578
579Turning off Recursion
580~~~~~~~~~~~~~~~~~~~~~
581DocTestFinder can be told not to look for tests in contained objects
582using the `recurse` flag:
583
584 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
585 >>> tests.sort()
586 >>> for t in tests:
587 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000588 3 SampleClass
Edward Loperb51b2342004-08-17 16:37:12 +0000589
590Line numbers
591~~~~~~~~~~~~
592DocTestFinder finds the line number of each example:
593
594 >>> def f(x):
595 ... '''
596 ... >>> x = 12
597 ...
598 ... some text
599 ...
600 ... >>> # examples are not created for comments & bare prompts.
601 ... >>>
602 ... ...
603 ...
604 ... >>> for x in range(10):
605 ... ... print x,
606 ... 0 1 2 3 4 5 6 7 8 9
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000607 ... >>> x//2
608 ... 6
Edward Loperb51b2342004-08-17 16:37:12 +0000609 ... '''
610 >>> test = doctest.DocTestFinder().find(f)[0]
611 >>> [e.lineno for e in test.examples]
612 [1, 9, 12]
Tim Peters8485b562004-08-04 18:46:34 +0000613"""
614
Edward Loper00f8da72004-08-26 18:05:07 +0000615def test_DocTestParser(): r"""
616Unit tests for the `DocTestParser` class.
617
618DocTestParser is used to parse docstrings containing doctest examples.
619
620The `parse` method divides a docstring into examples and intervening
621text:
622
623 >>> s = '''
624 ... >>> x, y = 2, 3 # no output expected
625 ... >>> if 1:
626 ... ... print x
627 ... ... print y
628 ... 2
629 ... 3
630 ...
631 ... Some text.
632 ... >>> x+y
633 ... 5
634 ... '''
635 >>> parser = doctest.DocTestParser()
636 >>> for piece in parser.parse(s):
637 ... if isinstance(piece, doctest.Example):
638 ... print 'Example:', (piece.source, piece.want, piece.lineno)
639 ... else:
640 ... print ' Text:', `piece`
641 Text: '\n'
642 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
643 Text: ''
644 Example: ('if 1:\n print x\n print y\n', '2\n3\n', 2)
645 Text: '\nSome text.\n'
646 Example: ('x+y\n', '5\n', 9)
647 Text: ''
648
649The `get_examples` method returns just the examples:
650
651 >>> for piece in parser.get_examples(s):
652 ... print (piece.source, piece.want, piece.lineno)
653 ('x, y = 2, 3 # no output expected\n', '', 1)
654 ('if 1:\n print x\n print y\n', '2\n3\n', 2)
655 ('x+y\n', '5\n', 9)
656
657The `get_doctest` method creates a Test from the examples, along with the
658given arguments:
659
660 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
661 >>> (test.name, test.filename, test.lineno)
662 ('name', 'filename', 5)
663 >>> for piece in test.examples:
664 ... print (piece.source, piece.want, piece.lineno)
665 ('x, y = 2, 3 # no output expected\n', '', 1)
666 ('if 1:\n print x\n print y\n', '2\n3\n', 2)
667 ('x+y\n', '5\n', 9)
668"""
669
Tim Peters8485b562004-08-04 18:46:34 +0000670class test_DocTestRunner:
671 def basics(): r"""
672Unit tests for the `DocTestRunner` class.
673
674DocTestRunner is used to run DocTest test cases, and to accumulate
675statistics. Here's a simple DocTest case we can use:
676
677 >>> def f(x):
678 ... '''
679 ... >>> x = 12
680 ... >>> print x
681 ... 12
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000682 ... >>> x//2
683 ... 6
Tim Peters8485b562004-08-04 18:46:34 +0000684 ... '''
685 >>> test = doctest.DocTestFinder().find(f)[0]
686
687The main DocTestRunner interface is the `run` method, which runs a
688given DocTest case in a given namespace (globs). It returns a tuple
689`(f,t)`, where `f` is the number of failed tests and `t` is the number
690of tried tests.
691
692 >>> doctest.DocTestRunner(verbose=False).run(test)
693 (0, 3)
694
695If any example produces incorrect output, then the test runner reports
696the failure and proceeds to the next example:
697
698 >>> def f(x):
699 ... '''
700 ... >>> x = 12
701 ... >>> print x
702 ... 14
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000703 ... >>> x//2
704 ... 6
Tim Peters8485b562004-08-04 18:46:34 +0000705 ... '''
706 >>> test = doctest.DocTestFinder().find(f)[0]
707 >>> doctest.DocTestRunner(verbose=True).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000708 ... # doctest: +ELLIPSIS
Edward Loperaacf0832004-08-26 01:19:50 +0000709 Trying:
710 x = 12
711 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000712 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000713 Trying:
714 print x
715 Expecting:
716 14
Tim Peters8485b562004-08-04 18:46:34 +0000717 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000718 File ..., line 4, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000719 Failed example:
720 print x
721 Expected:
722 14
723 Got:
724 12
Edward Loperaacf0832004-08-26 01:19:50 +0000725 Trying:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000726 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000727 Expecting:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000728 6
Tim Peters8485b562004-08-04 18:46:34 +0000729 ok
730 (1, 3)
731"""
732 def verbose_flag(): r"""
733The `verbose` flag makes the test runner generate more detailed
734output:
735
736 >>> def f(x):
737 ... '''
738 ... >>> x = 12
739 ... >>> print x
740 ... 12
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000741 ... >>> x//2
742 ... 6
Tim Peters8485b562004-08-04 18:46:34 +0000743 ... '''
744 >>> test = doctest.DocTestFinder().find(f)[0]
745
746 >>> doctest.DocTestRunner(verbose=True).run(test)
Edward Loperaacf0832004-08-26 01:19:50 +0000747 Trying:
748 x = 12
749 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000750 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000751 Trying:
752 print x
753 Expecting:
754 12
Tim Peters8485b562004-08-04 18:46:34 +0000755 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000756 Trying:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000757 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000758 Expecting:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000759 6
Tim Peters8485b562004-08-04 18:46:34 +0000760 ok
761 (0, 3)
762
763If the `verbose` flag is unspecified, then the output will be verbose
764iff `-v` appears in sys.argv:
765
766 >>> # Save the real sys.argv list.
767 >>> old_argv = sys.argv
768
769 >>> # If -v does not appear in sys.argv, then output isn't verbose.
770 >>> sys.argv = ['test']
771 >>> doctest.DocTestRunner().run(test)
772 (0, 3)
773
774 >>> # If -v does appear in sys.argv, then output is verbose.
775 >>> sys.argv = ['test', '-v']
776 >>> doctest.DocTestRunner().run(test)
Edward Loperaacf0832004-08-26 01:19:50 +0000777 Trying:
778 x = 12
779 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000780 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000781 Trying:
782 print x
783 Expecting:
784 12
Tim Peters8485b562004-08-04 18:46:34 +0000785 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000786 Trying:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000787 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000788 Expecting:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000789 6
Tim Peters8485b562004-08-04 18:46:34 +0000790 ok
791 (0, 3)
792
793 >>> # Restore sys.argv
794 >>> sys.argv = old_argv
795
796In the remaining examples, the test runner's verbosity will be
797explicitly set, to ensure that the test behavior is consistent.
798 """
799 def exceptions(): r"""
800Tests of `DocTestRunner`'s exception handling.
801
802An expected exception is specified with a traceback message. The
803lines between the first line and the type/value may be omitted or
804replaced with any other string:
805
806 >>> def f(x):
807 ... '''
808 ... >>> x = 12
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000809 ... >>> print x//0
Tim Peters8485b562004-08-04 18:46:34 +0000810 ... Traceback (most recent call last):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000811 ... ZeroDivisionError: integer division or modulo by zero
Tim Peters8485b562004-08-04 18:46:34 +0000812 ... '''
813 >>> test = doctest.DocTestFinder().find(f)[0]
814 >>> doctest.DocTestRunner(verbose=False).run(test)
815 (0, 2)
816
Edward Loper19b19582004-08-25 23:07:03 +0000817An example may not generate output before it raises an exception; if
818it does, then the traceback message will not be recognized as
819signaling an expected exception, so the example will be reported as an
820unexpected exception:
Tim Peters8485b562004-08-04 18:46:34 +0000821
822 >>> def f(x):
823 ... '''
824 ... >>> x = 12
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000825 ... >>> print 'pre-exception output', x//0
Tim Peters8485b562004-08-04 18:46:34 +0000826 ... pre-exception output
827 ... Traceback (most recent call last):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000828 ... ZeroDivisionError: integer division or modulo by zero
Tim Peters8485b562004-08-04 18:46:34 +0000829 ... '''
830 >>> test = doctest.DocTestFinder().find(f)[0]
831 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper19b19582004-08-25 23:07:03 +0000832 ... # doctest: +ELLIPSIS
833 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000834 File ..., line 4, in f
Edward Loper19b19582004-08-25 23:07:03 +0000835 Failed example:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000836 print 'pre-exception output', x//0
Edward Loper19b19582004-08-25 23:07:03 +0000837 Exception raised:
838 ...
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000839 ZeroDivisionError: integer division or modulo by zero
Edward Loper19b19582004-08-25 23:07:03 +0000840 (1, 2)
Tim Peters8485b562004-08-04 18:46:34 +0000841
842Exception messages may contain newlines:
843
844 >>> def f(x):
845 ... r'''
846 ... >>> raise ValueError, 'multi\nline\nmessage'
847 ... Traceback (most recent call last):
848 ... ValueError: multi
849 ... line
850 ... message
851 ... '''
852 >>> test = doctest.DocTestFinder().find(f)[0]
853 >>> doctest.DocTestRunner(verbose=False).run(test)
854 (0, 1)
855
856If an exception is expected, but an exception with the wrong type or
857message is raised, then it is reported as a failure:
858
859 >>> def f(x):
860 ... r'''
861 ... >>> raise ValueError, 'message'
862 ... Traceback (most recent call last):
863 ... ValueError: wrong message
864 ... '''
865 >>> test = doctest.DocTestFinder().find(f)[0]
866 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000867 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000868 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000869 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000870 Failed example:
871 raise ValueError, 'message'
Tim Peters8485b562004-08-04 18:46:34 +0000872 Expected:
873 Traceback (most recent call last):
874 ValueError: wrong message
875 Got:
876 Traceback (most recent call last):
Edward Loper8e4a34b2004-08-12 02:34:27 +0000877 ...
Tim Peters8485b562004-08-04 18:46:34 +0000878 ValueError: message
879 (1, 1)
880
Tim Peters1fbf9c52004-09-04 17:21:02 +0000881However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
882detail:
883
884 >>> def f(x):
885 ... r'''
886 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
887 ... Traceback (most recent call last):
888 ... ValueError: wrong message
889 ... '''
890 >>> test = doctest.DocTestFinder().find(f)[0]
891 >>> doctest.DocTestRunner(verbose=False).run(test)
892 (0, 1)
893
894But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
895
896 >>> def f(x):
897 ... r'''
898 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
899 ... Traceback (most recent call last):
900 ... TypeError: wrong type
901 ... '''
902 >>> test = doctest.DocTestFinder().find(f)[0]
903 >>> doctest.DocTestRunner(verbose=False).run(test)
904 ... # doctest: +ELLIPSIS
905 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000906 File ..., line 3, in f
Tim Peters1fbf9c52004-09-04 17:21:02 +0000907 Failed example:
908 raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
909 Expected:
910 Traceback (most recent call last):
911 TypeError: wrong type
912 Got:
913 Traceback (most recent call last):
914 ...
915 ValueError: message
916 (1, 1)
917
Tim Peters8485b562004-08-04 18:46:34 +0000918If an exception is raised but not expected, then it is reported as an
919unexpected exception:
920
Tim Peters8485b562004-08-04 18:46:34 +0000921 >>> def f(x):
922 ... r'''
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000923 ... >>> 1//0
Tim Peters8485b562004-08-04 18:46:34 +0000924 ... 0
925 ... '''
926 >>> test = doctest.DocTestFinder().find(f)[0]
927 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper74bca7a2004-08-12 02:27:44 +0000928 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000929 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000930 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000931 Failed example:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000932 1//0
Tim Peters8485b562004-08-04 18:46:34 +0000933 Exception raised:
934 Traceback (most recent call last):
Jim Fulton07a349c2004-08-22 14:10:00 +0000935 ...
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000936 ZeroDivisionError: integer division or modulo by zero
Tim Peters8485b562004-08-04 18:46:34 +0000937 (1, 1)
Tim Peters8485b562004-08-04 18:46:34 +0000938"""
939 def optionflags(): r"""
940Tests of `DocTestRunner`'s option flag handling.
941
942Several option flags can be used to customize the behavior of the test
943runner. These are defined as module constants in doctest, and passed
944to the DocTestRunner constructor (multiple constants should be or-ed
945together).
946
947The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
948and 1/0:
949
950 >>> def f(x):
951 ... '>>> True\n1\n'
952
953 >>> # Without the flag:
954 >>> test = doctest.DocTestFinder().find(f)[0]
955 >>> doctest.DocTestRunner(verbose=False).run(test)
956 (0, 1)
957
958 >>> # With the flag:
959 >>> test = doctest.DocTestFinder().find(f)[0]
960 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
961 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000962 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000963 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000964 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000965 Failed example:
966 True
967 Expected:
968 1
969 Got:
970 True
Tim Peters8485b562004-08-04 18:46:34 +0000971 (1, 1)
972
973The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
974and the '<BLANKLINE>' marker:
975
976 >>> def f(x):
977 ... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n'
978
979 >>> # Without the flag:
980 >>> test = doctest.DocTestFinder().find(f)[0]
981 >>> doctest.DocTestRunner(verbose=False).run(test)
982 (0, 1)
983
984 >>> # With the flag:
985 >>> test = doctest.DocTestFinder().find(f)[0]
986 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
987 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000988 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000989 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000990 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000991 Failed example:
992 print "a\n\nb"
Tim Peters8485b562004-08-04 18:46:34 +0000993 Expected:
994 a
995 <BLANKLINE>
996 b
997 Got:
998 a
999 <BLANKLINE>
1000 b
1001 (1, 1)
1002
1003The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1004treated as equal:
1005
1006 >>> def f(x):
1007 ... '>>> print 1, 2, 3\n 1 2\n 3'
1008
1009 >>> # Without the flag:
1010 >>> test = doctest.DocTestFinder().find(f)[0]
1011 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001012 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001013 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001014 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001015 Failed example:
1016 print 1, 2, 3
Tim Peters8485b562004-08-04 18:46:34 +00001017 Expected:
1018 1 2
1019 3
Jim Fulton07a349c2004-08-22 14:10:00 +00001020 Got:
1021 1 2 3
Tim Peters8485b562004-08-04 18:46:34 +00001022 (1, 1)
1023
1024 >>> # With the flag:
1025 >>> test = doctest.DocTestFinder().find(f)[0]
1026 >>> flags = doctest.NORMALIZE_WHITESPACE
1027 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1028 (0, 1)
1029
Tim Peters026f8dc2004-08-19 16:38:58 +00001030 An example from the docs:
1031 >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
1032 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1033 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1034
Tim Peters8485b562004-08-04 18:46:34 +00001035The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1036output to match any substring in the actual output:
1037
1038 >>> def f(x):
1039 ... '>>> print range(15)\n[0, 1, 2, ..., 14]\n'
1040
1041 >>> # Without the flag:
1042 >>> test = doctest.DocTestFinder().find(f)[0]
1043 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001044 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001045 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001046 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001047 Failed example:
1048 print range(15)
1049 Expected:
1050 [0, 1, 2, ..., 14]
1051 Got:
1052 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
Tim Peters8485b562004-08-04 18:46:34 +00001053 (1, 1)
1054
1055 >>> # With the flag:
1056 >>> test = doctest.DocTestFinder().find(f)[0]
1057 >>> flags = doctest.ELLIPSIS
1058 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1059 (0, 1)
1060
Tim Peterse594bee2004-08-22 01:47:51 +00001061 ... also matches nothing:
Tim Peters1cf3aa62004-08-19 06:49:33 +00001062
1063 >>> for i in range(100):
Tim Peterse594bee2004-08-22 01:47:51 +00001064 ... print i**2, #doctest: +ELLIPSIS
1065 0 1...4...9 16 ... 36 49 64 ... 9801
Tim Peters1cf3aa62004-08-19 06:49:33 +00001066
Tim Peters026f8dc2004-08-19 16:38:58 +00001067 ... can be surprising; e.g., this test passes:
Tim Peters26b3ebb2004-08-19 08:10:08 +00001068
1069 >>> for i in range(21): #doctest: +ELLIPSIS
Tim Peterse594bee2004-08-22 01:47:51 +00001070 ... print i,
1071 0 1 2 ...1...2...0
Tim Peters26b3ebb2004-08-19 08:10:08 +00001072
Tim Peters026f8dc2004-08-19 16:38:58 +00001073 Examples from the docs:
1074
1075 >>> print range(20) # doctest:+ELLIPSIS
1076 [0, 1, ..., 18, 19]
1077
1078 >>> print range(20) # doctest: +ELLIPSIS
1079 ... # doctest: +NORMALIZE_WHITESPACE
1080 [0, 1, ..., 18, 19]
1081
Thomas Wouters477c8d52006-05-27 19:21:47 +00001082The SKIP flag causes an example to be skipped entirely. I.e., the
1083example is not run. It can be useful in contexts where doctest
1084examples serve as both documentation and test cases, and an example
1085should be included for documentation purposes, but should not be
1086checked (e.g., because its output is random, or depends on resources
1087which would be unavailable.) The SKIP flag can also be used for
1088'commenting out' broken examples.
1089
1090 >>> import unavailable_resource # doctest: +SKIP
1091 >>> unavailable_resource.do_something() # doctest: +SKIP
1092 >>> unavailable_resource.blow_up() # doctest: +SKIP
1093 Traceback (most recent call last):
1094 ...
1095 UncheckedBlowUpError: Nobody checks me.
1096
1097 >>> import random
1098 >>> print random.random() # doctest: +SKIP
1099 0.721216923889
1100
Edward Loper71f55af2004-08-26 01:41:51 +00001101The REPORT_UDIFF flag causes failures that involve multi-line expected
Tim Peters8485b562004-08-04 18:46:34 +00001102and actual outputs to be displayed using a unified diff:
1103
1104 >>> def f(x):
1105 ... r'''
1106 ... >>> print '\n'.join('abcdefg')
1107 ... a
1108 ... B
1109 ... c
1110 ... d
1111 ... f
1112 ... g
1113 ... h
1114 ... '''
1115
1116 >>> # Without the flag:
1117 >>> test = doctest.DocTestFinder().find(f)[0]
1118 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001119 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001120 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001121 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001122 Failed example:
1123 print '\n'.join('abcdefg')
Tim Peters8485b562004-08-04 18:46:34 +00001124 Expected:
1125 a
1126 B
1127 c
1128 d
1129 f
1130 g
1131 h
1132 Got:
1133 a
1134 b
1135 c
1136 d
1137 e
1138 f
1139 g
1140 (1, 1)
1141
1142 >>> # With the flag:
1143 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001144 >>> flags = doctest.REPORT_UDIFF
Tim Peters8485b562004-08-04 18:46:34 +00001145 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001146 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001147 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001148 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001149 Failed example:
1150 print '\n'.join('abcdefg')
Edward Loper56629292004-08-26 01:31:56 +00001151 Differences (unified diff with -expected +actual):
Tim Peterse7edcb82004-08-26 05:44:27 +00001152 @@ -1,7 +1,7 @@
Tim Peters8485b562004-08-04 18:46:34 +00001153 a
1154 -B
1155 +b
1156 c
1157 d
1158 +e
1159 f
1160 g
1161 -h
Tim Peters8485b562004-08-04 18:46:34 +00001162 (1, 1)
1163
Edward Loper71f55af2004-08-26 01:41:51 +00001164The REPORT_CDIFF flag causes failures that involve multi-line expected
Tim Peters8485b562004-08-04 18:46:34 +00001165and actual outputs to be displayed using a context diff:
1166
Edward Loper71f55af2004-08-26 01:41:51 +00001167 >>> # Reuse f() from the REPORT_UDIFF example, above.
Tim Peters8485b562004-08-04 18:46:34 +00001168 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001169 >>> flags = doctest.REPORT_CDIFF
Tim Peters8485b562004-08-04 18:46:34 +00001170 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001171 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001172 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001173 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001174 Failed example:
1175 print '\n'.join('abcdefg')
Edward Loper56629292004-08-26 01:31:56 +00001176 Differences (context diff with expected followed by actual):
Tim Peters8485b562004-08-04 18:46:34 +00001177 ***************
Tim Peterse7edcb82004-08-26 05:44:27 +00001178 *** 1,7 ****
Tim Peters8485b562004-08-04 18:46:34 +00001179 a
1180 ! B
1181 c
1182 d
1183 f
1184 g
1185 - h
Tim Peterse7edcb82004-08-26 05:44:27 +00001186 --- 1,7 ----
Tim Peters8485b562004-08-04 18:46:34 +00001187 a
1188 ! b
1189 c
1190 d
1191 + e
1192 f
1193 g
Tim Peters8485b562004-08-04 18:46:34 +00001194 (1, 1)
Tim Petersc6cbab02004-08-22 19:43:28 +00001195
1196
Edward Loper71f55af2004-08-26 01:41:51 +00001197The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
Tim Petersc6cbab02004-08-22 19:43:28 +00001198used by the popular ndiff.py utility. This does intraline difference
1199marking, as well as interline differences.
1200
1201 >>> def f(x):
1202 ... r'''
1203 ... >>> print "a b c d e f g h i j k l m"
1204 ... a b c d e f g h i j k 1 m
1205 ... '''
1206 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001207 >>> flags = doctest.REPORT_NDIFF
Tim Petersc6cbab02004-08-22 19:43:28 +00001208 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001209 ... # doctest: +ELLIPSIS
Tim Petersc6cbab02004-08-22 19:43:28 +00001210 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001211 File ..., line 3, in f
Tim Petersc6cbab02004-08-22 19:43:28 +00001212 Failed example:
1213 print "a b c d e f g h i j k l m"
1214 Differences (ndiff with -expected +actual):
1215 - a b c d e f g h i j k 1 m
1216 ? ^
1217 + a b c d e f g h i j k l m
1218 ? + ++ ^
Tim Petersc6cbab02004-08-22 19:43:28 +00001219 (1, 1)
Edward Lopera89f88d2004-08-26 02:45:51 +00001220
1221The REPORT_ONLY_FIRST_FAILURE supresses result output after the first
1222failing example:
1223
1224 >>> def f(x):
1225 ... r'''
1226 ... >>> print 1 # first success
1227 ... 1
1228 ... >>> print 2 # first failure
1229 ... 200
1230 ... >>> print 3 # second failure
1231 ... 300
1232 ... >>> print 4 # second success
1233 ... 4
1234 ... >>> print 5 # third failure
1235 ... 500
1236 ... '''
1237 >>> test = doctest.DocTestFinder().find(f)[0]
1238 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1239 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001240 ... # doctest: +ELLIPSIS
Edward Lopera89f88d2004-08-26 02:45:51 +00001241 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001242 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001243 Failed example:
1244 print 2 # first failure
1245 Expected:
1246 200
1247 Got:
1248 2
1249 (3, 5)
1250
1251However, output from `report_start` is not supressed:
1252
1253 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001254 ... # doctest: +ELLIPSIS
Edward Lopera89f88d2004-08-26 02:45:51 +00001255 Trying:
1256 print 1 # first success
1257 Expecting:
1258 1
1259 ok
1260 Trying:
1261 print 2 # first failure
1262 Expecting:
1263 200
1264 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001265 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001266 Failed example:
1267 print 2 # first failure
1268 Expected:
1269 200
1270 Got:
1271 2
1272 (3, 5)
1273
1274For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
1275count as failures:
1276
1277 >>> def f(x):
1278 ... r'''
1279 ... >>> print 1 # first success
1280 ... 1
1281 ... >>> raise ValueError(2) # first failure
1282 ... 200
1283 ... >>> print 3 # second failure
1284 ... 300
1285 ... >>> print 4 # second success
1286 ... 4
1287 ... >>> print 5 # third failure
1288 ... 500
1289 ... '''
1290 >>> test = doctest.DocTestFinder().find(f)[0]
1291 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1292 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1293 ... # doctest: +ELLIPSIS
1294 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001295 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001296 Failed example:
1297 raise ValueError(2) # first failure
1298 Exception raised:
1299 ...
1300 ValueError: 2
1301 (3, 5)
1302
Thomas Wouters477c8d52006-05-27 19:21:47 +00001303New option flags can also be registered, via register_optionflag(). Here
1304we reach into doctest's internals a bit.
1305
1306 >>> unlikely = "UNLIKELY_OPTION_NAME"
1307 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1308 False
1309 >>> new_flag_value = doctest.register_optionflag(unlikely)
1310 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1311 True
1312
1313Before 2.4.4/2.5, registering a name more than once erroneously created
1314more than one flag value. Here we verify that's fixed:
1315
1316 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1317 >>> redundant_flag_value == new_flag_value
1318 True
1319
1320Clean up.
1321 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1322
Tim Petersc6cbab02004-08-22 19:43:28 +00001323 """
1324
Tim Peters8485b562004-08-04 18:46:34 +00001325 def option_directives(): r"""
1326Tests of `DocTestRunner`'s option directive mechanism.
1327
Edward Loper74bca7a2004-08-12 02:27:44 +00001328Option directives can be used to turn option flags on or off for a
1329single example. To turn an option on for an example, follow that
1330example with a comment of the form ``# doctest: +OPTION``:
Tim Peters8485b562004-08-04 18:46:34 +00001331
1332 >>> def f(x): r'''
Edward Loper74bca7a2004-08-12 02:27:44 +00001333 ... >>> print range(10) # should fail: no ellipsis
1334 ... [0, 1, ..., 9]
1335 ...
1336 ... >>> print range(10) # doctest: +ELLIPSIS
1337 ... [0, 1, ..., 9]
1338 ... '''
1339 >>> test = doctest.DocTestFinder().find(f)[0]
1340 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001341 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001342 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001343 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001344 Failed example:
1345 print range(10) # should fail: no ellipsis
1346 Expected:
1347 [0, 1, ..., 9]
1348 Got:
1349 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Edward Loper74bca7a2004-08-12 02:27:44 +00001350 (1, 2)
1351
1352To turn an option off for an example, follow that example with a
1353comment of the form ``# doctest: -OPTION``:
1354
1355 >>> def f(x): r'''
1356 ... >>> print range(10)
1357 ... [0, 1, ..., 9]
1358 ...
1359 ... >>> # should fail: no ellipsis
1360 ... >>> print range(10) # doctest: -ELLIPSIS
1361 ... [0, 1, ..., 9]
1362 ... '''
1363 >>> test = doctest.DocTestFinder().find(f)[0]
1364 >>> doctest.DocTestRunner(verbose=False,
1365 ... optionflags=doctest.ELLIPSIS).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001366 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001367 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001368 File ..., line 6, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001369 Failed example:
1370 print range(10) # doctest: -ELLIPSIS
1371 Expected:
1372 [0, 1, ..., 9]
1373 Got:
1374 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Edward Loper74bca7a2004-08-12 02:27:44 +00001375 (1, 2)
1376
1377Option directives affect only the example that they appear with; they
1378do not change the options for surrounding examples:
Edward Loper8e4a34b2004-08-12 02:34:27 +00001379
Edward Loper74bca7a2004-08-12 02:27:44 +00001380 >>> def f(x): r'''
Tim Peters8485b562004-08-04 18:46:34 +00001381 ... >>> print range(10) # Should fail: no ellipsis
1382 ... [0, 1, ..., 9]
1383 ...
Edward Loper74bca7a2004-08-12 02:27:44 +00001384 ... >>> print range(10) # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001385 ... [0, 1, ..., 9]
1386 ...
Tim Peters8485b562004-08-04 18:46:34 +00001387 ... >>> print range(10) # Should fail: no ellipsis
1388 ... [0, 1, ..., 9]
1389 ... '''
1390 >>> test = doctest.DocTestFinder().find(f)[0]
1391 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001392 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001393 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001394 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001395 Failed example:
1396 print range(10) # Should fail: no ellipsis
1397 Expected:
1398 [0, 1, ..., 9]
1399 Got:
1400 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Tim Peters8485b562004-08-04 18:46:34 +00001401 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001402 File ..., line 8, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001403 Failed example:
1404 print range(10) # Should fail: no ellipsis
1405 Expected:
1406 [0, 1, ..., 9]
1407 Got:
1408 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Tim Peters8485b562004-08-04 18:46:34 +00001409 (2, 3)
1410
Edward Loper74bca7a2004-08-12 02:27:44 +00001411Multiple options may be modified by a single option directive. They
1412may be separated by whitespace, commas, or both:
Tim Peters8485b562004-08-04 18:46:34 +00001413
1414 >>> def f(x): r'''
1415 ... >>> print range(10) # Should fail
1416 ... [0, 1, ..., 9]
Tim Peters8485b562004-08-04 18:46:34 +00001417 ... >>> print range(10) # Should succeed
Edward Loper74bca7a2004-08-12 02:27:44 +00001418 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001419 ... [0, 1, ..., 9]
1420 ... '''
1421 >>> test = doctest.DocTestFinder().find(f)[0]
1422 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001423 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001424 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001425 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001426 Failed example:
1427 print range(10) # Should fail
1428 Expected:
1429 [0, 1, ..., 9]
1430 Got:
1431 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Tim Peters8485b562004-08-04 18:46:34 +00001432 (1, 2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001433
1434 >>> def f(x): r'''
1435 ... >>> print range(10) # Should fail
1436 ... [0, 1, ..., 9]
1437 ... >>> print range(10) # Should succeed
1438 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1439 ... [0, 1, ..., 9]
1440 ... '''
1441 >>> test = doctest.DocTestFinder().find(f)[0]
1442 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001443 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001444 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001445 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001446 Failed example:
1447 print range(10) # Should fail
1448 Expected:
1449 [0, 1, ..., 9]
1450 Got:
1451 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Edward Loper74bca7a2004-08-12 02:27:44 +00001452 (1, 2)
1453
1454 >>> def f(x): r'''
1455 ... >>> print range(10) # Should fail
1456 ... [0, 1, ..., 9]
1457 ... >>> print range(10) # Should succeed
1458 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1459 ... [0, 1, ..., 9]
1460 ... '''
1461 >>> test = doctest.DocTestFinder().find(f)[0]
1462 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001463 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001464 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001465 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001466 Failed example:
1467 print range(10) # Should fail
1468 Expected:
1469 [0, 1, ..., 9]
1470 Got:
1471 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Edward Loper74bca7a2004-08-12 02:27:44 +00001472 (1, 2)
1473
1474The option directive may be put on the line following the source, as
1475long as a continuation prompt is used:
1476
1477 >>> def f(x): r'''
1478 ... >>> print range(10)
1479 ... ... # doctest: +ELLIPSIS
1480 ... [0, 1, ..., 9]
1481 ... '''
1482 >>> test = doctest.DocTestFinder().find(f)[0]
1483 >>> doctest.DocTestRunner(verbose=False).run(test)
1484 (0, 1)
Edward Loper8e4a34b2004-08-12 02:34:27 +00001485
Edward Loper74bca7a2004-08-12 02:27:44 +00001486For examples with multi-line source, the option directive may appear
1487at the end of any line:
1488
1489 >>> def f(x): r'''
1490 ... >>> for x in range(10): # doctest: +ELLIPSIS
1491 ... ... print x,
1492 ... 0 1 2 ... 9
1493 ...
1494 ... >>> for x in range(10):
1495 ... ... print x, # doctest: +ELLIPSIS
1496 ... 0 1 2 ... 9
1497 ... '''
1498 >>> test = doctest.DocTestFinder().find(f)[0]
1499 >>> doctest.DocTestRunner(verbose=False).run(test)
1500 (0, 2)
1501
1502If more than one line of an example with multi-line source has an
1503option directive, then they are combined:
1504
1505 >>> def f(x): r'''
1506 ... Should fail (option directive not on the last line):
1507 ... >>> for x in range(10): # doctest: +ELLIPSIS
1508 ... ... print x, # doctest: +NORMALIZE_WHITESPACE
1509 ... 0 1 2...9
1510 ... '''
1511 >>> test = doctest.DocTestFinder().find(f)[0]
1512 >>> doctest.DocTestRunner(verbose=False).run(test)
1513 (0, 1)
1514
1515It is an error to have a comment of the form ``# doctest:`` that is
1516*not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1517``OPTION`` is an option that has been registered with
1518`register_option`:
1519
1520 >>> # Error: Option not registered
1521 >>> s = '>>> print 12 #doctest: +BADOPTION'
1522 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1523 Traceback (most recent call last):
1524 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1525
1526 >>> # Error: No + or - prefix
1527 >>> s = '>>> print 12 #doctest: ELLIPSIS'
1528 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1529 Traceback (most recent call last):
1530 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1531
1532It is an error to use an option directive on a line that contains no
1533source:
1534
1535 >>> s = '>>> # doctest: +ELLIPSIS'
1536 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1537 Traceback (most recent call last):
1538 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
Tim Peters8485b562004-08-04 18:46:34 +00001539"""
1540
1541def test_testsource(): r"""
1542Unit tests for `testsource()`.
1543
1544The testsource() function takes a module and a name, finds the (first)
Tim Peters19397e52004-08-06 22:02:59 +00001545test with that name in that module, and converts it to a script. The
1546example code is converted to regular Python code. The surrounding
1547words and expected output are converted to comments:
Tim Peters8485b562004-08-04 18:46:34 +00001548
1549 >>> import test.test_doctest
1550 >>> name = 'test.test_doctest.sample_func'
1551 >>> print doctest.testsource(test.test_doctest, name)
Edward Lopera5db6002004-08-12 02:41:30 +00001552 # Blah blah
Tim Peters19397e52004-08-06 22:02:59 +00001553 #
Tim Peters8485b562004-08-04 18:46:34 +00001554 print sample_func(22)
1555 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001556 ## 44
Tim Peters19397e52004-08-06 22:02:59 +00001557 #
Edward Lopera5db6002004-08-12 02:41:30 +00001558 # Yee ha!
Georg Brandlecf93c72005-06-26 23:09:51 +00001559 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001560
1561 >>> name = 'test.test_doctest.SampleNewStyleClass'
1562 >>> print doctest.testsource(test.test_doctest, name)
1563 print '1\n2\n3'
1564 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001565 ## 1
1566 ## 2
1567 ## 3
Georg Brandlecf93c72005-06-26 23:09:51 +00001568 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001569
1570 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1571 >>> print doctest.testsource(test.test_doctest, name)
1572 print SampleClass.a_classmethod(10)
1573 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001574 ## 12
Tim Peters8485b562004-08-04 18:46:34 +00001575 print SampleClass(0).a_classmethod(10)
1576 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001577 ## 12
Georg Brandlecf93c72005-06-26 23:09:51 +00001578 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001579"""
1580
1581def test_debug(): r"""
1582
1583Create a docstring that we want to debug:
1584
1585 >>> s = '''
1586 ... >>> x = 12
1587 ... >>> print x
1588 ... 12
1589 ... '''
1590
1591Create some fake stdin input, to feed to the debugger:
1592
1593 >>> import tempfile
Tim Peters8485b562004-08-04 18:46:34 +00001594 >>> real_stdin = sys.stdin
Edward Loper2de91ba2004-08-27 02:07:46 +00001595 >>> sys.stdin = _FakeInput(['next', 'print x', 'continue'])
Tim Peters8485b562004-08-04 18:46:34 +00001596
1597Run the debugger on the docstring, and then restore sys.stdin.
1598
Edward Loper2de91ba2004-08-27 02:07:46 +00001599 >>> try: doctest.debug_src(s)
1600 ... finally: sys.stdin = real_stdin
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001601 > <string>(1)<module>()
Edward Loper2de91ba2004-08-27 02:07:46 +00001602 (Pdb) next
1603 12
Tim Peters8485b562004-08-04 18:46:34 +00001604 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001605 > <string>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001606 (Pdb) print x
1607 12
1608 (Pdb) continue
Tim Peters8485b562004-08-04 18:46:34 +00001609
1610"""
1611
Jim Fulton356fd192004-08-09 11:34:47 +00001612def test_pdb_set_trace():
Tim Peters50c6bdb2004-11-08 22:07:37 +00001613 """Using pdb.set_trace from a doctest.
Jim Fulton356fd192004-08-09 11:34:47 +00001614
Tim Peters413ced62004-08-09 15:43:47 +00001615 You can use pdb.set_trace from a doctest. To do so, you must
Jim Fulton356fd192004-08-09 11:34:47 +00001616 retrieve the set_trace function from the pdb module at the time
Tim Peters413ced62004-08-09 15:43:47 +00001617 you use it. The doctest module changes sys.stdout so that it can
1618 capture program output. It also temporarily replaces pdb.set_trace
1619 with a version that restores stdout. This is necessary for you to
Jim Fulton356fd192004-08-09 11:34:47 +00001620 see debugger output.
1621
1622 >>> doc = '''
1623 ... >>> x = 42
1624 ... >>> import pdb; pdb.set_trace()
1625 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +00001626 >>> parser = doctest.DocTestParser()
1627 >>> test = parser.get_doctest(doc, {}, "foo", "foo.py", 0)
Jim Fulton356fd192004-08-09 11:34:47 +00001628 >>> runner = doctest.DocTestRunner(verbose=False)
1629
1630 To demonstrate this, we'll create a fake standard input that
1631 captures our debugger input:
1632
1633 >>> import tempfile
Edward Loper2de91ba2004-08-27 02:07:46 +00001634 >>> real_stdin = sys.stdin
1635 >>> sys.stdin = _FakeInput([
Jim Fulton356fd192004-08-09 11:34:47 +00001636 ... 'print x', # print data defined by the example
1637 ... 'continue', # stop debugging
Edward Loper2de91ba2004-08-27 02:07:46 +00001638 ... ''])
Jim Fulton356fd192004-08-09 11:34:47 +00001639
Edward Loper2de91ba2004-08-27 02:07:46 +00001640 >>> try: runner.run(test)
1641 ... finally: sys.stdin = real_stdin
Jim Fulton356fd192004-08-09 11:34:47 +00001642 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001643 > <doctest foo[1]>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001644 -> import pdb; pdb.set_trace()
1645 (Pdb) print x
1646 42
1647 (Pdb) continue
1648 (0, 2)
Jim Fulton356fd192004-08-09 11:34:47 +00001649
1650 You can also put pdb.set_trace in a function called from a test:
1651
1652 >>> def calls_set_trace():
1653 ... y=2
1654 ... import pdb; pdb.set_trace()
1655
1656 >>> doc = '''
1657 ... >>> x=1
1658 ... >>> calls_set_trace()
1659 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +00001660 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
Edward Loper2de91ba2004-08-27 02:07:46 +00001661 >>> real_stdin = sys.stdin
1662 >>> sys.stdin = _FakeInput([
Jim Fulton356fd192004-08-09 11:34:47 +00001663 ... 'print y', # print data defined in the function
1664 ... 'up', # out of function
1665 ... 'print x', # print data defined by the example
1666 ... 'continue', # stop debugging
Edward Loper2de91ba2004-08-27 02:07:46 +00001667 ... ''])
Jim Fulton356fd192004-08-09 11:34:47 +00001668
Tim Peters50c6bdb2004-11-08 22:07:37 +00001669 >>> try:
1670 ... runner.run(test)
1671 ... finally:
1672 ... sys.stdin = real_stdin
Jim Fulton356fd192004-08-09 11:34:47 +00001673 --Return--
Edward Loper2de91ba2004-08-27 02:07:46 +00001674 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
1675 -> import pdb; pdb.set_trace()
1676 (Pdb) print y
1677 2
1678 (Pdb) up
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001679 > <doctest foo[1]>(1)<module>()
Edward Loper2de91ba2004-08-27 02:07:46 +00001680 -> calls_set_trace()
1681 (Pdb) print x
1682 1
1683 (Pdb) continue
1684 (0, 2)
1685
1686 During interactive debugging, source code is shown, even for
1687 doctest examples:
1688
1689 >>> doc = '''
1690 ... >>> def f(x):
1691 ... ... g(x*2)
1692 ... >>> def g(x):
1693 ... ... print x+3
1694 ... ... import pdb; pdb.set_trace()
1695 ... >>> f(3)
1696 ... '''
1697 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1698 >>> real_stdin = sys.stdin
1699 >>> sys.stdin = _FakeInput([
1700 ... 'list', # list source from example 2
1701 ... 'next', # return from g()
1702 ... 'list', # list source from example 1
1703 ... 'next', # return from f()
1704 ... 'list', # list source from example 3
1705 ... 'continue', # stop debugging
1706 ... ''])
1707 >>> try: runner.run(test)
1708 ... finally: sys.stdin = real_stdin
1709 ... # doctest: +NORMALIZE_WHITESPACE
1710 --Return--
1711 > <doctest foo[1]>(3)g()->None
1712 -> import pdb; pdb.set_trace()
1713 (Pdb) list
1714 1 def g(x):
1715 2 print x+3
1716 3 -> import pdb; pdb.set_trace()
1717 [EOF]
1718 (Pdb) next
1719 --Return--
1720 > <doctest foo[0]>(2)f()->None
1721 -> g(x*2)
1722 (Pdb) list
1723 1 def f(x):
1724 2 -> g(x*2)
1725 [EOF]
1726 (Pdb) next
1727 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001728 > <doctest foo[2]>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001729 -> f(3)
1730 (Pdb) list
1731 1 -> f(3)
1732 [EOF]
1733 (Pdb) continue
1734 **********************************************************************
1735 File "foo.py", line 7, in foo
1736 Failed example:
1737 f(3)
1738 Expected nothing
1739 Got:
1740 9
1741 (1, 3)
Jim Fulton356fd192004-08-09 11:34:47 +00001742 """
1743
Tim Peters50c6bdb2004-11-08 22:07:37 +00001744def test_pdb_set_trace_nested():
1745 """This illustrates more-demanding use of set_trace with nested functions.
1746
1747 >>> class C(object):
1748 ... def calls_set_trace(self):
1749 ... y = 1
1750 ... import pdb; pdb.set_trace()
1751 ... self.f1()
1752 ... y = 2
1753 ... def f1(self):
1754 ... x = 1
1755 ... self.f2()
1756 ... x = 2
1757 ... def f2(self):
1758 ... z = 1
1759 ... z = 2
1760
1761 >>> calls_set_trace = C().calls_set_trace
1762
1763 >>> doc = '''
1764 ... >>> a = 1
1765 ... >>> calls_set_trace()
1766 ... '''
1767 >>> parser = doctest.DocTestParser()
1768 >>> runner = doctest.DocTestRunner(verbose=False)
1769 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1770 >>> real_stdin = sys.stdin
1771 >>> sys.stdin = _FakeInput([
1772 ... 'print y', # print data defined in the function
1773 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print z',
1774 ... 'up', 'print x',
1775 ... 'up', 'print y',
1776 ... 'up', 'print foo',
1777 ... 'continue', # stop debugging
1778 ... ''])
1779
1780 >>> try:
1781 ... runner.run(test)
1782 ... finally:
1783 ... sys.stdin = real_stdin
1784 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1785 -> self.f1()
1786 (Pdb) print y
1787 1
1788 (Pdb) step
1789 --Call--
1790 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
1791 -> def f1(self):
1792 (Pdb) step
1793 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
1794 -> x = 1
1795 (Pdb) step
1796 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1797 -> self.f2()
1798 (Pdb) step
1799 --Call--
1800 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
1801 -> def f2(self):
1802 (Pdb) step
1803 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
1804 -> z = 1
1805 (Pdb) step
1806 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
1807 -> z = 2
1808 (Pdb) print z
1809 1
1810 (Pdb) up
1811 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1812 -> self.f2()
1813 (Pdb) print x
1814 1
1815 (Pdb) up
1816 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1817 -> self.f1()
1818 (Pdb) print y
1819 1
1820 (Pdb) up
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001821 > <doctest foo[1]>(1)<module>()
Tim Peters50c6bdb2004-11-08 22:07:37 +00001822 -> calls_set_trace()
1823 (Pdb) print foo
1824 *** NameError: name 'foo' is not defined
1825 (Pdb) continue
1826 (0, 2)
1827"""
1828
Tim Peters19397e52004-08-06 22:02:59 +00001829def test_DocTestSuite():
Tim Peters1e277ee2004-08-07 05:37:52 +00001830 """DocTestSuite creates a unittest test suite from a doctest.
Tim Peters19397e52004-08-06 22:02:59 +00001831
1832 We create a Suite by providing a module. A module can be provided
1833 by passing a module object:
1834
1835 >>> import unittest
1836 >>> import test.sample_doctest
1837 >>> suite = doctest.DocTestSuite(test.sample_doctest)
1838 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001839 <unittest.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00001840
1841 We can also supply the module by name:
1842
1843 >>> suite = doctest.DocTestSuite('test.sample_doctest')
1844 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001845 <unittest.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00001846
1847 We can use the current module:
1848
1849 >>> suite = test.sample_doctest.test_suite()
1850 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001851 <unittest.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00001852
1853 We can supply global variables. If we pass globs, they will be
1854 used instead of the module globals. Here we'll pass an empty
1855 globals, triggering an extra error:
1856
1857 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
1858 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001859 <unittest.TestResult run=9 errors=0 failures=5>
Tim Peters19397e52004-08-06 22:02:59 +00001860
1861 Alternatively, we can provide extra globals. Here we'll make an
1862 error go away by providing an extra global variable:
1863
1864 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1865 ... extraglobs={'y': 1})
1866 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001867 <unittest.TestResult run=9 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00001868
1869 You can pass option flags. Here we'll cause an extra error
1870 by disabling the blank-line feature:
1871
1872 >>> suite = doctest.DocTestSuite('test.sample_doctest',
Tim Peters1e277ee2004-08-07 05:37:52 +00001873 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
Tim Peters19397e52004-08-06 22:02:59 +00001874 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001875 <unittest.TestResult run=9 errors=0 failures=5>
Tim Peters19397e52004-08-06 22:02:59 +00001876
Tim Peters1e277ee2004-08-07 05:37:52 +00001877 You can supply setUp and tearDown functions:
Tim Peters19397e52004-08-06 22:02:59 +00001878
Jim Fultonf54bad42004-08-28 14:57:56 +00001879 >>> def setUp(t):
Tim Peters19397e52004-08-06 22:02:59 +00001880 ... import test.test_doctest
1881 ... test.test_doctest.sillySetup = True
1882
Jim Fultonf54bad42004-08-28 14:57:56 +00001883 >>> def tearDown(t):
Tim Peters19397e52004-08-06 22:02:59 +00001884 ... import test.test_doctest
1885 ... del test.test_doctest.sillySetup
1886
1887 Here, we installed a silly variable that the test expects:
1888
1889 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1890 ... setUp=setUp, tearDown=tearDown)
1891 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001892 <unittest.TestResult run=9 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00001893
1894 But the tearDown restores sanity:
1895
1896 >>> import test.test_doctest
1897 >>> test.test_doctest.sillySetup
1898 Traceback (most recent call last):
1899 ...
1900 AttributeError: 'module' object has no attribute 'sillySetup'
1901
Jim Fultonf54bad42004-08-28 14:57:56 +00001902 The setUp and tearDown funtions are passed test objects. Here
1903 we'll use the setUp function to supply the missing variable y:
1904
1905 >>> def setUp(test):
1906 ... test.globs['y'] = 1
1907
1908 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
1909 >>> suite.run(unittest.TestResult())
1910 <unittest.TestResult run=9 errors=0 failures=3>
1911
1912 Here, we didn't need to use a tearDown function because we
1913 modified the test globals, which are a copy of the
1914 sample_doctest module dictionary. The test globals are
1915 automatically cleared for us after a test.
1916
Tim Peters19397e52004-08-06 22:02:59 +00001917 Finally, you can provide an alternate test finder. Here we'll
Tim Peters1e277ee2004-08-07 05:37:52 +00001918 use a custom test_finder to to run just the test named bar.
1919 However, the test in the module docstring, and the two tests
1920 in the module __test__ dict, aren't filtered, so we actually
1921 run three tests besides bar's. The filtering mechanisms are
1922 poorly conceived, and will go away someday.
Tim Peters19397e52004-08-06 22:02:59 +00001923
1924 >>> finder = doctest.DocTestFinder(
Tim Petersf727c6c2004-08-08 01:48:59 +00001925 ... _namefilter=lambda prefix, base: base!='bar')
Tim Peters19397e52004-08-06 22:02:59 +00001926 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1927 ... test_finder=finder)
1928 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001929 <unittest.TestResult run=4 errors=0 failures=1>
Tim Peters19397e52004-08-06 22:02:59 +00001930 """
1931
1932def test_DocFileSuite():
1933 """We can test tests found in text files using a DocFileSuite.
1934
1935 We create a suite by providing the names of one or more text
1936 files that include examples:
1937
1938 >>> import unittest
1939 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1940 ... 'test_doctest2.txt')
1941 >>> suite.run(unittest.TestResult())
1942 <unittest.TestResult run=2 errors=0 failures=2>
1943
1944 The test files are looked for in the directory containing the
1945 calling module. A package keyword argument can be provided to
1946 specify a different relative location.
1947
1948 >>> import unittest
1949 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1950 ... 'test_doctest2.txt',
1951 ... package='test')
1952 >>> suite.run(unittest.TestResult())
1953 <unittest.TestResult run=2 errors=0 failures=2>
1954
Edward Loper0273f5b2004-09-18 20:27:04 +00001955 '/' should be used as a path separator. It will be converted
1956 to a native separator at run time:
Tim Peters19397e52004-08-06 22:02:59 +00001957
1958 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
1959 >>> suite.run(unittest.TestResult())
1960 <unittest.TestResult run=1 errors=0 failures=1>
1961
Edward Loper0273f5b2004-09-18 20:27:04 +00001962 If DocFileSuite is used from an interactive session, then files
1963 are resolved relative to the directory of sys.argv[0]:
1964
1965 >>> import new, os.path, test.test_doctest
1966 >>> save_argv = sys.argv
1967 >>> sys.argv = [test.test_doctest.__file__]
1968 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1969 ... package=new.module('__main__'))
1970 >>> sys.argv = save_argv
1971
Edward Loper052d0cd2004-09-19 17:19:33 +00001972 By setting `module_relative=False`, os-specific paths may be
1973 used (including absolute paths and paths relative to the
1974 working directory):
Edward Loper0273f5b2004-09-18 20:27:04 +00001975
1976 >>> # Get the absolute path of the test package.
1977 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
1978 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
1979
1980 >>> # Use it to find the absolute path of test_doctest.txt.
1981 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
1982
Edward Loper052d0cd2004-09-19 17:19:33 +00001983 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
Edward Loper0273f5b2004-09-18 20:27:04 +00001984 >>> suite.run(unittest.TestResult())
1985 <unittest.TestResult run=1 errors=0 failures=1>
1986
Edward Loper052d0cd2004-09-19 17:19:33 +00001987 It is an error to specify `package` when `module_relative=False`:
1988
1989 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
1990 ... package='test')
1991 Traceback (most recent call last):
1992 ValueError: Package may only be specified for module-relative paths.
1993
Tim Peters19397e52004-08-06 22:02:59 +00001994 You can specify initial global variables:
1995
1996 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1997 ... 'test_doctest2.txt',
1998 ... globs={'favorite_color': 'blue'})
1999 >>> suite.run(unittest.TestResult())
2000 <unittest.TestResult run=2 errors=0 failures=1>
2001
2002 In this case, we supplied a missing favorite color. You can
2003 provide doctest options:
2004
2005 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2006 ... 'test_doctest2.txt',
2007 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2008 ... globs={'favorite_color': 'blue'})
2009 >>> suite.run(unittest.TestResult())
2010 <unittest.TestResult run=2 errors=0 failures=2>
2011
2012 And, you can provide setUp and tearDown functions:
2013
2014 You can supply setUp and teatDoen functions:
2015
Jim Fultonf54bad42004-08-28 14:57:56 +00002016 >>> def setUp(t):
Tim Peters19397e52004-08-06 22:02:59 +00002017 ... import test.test_doctest
2018 ... test.test_doctest.sillySetup = True
2019
Jim Fultonf54bad42004-08-28 14:57:56 +00002020 >>> def tearDown(t):
Tim Peters19397e52004-08-06 22:02:59 +00002021 ... import test.test_doctest
2022 ... del test.test_doctest.sillySetup
2023
2024 Here, we installed a silly variable that the test expects:
2025
2026 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2027 ... 'test_doctest2.txt',
2028 ... setUp=setUp, tearDown=tearDown)
2029 >>> suite.run(unittest.TestResult())
2030 <unittest.TestResult run=2 errors=0 failures=1>
2031
2032 But the tearDown restores sanity:
2033
2034 >>> import test.test_doctest
2035 >>> test.test_doctest.sillySetup
2036 Traceback (most recent call last):
2037 ...
2038 AttributeError: 'module' object has no attribute 'sillySetup'
2039
Jim Fultonf54bad42004-08-28 14:57:56 +00002040 The setUp and tearDown funtions are passed test objects.
2041 Here, we'll use a setUp function to set the favorite color in
2042 test_doctest.txt:
2043
2044 >>> def setUp(test):
2045 ... test.globs['favorite_color'] = 'blue'
2046
2047 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2048 >>> suite.run(unittest.TestResult())
2049 <unittest.TestResult run=1 errors=0 failures=0>
2050
2051 Here, we didn't need to use a tearDown function because we
2052 modified the test globals. The test globals are
2053 automatically cleared for us after a test.
Tim Petersdf7a2082004-08-29 00:38:17 +00002054
Fred Drake7c404a42004-12-21 23:46:34 +00002055 Tests in a file run using `DocFileSuite` can also access the
2056 `__file__` global, which is set to the name of the file
2057 containing the tests:
2058
2059 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2060 >>> suite.run(unittest.TestResult())
2061 <unittest.TestResult run=1 errors=0 failures=0>
2062
Jim Fultonf54bad42004-08-28 14:57:56 +00002063 """
Tim Peters19397e52004-08-06 22:02:59 +00002064
Jim Fulton07a349c2004-08-22 14:10:00 +00002065def test_trailing_space_in_test():
2066 """
Tim Petersa7def722004-08-23 22:13:22 +00002067 Trailing spaces in expected output are significant:
Tim Petersc6cbab02004-08-22 19:43:28 +00002068
Jim Fulton07a349c2004-08-22 14:10:00 +00002069 >>> x, y = 'foo', ''
2070 >>> print x, y
2071 foo \n
2072 """
Tim Peters19397e52004-08-06 22:02:59 +00002073
Jim Fultonf54bad42004-08-28 14:57:56 +00002074
2075def test_unittest_reportflags():
2076 """Default unittest reporting flags can be set to control reporting
2077
2078 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2079 only the first failure of each test. First, we'll look at the
2080 output without the flag. The file test_doctest.txt file has two
2081 tests. They both fail if blank lines are disabled:
2082
2083 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2084 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2085 >>> import unittest
2086 >>> result = suite.run(unittest.TestResult())
2087 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2088 Traceback ...
2089 Failed example:
2090 favorite_color
2091 ...
2092 Failed example:
2093 if 1:
2094 ...
2095
2096 Note that we see both failures displayed.
2097
2098 >>> old = doctest.set_unittest_reportflags(
2099 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2100
2101 Now, when we run the test:
2102
2103 >>> result = suite.run(unittest.TestResult())
2104 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2105 Traceback ...
2106 Failed example:
2107 favorite_color
2108 Exception raised:
2109 ...
2110 NameError: name 'favorite_color' is not defined
2111 <BLANKLINE>
2112 <BLANKLINE>
Tim Petersdf7a2082004-08-29 00:38:17 +00002113
Jim Fultonf54bad42004-08-28 14:57:56 +00002114 We get only the first failure.
2115
2116 If we give any reporting options when we set up the tests,
2117 however:
2118
2119 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2120 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2121
2122 Then the default eporting options are ignored:
2123
2124 >>> result = suite.run(unittest.TestResult())
2125 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2126 Traceback ...
2127 Failed example:
2128 favorite_color
2129 ...
2130 Failed example:
2131 if 1:
2132 print 'a'
2133 print
2134 print 'b'
2135 Differences (ndiff with -expected +actual):
2136 a
2137 - <BLANKLINE>
2138 +
2139 b
2140 <BLANKLINE>
2141 <BLANKLINE>
2142
2143
2144 Test runners can restore the formatting flags after they run:
2145
2146 >>> ignored = doctest.set_unittest_reportflags(old)
2147
2148 """
2149
Edward Loper052d0cd2004-09-19 17:19:33 +00002150def test_testfile(): r"""
2151Tests for the `testfile()` function. This function runs all the
2152doctest examples in a given file. In its simple invokation, it is
2153called with the name of a file, which is taken to be relative to the
2154calling module. The return value is (#failures, #tests).
2155
2156 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2157 **********************************************************************
2158 File "...", line 6, in test_doctest.txt
2159 Failed example:
2160 favorite_color
2161 Exception raised:
2162 ...
2163 NameError: name 'favorite_color' is not defined
2164 **********************************************************************
2165 1 items had failures:
2166 1 of 2 in test_doctest.txt
2167 ***Test Failed*** 1 failures.
2168 (1, 2)
2169 >>> doctest.master = None # Reset master.
2170
2171(Note: we'll be clearing doctest.master after each call to
2172`doctest.testfile`, to supress warnings about multiple tests with the
2173same name.)
2174
2175Globals may be specified with the `globs` and `extraglobs` parameters:
2176
2177 >>> globs = {'favorite_color': 'blue'}
2178 >>> doctest.testfile('test_doctest.txt', globs=globs)
2179 (0, 2)
2180 >>> doctest.master = None # Reset master.
2181
2182 >>> extraglobs = {'favorite_color': 'red'}
2183 >>> doctest.testfile('test_doctest.txt', globs=globs,
2184 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2185 **********************************************************************
2186 File "...", line 6, in test_doctest.txt
2187 Failed example:
2188 favorite_color
2189 Expected:
2190 'blue'
2191 Got:
2192 'red'
2193 **********************************************************************
2194 1 items had failures:
2195 1 of 2 in test_doctest.txt
2196 ***Test Failed*** 1 failures.
2197 (1, 2)
2198 >>> doctest.master = None # Reset master.
2199
2200The file may be made relative to a given module or package, using the
2201optional `module_relative` parameter:
2202
2203 >>> doctest.testfile('test_doctest.txt', globs=globs,
2204 ... module_relative='test')
2205 (0, 2)
2206 >>> doctest.master = None # Reset master.
2207
2208Verbosity can be increased with the optional `verbose` paremter:
2209
2210 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2211 Trying:
2212 favorite_color
2213 Expecting:
2214 'blue'
2215 ok
2216 Trying:
2217 if 1:
2218 print 'a'
2219 print
2220 print 'b'
2221 Expecting:
2222 a
2223 <BLANKLINE>
2224 b
2225 ok
2226 1 items passed all tests:
2227 2 tests in test_doctest.txt
2228 2 tests in 1 items.
2229 2 passed and 0 failed.
2230 Test passed.
2231 (0, 2)
2232 >>> doctest.master = None # Reset master.
2233
2234The name of the test may be specified with the optional `name`
2235parameter:
2236
2237 >>> doctest.testfile('test_doctest.txt', name='newname')
2238 ... # doctest: +ELLIPSIS
2239 **********************************************************************
2240 File "...", line 6, in newname
2241 ...
2242 (1, 2)
2243 >>> doctest.master = None # Reset master.
2244
2245The summary report may be supressed with the optional `report`
2246parameter:
2247
2248 >>> doctest.testfile('test_doctest.txt', report=False)
2249 ... # doctest: +ELLIPSIS
2250 **********************************************************************
2251 File "...", line 6, in test_doctest.txt
2252 Failed example:
2253 favorite_color
2254 Exception raised:
2255 ...
2256 NameError: name 'favorite_color' is not defined
2257 (1, 2)
2258 >>> doctest.master = None # Reset master.
2259
2260The optional keyword argument `raise_on_error` can be used to raise an
2261exception on the first error (which may be useful for postmortem
2262debugging):
2263
2264 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2265 ... # doctest: +ELLIPSIS
2266 Traceback (most recent call last):
2267 UnexpectedException: ...
2268 >>> doctest.master = None # Reset master.
2269"""
2270
Tim Petersa7def722004-08-23 22:13:22 +00002271# old_test1, ... used to live in doctest.py, but cluttered it. Note
2272# that these use the deprecated doctest.Tester, so should go away (or
2273# be rewritten) someday.
2274
2275# Ignore all warnings about the use of class Tester in this module.
2276# Note that the name of this module may differ depending on how it's
2277# imported, so the use of __name__ is important.
2278warnings.filterwarnings("ignore", "class Tester", DeprecationWarning,
2279 __name__, 0)
2280
2281def old_test1(): r"""
2282>>> from doctest import Tester
2283>>> t = Tester(globs={'x': 42}, verbose=0)
2284>>> t.runstring(r'''
2285... >>> x = x * 2
2286... >>> print x
2287... 42
2288... ''', 'XYZ')
2289**********************************************************************
2290Line 3, in XYZ
2291Failed example:
2292 print x
2293Expected:
2294 42
2295Got:
2296 84
2297(1, 2)
2298>>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
2299(0, 2)
2300>>> t.summarize()
2301**********************************************************************
23021 items had failures:
2303 1 of 2 in XYZ
2304***Test Failed*** 1 failures.
2305(1, 4)
2306>>> t.summarize(verbose=1)
23071 items passed all tests:
2308 2 tests in example2
2309**********************************************************************
23101 items had failures:
2311 1 of 2 in XYZ
23124 tests in 2 items.
23133 passed and 1 failed.
2314***Test Failed*** 1 failures.
2315(1, 4)
2316"""
2317
2318def old_test2(): r"""
2319 >>> from doctest import Tester
2320 >>> t = Tester(globs={}, verbose=1)
2321 >>> test = r'''
2322 ... # just an example
2323 ... >>> x = 1 + 2
2324 ... >>> x
2325 ... 3
2326 ... '''
2327 >>> t.runstring(test, "Example")
2328 Running string Example
Edward Loperaacf0832004-08-26 01:19:50 +00002329 Trying:
2330 x = 1 + 2
2331 Expecting nothing
Tim Petersa7def722004-08-23 22:13:22 +00002332 ok
Edward Loperaacf0832004-08-26 01:19:50 +00002333 Trying:
2334 x
2335 Expecting:
2336 3
Tim Petersa7def722004-08-23 22:13:22 +00002337 ok
2338 0 of 2 examples failed in string Example
2339 (0, 2)
2340"""
2341
2342def old_test3(): r"""
2343 >>> from doctest import Tester
2344 >>> t = Tester(globs={}, verbose=0)
2345 >>> def _f():
2346 ... '''Trivial docstring example.
2347 ... >>> assert 2 == 2
2348 ... '''
2349 ... return 32
2350 ...
2351 >>> t.rundoc(_f) # expect 0 failures in 1 example
2352 (0, 1)
2353"""
2354
2355def old_test4(): """
2356 >>> import new
2357 >>> m1 = new.module('_m1')
2358 >>> m2 = new.module('_m2')
2359 >>> test_data = \"""
2360 ... def _f():
2361 ... '''>>> assert 1 == 1
2362 ... '''
2363 ... def g():
2364 ... '''>>> assert 2 != 1
2365 ... '''
2366 ... class H:
2367 ... '''>>> assert 2 > 1
2368 ... '''
2369 ... def bar(self):
2370 ... '''>>> assert 1 < 2
2371 ... '''
2372 ... \"""
2373 >>> exec test_data in m1.__dict__
2374 >>> exec test_data in m2.__dict__
2375 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
2376
2377 Tests that objects outside m1 are excluded:
2378
2379 >>> from doctest import Tester
2380 >>> t = Tester(globs={}, verbose=0)
2381 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
2382 (0, 4)
2383
2384 Once more, not excluding stuff outside m1:
2385
2386 >>> t = Tester(globs={}, verbose=0)
2387 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
2388 (0, 8)
2389
2390 The exclusion of objects from outside the designated module is
2391 meant to be invoked automagically by testmod.
2392
2393 >>> doctest.testmod(m1, verbose=False)
2394 (0, 4)
2395"""
2396
Tim Peters8485b562004-08-04 18:46:34 +00002397######################################################################
2398## Main
2399######################################################################
2400
2401def test_main():
2402 # Check the doctest cases in doctest itself:
2403 test_support.run_doctest(doctest, verbosity=True)
2404 # Check the doctest cases defined here:
2405 from test import test_doctest
2406 test_support.run_doctest(test_doctest, verbosity=True)
2407
2408import trace, sys, re, StringIO
2409def test_coverage(coverdir):
2410 tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
2411 trace=0, count=1)
2412 tracer.run('reload(doctest); test_main()')
2413 r = tracer.results()
2414 print 'Writing coverage results...'
2415 r.write_results(show_missing=True, summary=True,
2416 coverdir=coverdir)
2417
2418if __name__ == '__main__':
2419 if '-c' in sys.argv:
2420 test_coverage('/tmp/doctest.cover')
2421 else:
2422 test_main()