blob: 45057c8707800d91d2a7f94b5827fd883bd62260 [file] [log] [blame]
Florent Xicluna2a903b22010-02-27 13:31:23 +00001# -*- coding: utf-8 -*-
Tim Peters8485b562004-08-04 18:46:34 +00002"""
3Test script for doctest.
4"""
5
Florent Xicluna6257a7b2010-03-31 22:01:03 +00006import sys
Barry Warsaw04f357c2002-07-23 19:04:11 +00007from test import test_support
Tim Peters8485b562004-08-04 18:46:34 +00008import doctest
9
Nick Coghlana2053472008-12-14 10:54:50 +000010# NOTE: There are some additional tests relating to interaction with
11# zipimport in the test_zipimport_support test module.
12
Tim Peters8485b562004-08-04 18:46:34 +000013######################################################################
14## Sample Objects (used by test cases)
15######################################################################
16
17def sample_func(v):
18 """
Tim Peters19397e52004-08-06 22:02:59 +000019 Blah blah
20
Tim Peters8485b562004-08-04 18:46:34 +000021 >>> print sample_func(22)
22 44
Tim Peters19397e52004-08-06 22:02:59 +000023
24 Yee ha!
Tim Peters8485b562004-08-04 18:46:34 +000025 """
26 return v+v
27
28class SampleClass:
29 """
30 >>> print 1
31 1
Edward Loper4ae900f2004-09-21 03:20:34 +000032
33 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
34 >>>
35 ...
36
37 Multiline example:
38 >>> sc = SampleClass(3)
39 >>> for i in range(10):
40 ... sc = sc.double()
41 ... print sc.get(),
42 6 12 24 48 96 192 384 768 1536 3072
Tim Peters8485b562004-08-04 18:46:34 +000043 """
44 def __init__(self, val):
45 """
46 >>> print SampleClass(12).get()
47 12
48 """
49 self.val = val
50
51 def double(self):
52 """
53 >>> print SampleClass(12).double().get()
54 24
55 """
56 return SampleClass(self.val + self.val)
57
58 def get(self):
59 """
60 >>> print SampleClass(-5).get()
61 -5
62 """
63 return self.val
64
65 def a_staticmethod(v):
66 """
67 >>> print SampleClass.a_staticmethod(10)
68 11
69 """
70 return v+1
71 a_staticmethod = staticmethod(a_staticmethod)
72
73 def a_classmethod(cls, v):
74 """
75 >>> print SampleClass.a_classmethod(10)
76 12
77 >>> print SampleClass(0).a_classmethod(10)
78 12
79 """
80 return v+2
81 a_classmethod = classmethod(a_classmethod)
82
83 a_property = property(get, doc="""
84 >>> print SampleClass(22).a_property
85 22
86 """)
87
88 class NestedClass:
89 """
90 >>> x = SampleClass.NestedClass(5)
91 >>> y = x.square()
92 >>> print y.get()
93 25
94 """
95 def __init__(self, val=0):
96 """
97 >>> print SampleClass.NestedClass().get()
98 0
99 """
100 self.val = val
101 def square(self):
102 return SampleClass.NestedClass(self.val*self.val)
103 def get(self):
104 return self.val
105
106class SampleNewStyleClass(object):
107 r"""
108 >>> print '1\n2\n3'
109 1
110 2
111 3
112 """
113 def __init__(self, val):
114 """
115 >>> print SampleNewStyleClass(12).get()
116 12
117 """
118 self.val = val
119
120 def double(self):
121 """
122 >>> print SampleNewStyleClass(12).double().get()
123 24
124 """
125 return SampleNewStyleClass(self.val + self.val)
126
127 def get(self):
128 """
129 >>> print SampleNewStyleClass(-5).get()
130 -5
131 """
132 return self.val
133
134######################################################################
Edward Loper2de91ba2004-08-27 02:07:46 +0000135## Fake stdin (for testing interactive debugging)
136######################################################################
137
138class _FakeInput:
139 """
140 A fake input stream for pdb's interactive debugger. Whenever a
141 line is read, print it (to simulate the user typing it), and then
142 return it. The set of lines to return is specified in the
143 constructor; they should not have trailing newlines.
144 """
145 def __init__(self, lines):
146 self.lines = lines
147
148 def readline(self):
149 line = self.lines.pop(0)
150 print line
151 return line+'\n'
152
153######################################################################
Tim Peters8485b562004-08-04 18:46:34 +0000154## Test Cases
155######################################################################
156
157def test_Example(): r"""
158Unit tests for the `Example` class.
159
Edward Lopera6b68322004-08-26 00:05:43 +0000160Example is a simple container class that holds:
161 - `source`: A source string.
162 - `want`: An expected output string.
163 - `exc_msg`: An expected exception message string (or None if no
164 exception is expected).
165 - `lineno`: A line number (within the docstring).
166 - `indent`: The example's indentation in the input string.
167 - `options`: An option dictionary, mapping option flags to True or
168 False.
Tim Peters8485b562004-08-04 18:46:34 +0000169
Edward Lopera6b68322004-08-26 00:05:43 +0000170These attributes are set by the constructor. `source` and `want` are
171required; the other attributes all have default values:
Tim Peters8485b562004-08-04 18:46:34 +0000172
Edward Lopera6b68322004-08-26 00:05:43 +0000173 >>> example = doctest.Example('print 1', '1\n')
174 >>> (example.source, example.want, example.exc_msg,
175 ... example.lineno, example.indent, example.options)
176 ('print 1\n', '1\n', None, 0, 0, {})
177
178The first three attributes (`source`, `want`, and `exc_msg`) may be
179specified positionally; the remaining arguments should be specified as
180keyword arguments:
181
182 >>> exc_msg = 'IndexError: pop from an empty list'
183 >>> example = doctest.Example('[].pop()', '', exc_msg,
184 ... lineno=5, indent=4,
185 ... options={doctest.ELLIPSIS: True})
186 >>> (example.source, example.want, example.exc_msg,
187 ... example.lineno, example.indent, example.options)
188 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
189
190The constructor normalizes the `source` string to end in a newline:
Tim Peters8485b562004-08-04 18:46:34 +0000191
Tim Petersbb431472004-08-09 03:51:46 +0000192 Source spans a single line: no terminating newline.
Edward Lopera6b68322004-08-26 00:05:43 +0000193 >>> e = doctest.Example('print 1', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000194 >>> e.source, e.want
195 ('print 1\n', '1\n')
196
Edward Lopera6b68322004-08-26 00:05:43 +0000197 >>> e = doctest.Example('print 1\n', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000198 >>> e.source, e.want
199 ('print 1\n', '1\n')
Tim Peters8485b562004-08-04 18:46:34 +0000200
Tim Petersbb431472004-08-09 03:51:46 +0000201 Source spans multiple lines: require terminating newline.
Edward Lopera6b68322004-08-26 00:05:43 +0000202 >>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000203 >>> e.source, e.want
204 ('print 1;\nprint 2\n', '1\n2\n')
Tim Peters8485b562004-08-04 18:46:34 +0000205
Edward Lopera6b68322004-08-26 00:05:43 +0000206 >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000207 >>> e.source, e.want
208 ('print 1;\nprint 2\n', '1\n2\n')
209
Edward Lopera6b68322004-08-26 00:05:43 +0000210 Empty source string (which should never appear in real examples)
211 >>> e = doctest.Example('', '')
212 >>> e.source, e.want
213 ('\n', '')
Tim Peters8485b562004-08-04 18:46:34 +0000214
Edward Lopera6b68322004-08-26 00:05:43 +0000215The constructor normalizes the `want` string to end in a newline,
216unless it's the empty string:
217
218 >>> e = doctest.Example('print 1', '1\n')
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 1', '1')
Tim Petersbb431472004-08-09 03:51:46 +0000223 >>> e.source, e.want
224 ('print 1\n', '1\n')
225
Edward Lopera6b68322004-08-26 00:05:43 +0000226 >>> e = doctest.Example('print', '')
Tim Petersbb431472004-08-09 03:51:46 +0000227 >>> e.source, e.want
228 ('print\n', '')
Edward Lopera6b68322004-08-26 00:05:43 +0000229
230The constructor normalizes the `exc_msg` string to end in a newline,
231unless it's `None`:
232
233 Message spans one line
234 >>> exc_msg = 'IndexError: pop from an empty list'
235 >>> e = doctest.Example('[].pop()', '', exc_msg)
236 >>> e.exc_msg
237 'IndexError: pop from an empty list\n'
238
239 >>> exc_msg = 'IndexError: pop from an empty list\n'
240 >>> e = doctest.Example('[].pop()', '', exc_msg)
241 >>> e.exc_msg
242 'IndexError: pop from an empty list\n'
243
244 Message spans multiple lines
245 >>> exc_msg = 'ValueError: 1\n 2'
246 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
247 >>> e.exc_msg
248 'ValueError: 1\n 2\n'
249
250 >>> exc_msg = 'ValueError: 1\n 2\n'
251 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
252 >>> e.exc_msg
253 'ValueError: 1\n 2\n'
254
255 Empty (but non-None) exception message (which should never appear
256 in real examples)
257 >>> exc_msg = ''
258 >>> e = doctest.Example('raise X()', '', exc_msg)
259 >>> e.exc_msg
260 '\n'
Antoine Pitrou6c3f4a82011-12-18 20:20:17 +0100261
262Compare `Example`:
263 >>> example = doctest.Example('print 1', '1\n')
264 >>> same_example = doctest.Example('print 1', '1\n')
265 >>> other_example = doctest.Example('print 42', '42\n')
266 >>> example == same_example
267 True
268 >>> example != same_example
269 False
270 >>> hash(example) == hash(same_example)
271 True
272 >>> example == other_example
273 False
274 >>> example != other_example
275 True
Tim Peters8485b562004-08-04 18:46:34 +0000276"""
277
278def test_DocTest(): r"""
279Unit tests for the `DocTest` class.
280
281DocTest is a collection of examples, extracted from a docstring, along
282with information about where the docstring comes from (a name,
283filename, and line number). The docstring is parsed by the `DocTest`
284constructor:
285
286 >>> docstring = '''
287 ... >>> print 12
288 ... 12
289 ...
290 ... Non-example text.
291 ...
292 ... >>> print 'another\example'
293 ... another
294 ... example
295 ... '''
296 >>> globs = {} # globals to run the test in.
Edward Lopera1ef6112004-08-09 16:14:41 +0000297 >>> parser = doctest.DocTestParser()
298 >>> test = parser.get_doctest(docstring, globs, 'some_test',
299 ... 'some_file', 20)
Tim Peters8485b562004-08-04 18:46:34 +0000300 >>> print test
301 <DocTest some_test from some_file:20 (2 examples)>
302 >>> len(test.examples)
303 2
304 >>> e1, e2 = test.examples
305 >>> (e1.source, e1.want, e1.lineno)
Tim Petersbb431472004-08-09 03:51:46 +0000306 ('print 12\n', '12\n', 1)
Tim Peters8485b562004-08-04 18:46:34 +0000307 >>> (e2.source, e2.want, e2.lineno)
Tim Petersbb431472004-08-09 03:51:46 +0000308 ("print 'another\\example'\n", 'another\nexample\n', 6)
Tim Peters8485b562004-08-04 18:46:34 +0000309
310Source information (name, filename, and line number) is available as
311attributes on the doctest object:
312
313 >>> (test.name, test.filename, test.lineno)
314 ('some_test', 'some_file', 20)
315
316The line number of an example within its containing file is found by
317adding the line number of the example and the line number of its
318containing test:
319
320 >>> test.lineno + e1.lineno
321 21
322 >>> test.lineno + e2.lineno
323 26
324
325If the docstring contains inconsistant leading whitespace in the
326expected output of an example, then `DocTest` will raise a ValueError:
327
328 >>> docstring = r'''
329 ... >>> print 'bad\nindentation'
330 ... bad
331 ... indentation
332 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000333 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000334 Traceback (most recent call last):
Edward Loper00f8da72004-08-26 18:05:07 +0000335 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
Tim Peters8485b562004-08-04 18:46:34 +0000336
337If the docstring contains inconsistent leading whitespace on
338continuation lines, then `DocTest` will raise a ValueError:
339
340 >>> docstring = r'''
341 ... >>> print ('bad indentation',
342 ... ... 2)
343 ... ('bad', 'indentation')
344 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000345 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000346 Traceback (most recent call last):
Edward Loper00f8da72004-08-26 18:05:07 +0000347 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2)'
Tim Peters8485b562004-08-04 18:46:34 +0000348
349If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
350will raise a ValueError:
351
352 >>> docstring = '>>>print 1\n1'
Edward Lopera1ef6112004-08-09 16:14:41 +0000353 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000354 Traceback (most recent call last):
Edward Loper7c748462004-08-09 02:06:06 +0000355 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1'
356
357If there's no blank space after a PS2 prompt ('...'), then `DocTest`
358will raise a ValueError:
359
360 >>> docstring = '>>> if 1:\n...print 1\n1'
Edward Lopera1ef6112004-08-09 16:14:41 +0000361 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Edward Loper7c748462004-08-09 02:06:06 +0000362 Traceback (most recent call last):
363 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1'
364
Antoine Pitrou7a3d8ae2011-12-18 19:27:45 +0100365Compare `DocTest`:
366
367 >>> docstring = '''
368 ... >>> print 12
369 ... 12
370 ... '''
371 >>> test = parser.get_doctest(docstring, globs, 'some_test',
372 ... 'some_test', 20)
373 >>> same_test = parser.get_doctest(docstring, globs, 'some_test',
374 ... 'some_test', 20)
375 >>> test == same_test
376 True
377 >>> test != same_test
378 False
Antoine Pitrou6c3f4a82011-12-18 20:20:17 +0100379 >>> hash(test) == hash(same_test)
380 True
Antoine Pitrou7a3d8ae2011-12-18 19:27:45 +0100381 >>> docstring = '''
382 ... >>> print 42
383 ... 42
384 ... '''
385 >>> other_test = parser.get_doctest(docstring, globs, 'other_test',
386 ... 'other_file', 10)
387 >>> test == other_test
388 False
389 >>> test != other_test
390 True
391
392Compare `DocTestCase`:
393
394 >>> DocTestCase = doctest.DocTestCase
395 >>> test_case = DocTestCase(test)
396 >>> same_test_case = DocTestCase(same_test)
397 >>> other_test_case = DocTestCase(other_test)
398 >>> test_case == same_test_case
399 True
400 >>> test_case != same_test_case
401 False
Antoine Pitrou6c3f4a82011-12-18 20:20:17 +0100402 >>> hash(test_case) == hash(same_test_case)
403 True
Antoine Pitrou7a3d8ae2011-12-18 19:27:45 +0100404 >>> test == other_test_case
405 False
406 >>> test != other_test_case
407 True
408
Tim Peters8485b562004-08-04 18:46:34 +0000409"""
410
Tim Peters8485b562004-08-04 18:46:34 +0000411def test_DocTestFinder(): r"""
412Unit tests for the `DocTestFinder` class.
413
414DocTestFinder is used to extract DocTests from an object's docstring
415and the docstrings of its contained objects. It can be used with
416modules, functions, classes, methods, staticmethods, classmethods, and
417properties.
418
419Finding Tests in Functions
420~~~~~~~~~~~~~~~~~~~~~~~~~~
421For a function whose docstring contains examples, DocTestFinder.find()
422will return a single test (for that function's docstring):
423
Tim Peters8485b562004-08-04 18:46:34 +0000424 >>> finder = doctest.DocTestFinder()
Jim Fulton07a349c2004-08-22 14:10:00 +0000425
426We'll simulate a __file__ attr that ends in pyc:
427
428 >>> import test.test_doctest
429 >>> old = test.test_doctest.__file__
430 >>> test.test_doctest.__file__ = 'test_doctest.pyc'
431
Tim Peters8485b562004-08-04 18:46:34 +0000432 >>> tests = finder.find(sample_func)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000433
Edward Loper74bca7a2004-08-12 02:27:44 +0000434 >>> print tests # doctest: +ELLIPSIS
Florent Xicluna2a903b22010-02-27 13:31:23 +0000435 [<DocTest sample_func from ...:17 (1 example)>]
Edward Loper8e4a34b2004-08-12 02:34:27 +0000436
Tim Peters4de7c5c2004-08-23 22:38:05 +0000437The exact name depends on how test_doctest was invoked, so allow for
438leading path components.
439
440 >>> tests[0].filename # doctest: +ELLIPSIS
441 '...test_doctest.py'
Jim Fulton07a349c2004-08-22 14:10:00 +0000442
443 >>> test.test_doctest.__file__ = old
Tim Petersc6cbab02004-08-22 19:43:28 +0000444
Jim Fulton07a349c2004-08-22 14:10:00 +0000445
Tim Peters8485b562004-08-04 18:46:34 +0000446 >>> e = tests[0].examples[0]
Tim Petersbb431472004-08-09 03:51:46 +0000447 >>> (e.source, e.want, e.lineno)
448 ('print sample_func(22)\n', '44\n', 3)
Tim Peters8485b562004-08-04 18:46:34 +0000449
Edward Loper32ddbf72004-09-13 05:47:24 +0000450By default, tests are created for objects with no docstring:
Tim Peters8485b562004-08-04 18:46:34 +0000451
452 >>> def no_docstring(v):
453 ... pass
Tim Peters958cc892004-09-13 14:53:28 +0000454 >>> finder.find(no_docstring)
455 []
Edward Loper32ddbf72004-09-13 05:47:24 +0000456
457However, the optional argument `exclude_empty` to the DocTestFinder
458constructor can be used to exclude tests for objects with empty
459docstrings:
460
461 >>> def no_docstring(v):
462 ... pass
463 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
464 >>> excl_empty_finder.find(no_docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000465 []
466
467If the function has a docstring with no examples, then a test with no
468examples is returned. (This lets `DocTestRunner` collect statistics
469about which functions have no tests -- but is that useful? And should
470an empty test also be created when there's no docstring?)
471
472 >>> def no_examples(v):
473 ... ''' no doctest examples '''
Tim Peters17b56372004-09-11 17:33:27 +0000474 >>> finder.find(no_examples) # doctest: +ELLIPSIS
475 [<DocTest no_examples from ...:1 (no examples)>]
Tim Peters8485b562004-08-04 18:46:34 +0000476
477Finding Tests in Classes
478~~~~~~~~~~~~~~~~~~~~~~~~
479For a class, DocTestFinder will create a test for the class's
480docstring, and will recursively explore its contents, including
481methods, classmethods, staticmethods, properties, and nested classes.
482
483 >>> finder = doctest.DocTestFinder()
484 >>> tests = finder.find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000485 >>> for t in tests:
486 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000487 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000488 3 SampleClass.NestedClass
489 1 SampleClass.NestedClass.__init__
490 1 SampleClass.__init__
491 2 SampleClass.a_classmethod
492 1 SampleClass.a_property
493 1 SampleClass.a_staticmethod
494 1 SampleClass.double
495 1 SampleClass.get
496
497New-style classes are also supported:
498
499 >>> tests = finder.find(SampleNewStyleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000500 >>> for t in tests:
501 ... print '%2s %s' % (len(t.examples), t.name)
502 1 SampleNewStyleClass
503 1 SampleNewStyleClass.__init__
504 1 SampleNewStyleClass.double
505 1 SampleNewStyleClass.get
506
507Finding Tests in Modules
508~~~~~~~~~~~~~~~~~~~~~~~~
509For a module, DocTestFinder will create a test for the class's
510docstring, and will recursively explore its contents, including
511functions, classes, and the `__test__` dictionary, if it exists:
512
513 >>> # A module
Christian Heimesc756d002007-11-27 21:34:01 +0000514 >>> import types
515 >>> m = types.ModuleType('some_module')
Tim Peters8485b562004-08-04 18:46:34 +0000516 >>> def triple(val):
517 ... '''
Edward Loper4ae900f2004-09-21 03:20:34 +0000518 ... >>> print triple(11)
Tim Peters8485b562004-08-04 18:46:34 +0000519 ... 33
520 ... '''
521 ... return val*3
522 >>> m.__dict__.update({
523 ... 'sample_func': sample_func,
524 ... 'SampleClass': SampleClass,
525 ... '__doc__': '''
526 ... Module docstring.
527 ... >>> print 'module'
528 ... module
529 ... ''',
530 ... '__test__': {
531 ... 'd': '>>> print 6\n6\n>>> print 7\n7\n',
532 ... 'c': triple}})
533
534 >>> finder = doctest.DocTestFinder()
535 >>> # Use module=test.test_doctest, to prevent doctest from
536 >>> # ignoring the objects since they weren't defined in m.
537 >>> import test.test_doctest
538 >>> tests = finder.find(m, module=test.test_doctest)
Tim Peters8485b562004-08-04 18:46:34 +0000539 >>> for t in tests:
540 ... print '%2s %s' % (len(t.examples), t.name)
541 1 some_module
Edward Loper4ae900f2004-09-21 03:20:34 +0000542 3 some_module.SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000543 3 some_module.SampleClass.NestedClass
544 1 some_module.SampleClass.NestedClass.__init__
545 1 some_module.SampleClass.__init__
546 2 some_module.SampleClass.a_classmethod
547 1 some_module.SampleClass.a_property
548 1 some_module.SampleClass.a_staticmethod
549 1 some_module.SampleClass.double
550 1 some_module.SampleClass.get
Tim Petersc5684782004-09-13 01:07:12 +0000551 1 some_module.__test__.c
552 2 some_module.__test__.d
Tim Peters8485b562004-08-04 18:46:34 +0000553 1 some_module.sample_func
554
555Duplicate Removal
556~~~~~~~~~~~~~~~~~
557If a single object is listed twice (under different names), then tests
558will only be generated for it once:
559
Tim Petersf3f57472004-08-08 06:11:48 +0000560 >>> from test import doctest_aliases
Amaury Forgeot d'Arcf81ff982009-06-14 21:20:40 +0000561 >>> assert doctest_aliases.TwoNames.f
562 >>> assert doctest_aliases.TwoNames.g
Edward Loper32ddbf72004-09-13 05:47:24 +0000563 >>> tests = excl_empty_finder.find(doctest_aliases)
Tim Peters8485b562004-08-04 18:46:34 +0000564 >>> print len(tests)
565 2
566 >>> print tests[0].name
Tim Petersf3f57472004-08-08 06:11:48 +0000567 test.doctest_aliases.TwoNames
568
569 TwoNames.f and TwoNames.g are bound to the same object.
570 We can't guess which will be found in doctest's traversal of
571 TwoNames.__dict__ first, so we have to allow for either.
572
573 >>> tests[1].name.split('.')[-1] in ['f', 'g']
Tim Peters8485b562004-08-04 18:46:34 +0000574 True
575
Tim Petersbf0400a2006-06-05 01:43:03 +0000576Empty Tests
577~~~~~~~~~~~
578By default, an object with no doctests doesn't create any tests:
Tim Peters8485b562004-08-04 18:46:34 +0000579
Tim Petersbf0400a2006-06-05 01:43:03 +0000580 >>> tests = doctest.DocTestFinder().find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000581 >>> for t in tests:
582 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000583 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000584 3 SampleClass.NestedClass
585 1 SampleClass.NestedClass.__init__
Tim Peters958cc892004-09-13 14:53:28 +0000586 1 SampleClass.__init__
Tim Petersbf0400a2006-06-05 01:43:03 +0000587 2 SampleClass.a_classmethod
588 1 SampleClass.a_property
589 1 SampleClass.a_staticmethod
Tim Peters958cc892004-09-13 14:53:28 +0000590 1 SampleClass.double
591 1 SampleClass.get
592
593By default, that excluded objects with no doctests. exclude_empty=False
594tells it to include (empty) tests for objects with no doctests. This feature
595is really to support backward compatibility in what doctest.master.summarize()
596displays.
597
Tim Petersbf0400a2006-06-05 01:43:03 +0000598 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
Tim Peters958cc892004-09-13 14:53:28 +0000599 >>> for t in tests:
600 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000601 3 SampleClass
Tim Peters958cc892004-09-13 14:53:28 +0000602 3 SampleClass.NestedClass
603 1 SampleClass.NestedClass.__init__
Edward Loper32ddbf72004-09-13 05:47:24 +0000604 0 SampleClass.NestedClass.get
605 0 SampleClass.NestedClass.square
Tim Peters8485b562004-08-04 18:46:34 +0000606 1 SampleClass.__init__
Tim Peters8485b562004-08-04 18:46:34 +0000607 2 SampleClass.a_classmethod
608 1 SampleClass.a_property
609 1 SampleClass.a_staticmethod
610 1 SampleClass.double
611 1 SampleClass.get
612
Tim Peters8485b562004-08-04 18:46:34 +0000613Turning off Recursion
614~~~~~~~~~~~~~~~~~~~~~
615DocTestFinder can be told not to look for tests in contained objects
616using the `recurse` flag:
617
618 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000619 >>> for t in tests:
620 ... print '%2s %s' % (len(t.examples), t.name)
Edward Loper4ae900f2004-09-21 03:20:34 +0000621 3 SampleClass
Edward Loperb51b2342004-08-17 16:37:12 +0000622
623Line numbers
624~~~~~~~~~~~~
625DocTestFinder finds the line number of each example:
626
627 >>> def f(x):
628 ... '''
629 ... >>> x = 12
630 ...
631 ... some text
632 ...
633 ... >>> # examples are not created for comments & bare prompts.
634 ... >>>
635 ... ...
636 ...
637 ... >>> for x in range(10):
638 ... ... print x,
639 ... 0 1 2 3 4 5 6 7 8 9
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000640 ... >>> x//2
Edward Loperb51b2342004-08-17 16:37:12 +0000641 ... 6
642 ... '''
643 >>> test = doctest.DocTestFinder().find(f)[0]
644 >>> [e.lineno for e in test.examples]
645 [1, 9, 12]
Tim Peters8485b562004-08-04 18:46:34 +0000646"""
647
Edward Loper00f8da72004-08-26 18:05:07 +0000648def test_DocTestParser(): r"""
649Unit tests for the `DocTestParser` class.
650
651DocTestParser is used to parse docstrings containing doctest examples.
652
653The `parse` method divides a docstring into examples and intervening
654text:
655
656 >>> s = '''
657 ... >>> x, y = 2, 3 # no output expected
658 ... >>> if 1:
659 ... ... print x
660 ... ... print y
661 ... 2
662 ... 3
663 ...
664 ... Some text.
665 ... >>> x+y
666 ... 5
667 ... '''
668 >>> parser = doctest.DocTestParser()
669 >>> for piece in parser.parse(s):
670 ... if isinstance(piece, doctest.Example):
671 ... print 'Example:', (piece.source, piece.want, piece.lineno)
672 ... else:
673 ... print ' Text:', `piece`
674 Text: '\n'
675 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
676 Text: ''
677 Example: ('if 1:\n print x\n print y\n', '2\n3\n', 2)
678 Text: '\nSome text.\n'
679 Example: ('x+y\n', '5\n', 9)
680 Text: ''
681
682The `get_examples` method returns just the examples:
683
684 >>> for piece in parser.get_examples(s):
685 ... print (piece.source, piece.want, piece.lineno)
686 ('x, y = 2, 3 # no output expected\n', '', 1)
687 ('if 1:\n print x\n print y\n', '2\n3\n', 2)
688 ('x+y\n', '5\n', 9)
689
690The `get_doctest` method creates a Test from the examples, along with the
691given arguments:
692
693 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
694 >>> (test.name, test.filename, test.lineno)
695 ('name', 'filename', 5)
696 >>> for piece in test.examples:
697 ... print (piece.source, piece.want, piece.lineno)
698 ('x, y = 2, 3 # no output expected\n', '', 1)
699 ('if 1:\n print x\n print y\n', '2\n3\n', 2)
700 ('x+y\n', '5\n', 9)
701"""
702
Tim Peters8485b562004-08-04 18:46:34 +0000703class test_DocTestRunner:
704 def basics(): r"""
705Unit tests for the `DocTestRunner` class.
706
707DocTestRunner is used to run DocTest test cases, and to accumulate
708statistics. Here's a simple DocTest case we can use:
709
710 >>> def f(x):
711 ... '''
712 ... >>> x = 12
713 ... >>> print x
714 ... 12
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000715 ... >>> x//2
Tim Peters8485b562004-08-04 18:46:34 +0000716 ... 6
717 ... '''
718 >>> test = doctest.DocTestFinder().find(f)[0]
719
720The main DocTestRunner interface is the `run` method, which runs a
721given DocTest case in a given namespace (globs). It returns a tuple
722`(f,t)`, where `f` is the number of failed tests and `t` is the number
723of tried tests.
724
725 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000726 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000727
728If any example produces incorrect output, then the test runner reports
729the failure and proceeds to the next example:
730
731 >>> def f(x):
732 ... '''
733 ... >>> x = 12
734 ... >>> print x
735 ... 14
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000736 ... >>> x//2
Tim Peters8485b562004-08-04 18:46:34 +0000737 ... 6
738 ... '''
739 >>> test = doctest.DocTestFinder().find(f)[0]
740 >>> doctest.DocTestRunner(verbose=True).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000741 ... # doctest: +ELLIPSIS
Edward Loperaacf0832004-08-26 01:19:50 +0000742 Trying:
743 x = 12
744 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000745 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000746 Trying:
747 print x
748 Expecting:
749 14
Tim Peters8485b562004-08-04 18:46:34 +0000750 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000751 File ..., line 4, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000752 Failed example:
753 print x
754 Expected:
755 14
756 Got:
757 12
Edward Loperaacf0832004-08-26 01:19:50 +0000758 Trying:
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000759 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000760 Expecting:
761 6
Tim Peters8485b562004-08-04 18:46:34 +0000762 ok
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000763 TestResults(failed=1, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000764"""
765 def verbose_flag(): r"""
766The `verbose` flag makes the test runner generate more detailed
767output:
768
769 >>> def f(x):
770 ... '''
771 ... >>> x = 12
772 ... >>> print x
773 ... 12
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000774 ... >>> x//2
Tim Peters8485b562004-08-04 18:46:34 +0000775 ... 6
776 ... '''
777 >>> test = doctest.DocTestFinder().find(f)[0]
778
779 >>> doctest.DocTestRunner(verbose=True).run(test)
Edward Loperaacf0832004-08-26 01:19:50 +0000780 Trying:
781 x = 12
782 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000783 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000784 Trying:
785 print x
786 Expecting:
787 12
Tim Peters8485b562004-08-04 18:46:34 +0000788 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000789 Trying:
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000790 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000791 Expecting:
792 6
Tim Peters8485b562004-08-04 18:46:34 +0000793 ok
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000794 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000795
796If the `verbose` flag is unspecified, then the output will be verbose
797iff `-v` appears in sys.argv:
798
799 >>> # Save the real sys.argv list.
800 >>> old_argv = sys.argv
801
802 >>> # If -v does not appear in sys.argv, then output isn't verbose.
803 >>> sys.argv = ['test']
804 >>> doctest.DocTestRunner().run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000805 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000806
807 >>> # If -v does appear in sys.argv, then output is verbose.
808 >>> sys.argv = ['test', '-v']
809 >>> doctest.DocTestRunner().run(test)
Edward Loperaacf0832004-08-26 01:19:50 +0000810 Trying:
811 x = 12
812 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000813 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000814 Trying:
815 print x
816 Expecting:
817 12
Tim Peters8485b562004-08-04 18:46:34 +0000818 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000819 Trying:
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000820 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000821 Expecting:
822 6
Tim Peters8485b562004-08-04 18:46:34 +0000823 ok
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000824 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000825
826 >>> # Restore sys.argv
827 >>> sys.argv = old_argv
828
829In the remaining examples, the test runner's verbosity will be
830explicitly set, to ensure that the test behavior is consistent.
831 """
832 def exceptions(): r"""
833Tests of `DocTestRunner`'s exception handling.
834
835An expected exception is specified with a traceback message. The
836lines between the first line and the type/value may be omitted or
837replaced with any other string:
838
839 >>> def f(x):
840 ... '''
841 ... >>> x = 12
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000842 ... >>> print x//0
Tim Peters8485b562004-08-04 18:46:34 +0000843 ... Traceback (most recent call last):
844 ... ZeroDivisionError: integer division or modulo by zero
845 ... '''
846 >>> test = doctest.DocTestFinder().find(f)[0]
847 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000848 TestResults(failed=0, attempted=2)
Tim Peters8485b562004-08-04 18:46:34 +0000849
Edward Loper19b19582004-08-25 23:07:03 +0000850An example may not generate output before it raises an exception; if
851it does, then the traceback message will not be recognized as
852signaling an expected exception, so the example will be reported as an
853unexpected exception:
Tim Peters8485b562004-08-04 18:46:34 +0000854
855 >>> def f(x):
856 ... '''
857 ... >>> x = 12
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000858 ... >>> print 'pre-exception output', x//0
Tim Peters8485b562004-08-04 18:46:34 +0000859 ... pre-exception output
860 ... Traceback (most recent call last):
861 ... ZeroDivisionError: integer division or modulo by zero
862 ... '''
863 >>> test = doctest.DocTestFinder().find(f)[0]
864 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper19b19582004-08-25 23:07:03 +0000865 ... # doctest: +ELLIPSIS
866 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000867 File ..., line 4, in f
Edward Loper19b19582004-08-25 23:07:03 +0000868 Failed example:
Tim Peters1c5bc1c2006-03-28 07:28:40 +0000869 print 'pre-exception output', x//0
Edward Loper19b19582004-08-25 23:07:03 +0000870 Exception raised:
871 ...
872 ZeroDivisionError: integer division or modulo by zero
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000873 TestResults(failed=1, attempted=2)
Tim Peters8485b562004-08-04 18:46:34 +0000874
875Exception messages may contain newlines:
876
877 >>> def f(x):
878 ... r'''
879 ... >>> raise ValueError, 'multi\nline\nmessage'
880 ... Traceback (most recent call last):
881 ... ValueError: multi
882 ... line
883 ... message
884 ... '''
885 >>> test = doctest.DocTestFinder().find(f)[0]
886 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000887 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000888
889If an exception is expected, but an exception with the wrong type or
890message is raised, then it is reported as a failure:
891
892 >>> def f(x):
893 ... r'''
894 ... >>> raise ValueError, 'message'
895 ... Traceback (most recent call last):
896 ... ValueError: wrong message
897 ... '''
898 >>> test = doctest.DocTestFinder().find(f)[0]
899 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000900 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000901 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000902 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000903 Failed example:
904 raise ValueError, 'message'
Tim Peters8485b562004-08-04 18:46:34 +0000905 Expected:
906 Traceback (most recent call last):
907 ValueError: wrong message
908 Got:
909 Traceback (most recent call last):
Edward Loper8e4a34b2004-08-12 02:34:27 +0000910 ...
Tim Peters8485b562004-08-04 18:46:34 +0000911 ValueError: message
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000912 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000913
Tim Peters1fbf9c52004-09-04 17:21:02 +0000914However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
915detail:
916
917 >>> def f(x):
918 ... r'''
919 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
920 ... Traceback (most recent call last):
921 ... ValueError: wrong message
922 ... '''
923 >>> test = doctest.DocTestFinder().find(f)[0]
924 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +0000925 TestResults(failed=0, attempted=1)
Tim Peters1fbf9c52004-09-04 17:21:02 +0000926
Nick Coghlandfb45df2010-04-28 14:29:06 +0000927IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
928between Python versions. For example, in Python 3.x, the module path of
929the exception is in the output, but this will fail under Python 2:
930
931 >>> def f(x):
932 ... r'''
933 ... >>> from httplib import HTTPException
934 ... >>> raise HTTPException('message')
935 ... Traceback (most recent call last):
936 ... httplib.HTTPException: message
937 ... '''
938 >>> test = doctest.DocTestFinder().find(f)[0]
939 >>> doctest.DocTestRunner(verbose=False).run(test)
940 ... # doctest: +ELLIPSIS
941 **********************************************************************
942 File ..., line 4, in f
943 Failed example:
944 raise HTTPException('message')
945 Expected:
946 Traceback (most recent call last):
947 httplib.HTTPException: message
948 Got:
949 Traceback (most recent call last):
950 ...
951 HTTPException: message
952 TestResults(failed=1, attempted=2)
953
954But in Python 2 the module path is not included, an therefore a test must look
955like the following test to succeed in Python 2. But that test will fail under
956Python 3.
957
958 >>> def f(x):
959 ... r'''
960 ... >>> from httplib import HTTPException
961 ... >>> raise HTTPException('message')
962 ... Traceback (most recent call last):
963 ... HTTPException: message
964 ... '''
965 >>> test = doctest.DocTestFinder().find(f)[0]
966 >>> doctest.DocTestRunner(verbose=False).run(test)
967 TestResults(failed=0, attempted=2)
968
969However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
970(if any) will be ignored:
971
972 >>> def f(x):
973 ... r'''
974 ... >>> from httplib import HTTPException
975 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
976 ... Traceback (most recent call last):
977 ... HTTPException: message
978 ... '''
979 >>> test = doctest.DocTestFinder().find(f)[0]
980 >>> doctest.DocTestRunner(verbose=False).run(test)
981 TestResults(failed=0, attempted=2)
982
983The module path will be completely ignored, so two different module paths will
984still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
985be used when exceptions have changed module.
986
987 >>> def f(x):
988 ... r'''
989 ... >>> from httplib import HTTPException
990 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
991 ... Traceback (most recent call last):
992 ... foo.bar.HTTPException: message
993 ... '''
994 >>> test = doctest.DocTestFinder().find(f)[0]
995 >>> doctest.DocTestRunner(verbose=False).run(test)
996 TestResults(failed=0, attempted=2)
997
Tim Peters1fbf9c52004-09-04 17:21:02 +0000998But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
999
1000 >>> def f(x):
1001 ... r'''
1002 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
1003 ... Traceback (most recent call last):
1004 ... TypeError: wrong type
1005 ... '''
1006 >>> test = doctest.DocTestFinder().find(f)[0]
1007 >>> doctest.DocTestRunner(verbose=False).run(test)
1008 ... # doctest: +ELLIPSIS
1009 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001010 File ..., line 3, in f
Tim Peters1fbf9c52004-09-04 17:21:02 +00001011 Failed example:
1012 raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
1013 Expected:
1014 Traceback (most recent call last):
1015 TypeError: wrong type
1016 Got:
1017 Traceback (most recent call last):
1018 ...
1019 ValueError: message
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001020 TestResults(failed=1, attempted=1)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001021
Tim Peters8485b562004-08-04 18:46:34 +00001022If an exception is raised but not expected, then it is reported as an
1023unexpected exception:
1024
Tim Peters8485b562004-08-04 18:46:34 +00001025 >>> def f(x):
1026 ... r'''
Tim Peters1c5bc1c2006-03-28 07:28:40 +00001027 ... >>> 1//0
Tim Peters8485b562004-08-04 18:46:34 +00001028 ... 0
1029 ... '''
1030 >>> test = doctest.DocTestFinder().find(f)[0]
1031 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper74bca7a2004-08-12 02:27:44 +00001032 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001033 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001034 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001035 Failed example:
Tim Peters1c5bc1c2006-03-28 07:28:40 +00001036 1//0
Tim Peters8485b562004-08-04 18:46:34 +00001037 Exception raised:
1038 Traceback (most recent call last):
Jim Fulton07a349c2004-08-22 14:10:00 +00001039 ...
Tim Peters8485b562004-08-04 18:46:34 +00001040 ZeroDivisionError: integer division or modulo by zero
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001041 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001042"""
Georg Brandl50775992010-08-01 19:33:15 +00001043 def displayhook(): r"""
1044Test that changing sys.displayhook doesn't matter for doctest.
1045
1046 >>> import sys
1047 >>> orig_displayhook = sys.displayhook
1048 >>> def my_displayhook(x):
1049 ... print('hi!')
1050 >>> sys.displayhook = my_displayhook
1051 >>> def f():
1052 ... '''
1053 ... >>> 3
1054 ... 3
1055 ... '''
1056 >>> test = doctest.DocTestFinder().find(f)[0]
1057 >>> r = doctest.DocTestRunner(verbose=False).run(test)
1058 >>> post_displayhook = sys.displayhook
1059
1060 We need to restore sys.displayhook now, so that we'll be able to test
1061 results.
1062
1063 >>> sys.displayhook = orig_displayhook
1064
1065 Ok, now we can check that everything is ok.
1066
1067 >>> r
1068 TestResults(failed=0, attempted=1)
1069 >>> post_displayhook is my_displayhook
1070 True
1071"""
Tim Peters8485b562004-08-04 18:46:34 +00001072 def optionflags(): r"""
1073Tests of `DocTestRunner`'s option flag handling.
1074
1075Several option flags can be used to customize the behavior of the test
1076runner. These are defined as module constants in doctest, and passed
Georg Brandlf725b952008-01-05 19:44:22 +00001077to the DocTestRunner constructor (multiple constants should be ORed
Tim Peters8485b562004-08-04 18:46:34 +00001078together).
1079
1080The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
1081and 1/0:
1082
1083 >>> def f(x):
1084 ... '>>> True\n1\n'
1085
1086 >>> # Without the flag:
1087 >>> test = doctest.DocTestFinder().find(f)[0]
1088 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001089 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001090
1091 >>> # With the flag:
1092 >>> test = doctest.DocTestFinder().find(f)[0]
1093 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1094 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001095 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001096 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001097 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001098 Failed example:
1099 True
1100 Expected:
1101 1
1102 Got:
1103 True
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001104 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001105
1106The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1107and the '<BLANKLINE>' marker:
1108
1109 >>> def f(x):
1110 ... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n'
1111
1112 >>> # Without the flag:
1113 >>> test = doctest.DocTestFinder().find(f)[0]
1114 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001115 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001116
1117 >>> # With the flag:
1118 >>> test = doctest.DocTestFinder().find(f)[0]
1119 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
1120 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001121 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001122 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001123 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001124 Failed example:
1125 print "a\n\nb"
Tim Peters8485b562004-08-04 18:46:34 +00001126 Expected:
1127 a
1128 <BLANKLINE>
1129 b
1130 Got:
1131 a
1132 <BLANKLINE>
1133 b
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001134 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001135
1136The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1137treated as equal:
1138
1139 >>> def f(x):
1140 ... '>>> print 1, 2, 3\n 1 2\n 3'
1141
1142 >>> # Without the flag:
1143 >>> test = doctest.DocTestFinder().find(f)[0]
1144 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001145 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001146 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001147 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001148 Failed example:
1149 print 1, 2, 3
Tim Peters8485b562004-08-04 18:46:34 +00001150 Expected:
1151 1 2
1152 3
Jim Fulton07a349c2004-08-22 14:10:00 +00001153 Got:
1154 1 2 3
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001155 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001156
1157 >>> # With the flag:
1158 >>> test = doctest.DocTestFinder().find(f)[0]
1159 >>> flags = doctest.NORMALIZE_WHITESPACE
1160 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001161 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001162
Tim Peters026f8dc2004-08-19 16:38:58 +00001163 An example from the docs:
1164 >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
1165 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1166 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1167
Tim Peters8485b562004-08-04 18:46:34 +00001168The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1169output to match any substring in the actual output:
1170
1171 >>> def f(x):
1172 ... '>>> print range(15)\n[0, 1, 2, ..., 14]\n'
1173
1174 >>> # Without the flag:
1175 >>> test = doctest.DocTestFinder().find(f)[0]
1176 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001177 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001178 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001179 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001180 Failed example:
1181 print range(15)
1182 Expected:
1183 [0, 1, 2, ..., 14]
1184 Got:
1185 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001186 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001187
1188 >>> # With the flag:
1189 >>> test = doctest.DocTestFinder().find(f)[0]
1190 >>> flags = doctest.ELLIPSIS
1191 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001192 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001193
Tim Peterse594bee2004-08-22 01:47:51 +00001194 ... also matches nothing:
Tim Peters1cf3aa62004-08-19 06:49:33 +00001195
1196 >>> for i in range(100):
Tim Peterse594bee2004-08-22 01:47:51 +00001197 ... print i**2, #doctest: +ELLIPSIS
1198 0 1...4...9 16 ... 36 49 64 ... 9801
Tim Peters1cf3aa62004-08-19 06:49:33 +00001199
Tim Peters026f8dc2004-08-19 16:38:58 +00001200 ... can be surprising; e.g., this test passes:
Tim Peters26b3ebb2004-08-19 08:10:08 +00001201
1202 >>> for i in range(21): #doctest: +ELLIPSIS
Tim Peterse594bee2004-08-22 01:47:51 +00001203 ... print i,
1204 0 1 2 ...1...2...0
Tim Peters26b3ebb2004-08-19 08:10:08 +00001205
Tim Peters026f8dc2004-08-19 16:38:58 +00001206 Examples from the docs:
1207
1208 >>> print range(20) # doctest:+ELLIPSIS
1209 [0, 1, ..., 18, 19]
1210
1211 >>> print range(20) # doctest: +ELLIPSIS
1212 ... # doctest: +NORMALIZE_WHITESPACE
1213 [0, 1, ..., 18, 19]
1214
Tim Peters711bf302006-04-25 03:31:36 +00001215The SKIP flag causes an example to be skipped entirely. I.e., the
1216example is not run. It can be useful in contexts where doctest
1217examples serve as both documentation and test cases, and an example
1218should be included for documentation purposes, but should not be
1219checked (e.g., because its output is random, or depends on resources
1220which would be unavailable.) The SKIP flag can also be used for
1221'commenting out' broken examples.
1222
1223 >>> import unavailable_resource # doctest: +SKIP
1224 >>> unavailable_resource.do_something() # doctest: +SKIP
1225 >>> unavailable_resource.blow_up() # doctest: +SKIP
1226 Traceback (most recent call last):
1227 ...
1228 UncheckedBlowUpError: Nobody checks me.
1229
1230 >>> import random
1231 >>> print random.random() # doctest: +SKIP
1232 0.721216923889
1233
Edward Loper71f55af2004-08-26 01:41:51 +00001234The REPORT_UDIFF flag causes failures that involve multi-line expected
Tim Peters8485b562004-08-04 18:46:34 +00001235and actual outputs to be displayed using a unified diff:
1236
1237 >>> def f(x):
1238 ... r'''
1239 ... >>> print '\n'.join('abcdefg')
1240 ... a
1241 ... B
1242 ... c
1243 ... d
1244 ... f
1245 ... g
1246 ... h
1247 ... '''
1248
1249 >>> # Without the flag:
1250 >>> test = doctest.DocTestFinder().find(f)[0]
1251 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001252 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001253 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001254 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001255 Failed example:
1256 print '\n'.join('abcdefg')
Tim Peters8485b562004-08-04 18:46:34 +00001257 Expected:
1258 a
1259 B
1260 c
1261 d
1262 f
1263 g
1264 h
1265 Got:
1266 a
1267 b
1268 c
1269 d
1270 e
1271 f
1272 g
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001273 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001274
1275 >>> # With the flag:
1276 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001277 >>> flags = doctest.REPORT_UDIFF
Tim Peters8485b562004-08-04 18:46:34 +00001278 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001279 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001280 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001281 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001282 Failed example:
1283 print '\n'.join('abcdefg')
Edward Loper56629292004-08-26 01:31:56 +00001284 Differences (unified diff with -expected +actual):
Tim Peterse7edcb82004-08-26 05:44:27 +00001285 @@ -1,7 +1,7 @@
Tim Peters8485b562004-08-04 18:46:34 +00001286 a
1287 -B
1288 +b
1289 c
1290 d
1291 +e
1292 f
1293 g
1294 -h
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001295 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001296
Edward Loper71f55af2004-08-26 01:41:51 +00001297The REPORT_CDIFF flag causes failures that involve multi-line expected
Tim Peters8485b562004-08-04 18:46:34 +00001298and actual outputs to be displayed using a context diff:
1299
Edward Loper71f55af2004-08-26 01:41:51 +00001300 >>> # Reuse f() from the REPORT_UDIFF example, above.
Tim Peters8485b562004-08-04 18:46:34 +00001301 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001302 >>> flags = doctest.REPORT_CDIFF
Tim Peters8485b562004-08-04 18:46:34 +00001303 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001304 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001305 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001306 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001307 Failed example:
1308 print '\n'.join('abcdefg')
Edward Loper56629292004-08-26 01:31:56 +00001309 Differences (context diff with expected followed by actual):
Tim Peters8485b562004-08-04 18:46:34 +00001310 ***************
Tim Peterse7edcb82004-08-26 05:44:27 +00001311 *** 1,7 ****
Tim Peters8485b562004-08-04 18:46:34 +00001312 a
1313 ! B
1314 c
1315 d
1316 f
1317 g
1318 - h
Tim Peterse7edcb82004-08-26 05:44:27 +00001319 --- 1,7 ----
Tim Peters8485b562004-08-04 18:46:34 +00001320 a
1321 ! b
1322 c
1323 d
1324 + e
1325 f
1326 g
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001327 TestResults(failed=1, attempted=1)
Tim Petersc6cbab02004-08-22 19:43:28 +00001328
1329
Edward Loper71f55af2004-08-26 01:41:51 +00001330The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
Tim Petersc6cbab02004-08-22 19:43:28 +00001331used by the popular ndiff.py utility. This does intraline difference
1332marking, as well as interline differences.
1333
1334 >>> def f(x):
1335 ... r'''
1336 ... >>> print "a b c d e f g h i j k l m"
1337 ... a b c d e f g h i j k 1 m
1338 ... '''
1339 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001340 >>> flags = doctest.REPORT_NDIFF
Tim Petersc6cbab02004-08-22 19:43:28 +00001341 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001342 ... # doctest: +ELLIPSIS
Tim Petersc6cbab02004-08-22 19:43:28 +00001343 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001344 File ..., line 3, in f
Tim Petersc6cbab02004-08-22 19:43:28 +00001345 Failed example:
1346 print "a b c d e f g h i j k l m"
1347 Differences (ndiff with -expected +actual):
1348 - a b c d e f g h i j k 1 m
1349 ? ^
1350 + a b c d e f g h i j k l m
1351 ? + ++ ^
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001352 TestResults(failed=1, attempted=1)
Edward Lopera89f88d2004-08-26 02:45:51 +00001353
Ezio Melottic2077b02011-03-16 12:34:31 +02001354The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
Edward Lopera89f88d2004-08-26 02:45:51 +00001355failing example:
1356
1357 >>> def f(x):
1358 ... r'''
1359 ... >>> print 1 # first success
1360 ... 1
1361 ... >>> print 2 # first failure
1362 ... 200
1363 ... >>> print 3 # second failure
1364 ... 300
1365 ... >>> print 4 # second success
1366 ... 4
1367 ... >>> print 5 # third failure
1368 ... 500
1369 ... '''
1370 >>> test = doctest.DocTestFinder().find(f)[0]
1371 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1372 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001373 ... # doctest: +ELLIPSIS
Edward Lopera89f88d2004-08-26 02:45:51 +00001374 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001375 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001376 Failed example:
1377 print 2 # first failure
1378 Expected:
1379 200
1380 Got:
1381 2
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001382 TestResults(failed=3, attempted=5)
Edward Lopera89f88d2004-08-26 02:45:51 +00001383
Ezio Melottic2077b02011-03-16 12:34:31 +02001384However, output from `report_start` is not suppressed:
Edward Lopera89f88d2004-08-26 02:45:51 +00001385
1386 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001387 ... # doctest: +ELLIPSIS
Edward Lopera89f88d2004-08-26 02:45:51 +00001388 Trying:
1389 print 1 # first success
1390 Expecting:
1391 1
1392 ok
1393 Trying:
1394 print 2 # first failure
1395 Expecting:
1396 200
1397 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001398 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001399 Failed example:
1400 print 2 # first failure
1401 Expected:
1402 200
1403 Got:
1404 2
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001405 TestResults(failed=3, attempted=5)
Edward Lopera89f88d2004-08-26 02:45:51 +00001406
1407For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
1408count as failures:
1409
1410 >>> def f(x):
1411 ... r'''
1412 ... >>> print 1 # first success
1413 ... 1
1414 ... >>> raise ValueError(2) # first failure
1415 ... 200
1416 ... >>> print 3 # second failure
1417 ... 300
1418 ... >>> print 4 # second success
1419 ... 4
1420 ... >>> print 5 # third failure
1421 ... 500
1422 ... '''
1423 >>> test = doctest.DocTestFinder().find(f)[0]
1424 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1425 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1426 ... # doctest: +ELLIPSIS
1427 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001428 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001429 Failed example:
1430 raise ValueError(2) # first failure
1431 Exception raised:
1432 ...
1433 ValueError: 2
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001434 TestResults(failed=3, attempted=5)
Edward Lopera89f88d2004-08-26 02:45:51 +00001435
Tim Petersad2ef332006-05-10 02:43:01 +00001436New option flags can also be registered, via register_optionflag(). Here
1437we reach into doctest's internals a bit.
1438
1439 >>> unlikely = "UNLIKELY_OPTION_NAME"
1440 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1441 False
1442 >>> new_flag_value = doctest.register_optionflag(unlikely)
1443 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1444 True
1445
1446Before 2.4.4/2.5, registering a name more than once erroneously created
1447more than one flag value. Here we verify that's fixed:
1448
1449 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1450 >>> redundant_flag_value == new_flag_value
1451 True
1452
1453Clean up.
1454 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1455
Tim Petersc6cbab02004-08-22 19:43:28 +00001456 """
1457
Tim Peters8485b562004-08-04 18:46:34 +00001458 def option_directives(): r"""
1459Tests of `DocTestRunner`'s option directive mechanism.
1460
Edward Loper74bca7a2004-08-12 02:27:44 +00001461Option directives can be used to turn option flags on or off for a
1462single example. To turn an option on for an example, follow that
1463example with a comment of the form ``# doctest: +OPTION``:
Tim Peters8485b562004-08-04 18:46:34 +00001464
1465 >>> def f(x): r'''
Edward Loper74bca7a2004-08-12 02:27:44 +00001466 ... >>> print range(10) # should fail: no ellipsis
1467 ... [0, 1, ..., 9]
1468 ...
1469 ... >>> print range(10) # doctest: +ELLIPSIS
1470 ... [0, 1, ..., 9]
1471 ... '''
1472 >>> test = doctest.DocTestFinder().find(f)[0]
1473 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001474 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001475 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001476 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001477 Failed example:
1478 print range(10) # should fail: no ellipsis
1479 Expected:
1480 [0, 1, ..., 9]
1481 Got:
1482 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001483 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001484
1485To turn an option off for an example, follow that example with a
1486comment of the form ``# doctest: -OPTION``:
1487
1488 >>> def f(x): r'''
1489 ... >>> print range(10)
1490 ... [0, 1, ..., 9]
1491 ...
1492 ... >>> # should fail: no ellipsis
1493 ... >>> print range(10) # doctest: -ELLIPSIS
1494 ... [0, 1, ..., 9]
1495 ... '''
1496 >>> test = doctest.DocTestFinder().find(f)[0]
1497 >>> doctest.DocTestRunner(verbose=False,
1498 ... optionflags=doctest.ELLIPSIS).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001499 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001500 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001501 File ..., line 6, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001502 Failed example:
1503 print range(10) # doctest: -ELLIPSIS
1504 Expected:
1505 [0, 1, ..., 9]
1506 Got:
1507 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001508 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001509
1510Option directives affect only the example that they appear with; they
1511do not change the options for surrounding examples:
Edward Loper8e4a34b2004-08-12 02:34:27 +00001512
Edward Loper74bca7a2004-08-12 02:27:44 +00001513 >>> def f(x): r'''
Tim Peters8485b562004-08-04 18:46:34 +00001514 ... >>> print range(10) # Should fail: no ellipsis
1515 ... [0, 1, ..., 9]
1516 ...
Edward Loper74bca7a2004-08-12 02:27:44 +00001517 ... >>> print range(10) # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001518 ... [0, 1, ..., 9]
1519 ...
Tim Peters8485b562004-08-04 18:46:34 +00001520 ... >>> print range(10) # Should fail: no ellipsis
1521 ... [0, 1, ..., 9]
1522 ... '''
1523 >>> test = doctest.DocTestFinder().find(f)[0]
1524 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001525 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001526 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001527 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001528 Failed example:
1529 print range(10) # Should fail: no ellipsis
1530 Expected:
1531 [0, 1, ..., 9]
1532 Got:
1533 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Tim Peters8485b562004-08-04 18:46:34 +00001534 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001535 File ..., line 8, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001536 Failed example:
1537 print range(10) # Should fail: no ellipsis
1538 Expected:
1539 [0, 1, ..., 9]
1540 Got:
1541 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001542 TestResults(failed=2, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +00001543
Edward Loper74bca7a2004-08-12 02:27:44 +00001544Multiple options may be modified by a single option directive. They
1545may be separated by whitespace, commas, or both:
Tim Peters8485b562004-08-04 18:46:34 +00001546
1547 >>> def f(x): r'''
1548 ... >>> print range(10) # Should fail
1549 ... [0, 1, ..., 9]
Tim Peters8485b562004-08-04 18:46:34 +00001550 ... >>> print range(10) # Should succeed
Edward Loper74bca7a2004-08-12 02:27:44 +00001551 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001552 ... [0, 1, ..., 9]
1553 ... '''
1554 >>> test = doctest.DocTestFinder().find(f)[0]
1555 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001556 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001557 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001558 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001559 Failed example:
1560 print range(10) # Should fail
1561 Expected:
1562 [0, 1, ..., 9]
1563 Got:
1564 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001565 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001566
1567 >>> def f(x): r'''
1568 ... >>> print range(10) # Should fail
1569 ... [0, 1, ..., 9]
1570 ... >>> print range(10) # Should succeed
1571 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1572 ... [0, 1, ..., 9]
1573 ... '''
1574 >>> test = doctest.DocTestFinder().find(f)[0]
1575 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001576 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001577 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001578 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001579 Failed example:
1580 print range(10) # Should fail
1581 Expected:
1582 [0, 1, ..., 9]
1583 Got:
1584 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001585 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001586
1587 >>> def f(x): r'''
1588 ... >>> print range(10) # Should fail
1589 ... [0, 1, ..., 9]
1590 ... >>> print range(10) # Should succeed
1591 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1592 ... [0, 1, ..., 9]
1593 ... '''
1594 >>> test = doctest.DocTestFinder().find(f)[0]
1595 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001596 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001597 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001598 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001599 Failed example:
1600 print range(10) # Should fail
1601 Expected:
1602 [0, 1, ..., 9]
1603 Got:
1604 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001605 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001606
1607The option directive may be put on the line following the source, as
1608long as a continuation prompt is used:
1609
1610 >>> def f(x): r'''
1611 ... >>> print range(10)
1612 ... ... # doctest: +ELLIPSIS
1613 ... [0, 1, ..., 9]
1614 ... '''
1615 >>> test = doctest.DocTestFinder().find(f)[0]
1616 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001617 TestResults(failed=0, attempted=1)
Edward Loper8e4a34b2004-08-12 02:34:27 +00001618
Edward Loper74bca7a2004-08-12 02:27:44 +00001619For examples with multi-line source, the option directive may appear
1620at the end of any line:
1621
1622 >>> def f(x): r'''
1623 ... >>> for x in range(10): # doctest: +ELLIPSIS
1624 ... ... print x,
1625 ... 0 1 2 ... 9
1626 ...
1627 ... >>> for x in range(10):
1628 ... ... print x, # doctest: +ELLIPSIS
1629 ... 0 1 2 ... 9
1630 ... '''
1631 >>> test = doctest.DocTestFinder().find(f)[0]
1632 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001633 TestResults(failed=0, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001634
1635If more than one line of an example with multi-line source has an
1636option directive, then they are combined:
1637
1638 >>> def f(x): r'''
1639 ... Should fail (option directive not on the last line):
1640 ... >>> for x in range(10): # doctest: +ELLIPSIS
1641 ... ... print x, # doctest: +NORMALIZE_WHITESPACE
1642 ... 0 1 2...9
1643 ... '''
1644 >>> test = doctest.DocTestFinder().find(f)[0]
1645 >>> doctest.DocTestRunner(verbose=False).run(test)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001646 TestResults(failed=0, attempted=1)
Edward Loper74bca7a2004-08-12 02:27:44 +00001647
1648It is an error to have a comment of the form ``# doctest:`` that is
1649*not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1650``OPTION`` is an option that has been registered with
1651`register_option`:
1652
1653 >>> # Error: Option not registered
1654 >>> s = '>>> print 12 #doctest: +BADOPTION'
1655 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1656 Traceback (most recent call last):
1657 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1658
1659 >>> # Error: No + or - prefix
1660 >>> s = '>>> print 12 #doctest: ELLIPSIS'
1661 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1662 Traceback (most recent call last):
1663 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1664
1665It is an error to use an option directive on a line that contains no
1666source:
1667
1668 >>> s = '>>> # doctest: +ELLIPSIS'
1669 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1670 Traceback (most recent call last):
1671 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
Georg Brandl1f05e2e2010-08-01 08:22:05 +00001672
1673 """
1674
1675 def test_unicode_output(self): r"""
1676
1677Check that unicode output works:
1678
1679 >>> u'\xe9'
1680 u'\xe9'
1681
1682If we return unicode, SpoofOut's buf variable becomes automagically
1683converted to unicode. This means all subsequent output becomes converted
1684to unicode, and if the output contains non-ascii characters that failed.
1685It used to be that this state change carried on between tests, meaning
1686tests would fail if unicode has been output previously in the testrun.
1687This test tests that this is no longer so:
1688
1689 >>> print u'abc'
1690 abc
1691
1692And then return a string with non-ascii characters:
1693
1694 >>> print u'\xe9'.encode('utf-8')
1695 é
1696
1697 """
1698
Tim Peters8485b562004-08-04 18:46:34 +00001699
1700def test_testsource(): r"""
1701Unit tests for `testsource()`.
1702
1703The testsource() function takes a module and a name, finds the (first)
Tim Peters19397e52004-08-06 22:02:59 +00001704test with that name in that module, and converts it to a script. The
1705example code is converted to regular Python code. The surrounding
1706words and expected output are converted to comments:
Tim Peters8485b562004-08-04 18:46:34 +00001707
1708 >>> import test.test_doctest
1709 >>> name = 'test.test_doctest.sample_func'
1710 >>> print doctest.testsource(test.test_doctest, name)
Edward Lopera5db6002004-08-12 02:41:30 +00001711 # Blah blah
Tim Peters19397e52004-08-06 22:02:59 +00001712 #
Tim Peters8485b562004-08-04 18:46:34 +00001713 print sample_func(22)
1714 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001715 ## 44
Tim Peters19397e52004-08-06 22:02:59 +00001716 #
Edward Lopera5db6002004-08-12 02:41:30 +00001717 # Yee ha!
Georg Brandlecf93c72005-06-26 23:09:51 +00001718 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001719
1720 >>> name = 'test.test_doctest.SampleNewStyleClass'
1721 >>> print doctest.testsource(test.test_doctest, name)
1722 print '1\n2\n3'
1723 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001724 ## 1
1725 ## 2
1726 ## 3
Georg Brandlecf93c72005-06-26 23:09:51 +00001727 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001728
1729 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1730 >>> print doctest.testsource(test.test_doctest, name)
1731 print SampleClass.a_classmethod(10)
1732 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001733 ## 12
Tim Peters8485b562004-08-04 18:46:34 +00001734 print SampleClass(0).a_classmethod(10)
1735 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001736 ## 12
Georg Brandlecf93c72005-06-26 23:09:51 +00001737 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001738"""
1739
1740def test_debug(): r"""
1741
1742Create a docstring that we want to debug:
1743
1744 >>> s = '''
1745 ... >>> x = 12
1746 ... >>> print x
1747 ... 12
1748 ... '''
1749
1750Create some fake stdin input, to feed to the debugger:
1751
1752 >>> import tempfile
Tim Peters8485b562004-08-04 18:46:34 +00001753 >>> real_stdin = sys.stdin
Edward Loper2de91ba2004-08-27 02:07:46 +00001754 >>> sys.stdin = _FakeInput(['next', 'print x', 'continue'])
Tim Peters8485b562004-08-04 18:46:34 +00001755
1756Run the debugger on the docstring, and then restore sys.stdin.
1757
Edward Loper2de91ba2004-08-27 02:07:46 +00001758 >>> try: doctest.debug_src(s)
1759 ... finally: sys.stdin = real_stdin
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001760 > <string>(1)<module>()
Edward Loper2de91ba2004-08-27 02:07:46 +00001761 (Pdb) next
1762 12
Tim Peters8485b562004-08-04 18:46:34 +00001763 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001764 > <string>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001765 (Pdb) print x
1766 12
1767 (Pdb) continue
Tim Peters8485b562004-08-04 18:46:34 +00001768
1769"""
1770
Jim Fulton356fd192004-08-09 11:34:47 +00001771def test_pdb_set_trace():
Tim Peters50c6bdb2004-11-08 22:07:37 +00001772 """Using pdb.set_trace from a doctest.
Jim Fulton356fd192004-08-09 11:34:47 +00001773
Tim Peters413ced62004-08-09 15:43:47 +00001774 You can use pdb.set_trace from a doctest. To do so, you must
Jim Fulton356fd192004-08-09 11:34:47 +00001775 retrieve the set_trace function from the pdb module at the time
Tim Peters413ced62004-08-09 15:43:47 +00001776 you use it. The doctest module changes sys.stdout so that it can
1777 capture program output. It also temporarily replaces pdb.set_trace
1778 with a version that restores stdout. This is necessary for you to
Jim Fulton356fd192004-08-09 11:34:47 +00001779 see debugger output.
1780
1781 >>> doc = '''
1782 ... >>> x = 42
Florent Xicluna80800d32010-10-14 21:46:04 +00001783 ... >>> raise Exception('clé')
1784 ... Traceback (most recent call last):
1785 ... Exception: clé
Jim Fulton356fd192004-08-09 11:34:47 +00001786 ... >>> import pdb; pdb.set_trace()
1787 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +00001788 >>> parser = doctest.DocTestParser()
Florent Xiclunab67660f2010-10-14 21:10:45 +00001789 >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)
Jim Fulton356fd192004-08-09 11:34:47 +00001790 >>> runner = doctest.DocTestRunner(verbose=False)
1791
1792 To demonstrate this, we'll create a fake standard input that
1793 captures our debugger input:
1794
1795 >>> import tempfile
Edward Loper2de91ba2004-08-27 02:07:46 +00001796 >>> real_stdin = sys.stdin
1797 >>> sys.stdin = _FakeInput([
Jim Fulton356fd192004-08-09 11:34:47 +00001798 ... 'print x', # print data defined by the example
1799 ... 'continue', # stop debugging
Edward Loper2de91ba2004-08-27 02:07:46 +00001800 ... ''])
Jim Fulton356fd192004-08-09 11:34:47 +00001801
Edward Loper2de91ba2004-08-27 02:07:46 +00001802 >>> try: runner.run(test)
1803 ... finally: sys.stdin = real_stdin
Jim Fulton356fd192004-08-09 11:34:47 +00001804 --Return--
Florent Xicluna80800d32010-10-14 21:46:04 +00001805 > <doctest foo-bär@baz[2]>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001806 -> import pdb; pdb.set_trace()
1807 (Pdb) print x
1808 42
1809 (Pdb) continue
Florent Xicluna80800d32010-10-14 21:46:04 +00001810 TestResults(failed=0, attempted=3)
Jim Fulton356fd192004-08-09 11:34:47 +00001811
1812 You can also put pdb.set_trace in a function called from a test:
1813
1814 >>> def calls_set_trace():
1815 ... y=2
1816 ... import pdb; pdb.set_trace()
1817
1818 >>> doc = '''
1819 ... >>> x=1
1820 ... >>> calls_set_trace()
1821 ... '''
Florent Xiclunab67660f2010-10-14 21:10:45 +00001822 >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
Edward Loper2de91ba2004-08-27 02:07:46 +00001823 >>> real_stdin = sys.stdin
1824 >>> sys.stdin = _FakeInput([
Jim Fulton356fd192004-08-09 11:34:47 +00001825 ... 'print y', # print data defined in the function
1826 ... 'up', # out of function
1827 ... 'print x', # print data defined by the example
1828 ... 'continue', # stop debugging
Edward Loper2de91ba2004-08-27 02:07:46 +00001829 ... ''])
Jim Fulton356fd192004-08-09 11:34:47 +00001830
Tim Peters50c6bdb2004-11-08 22:07:37 +00001831 >>> try:
1832 ... runner.run(test)
1833 ... finally:
1834 ... sys.stdin = real_stdin
Jim Fulton356fd192004-08-09 11:34:47 +00001835 --Return--
Edward Loper2de91ba2004-08-27 02:07:46 +00001836 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
1837 -> import pdb; pdb.set_trace()
1838 (Pdb) print y
1839 2
1840 (Pdb) up
Florent Xiclunab67660f2010-10-14 21:10:45 +00001841 > <doctest foo-bär@baz[1]>(1)<module>()
Edward Loper2de91ba2004-08-27 02:07:46 +00001842 -> calls_set_trace()
1843 (Pdb) print x
1844 1
1845 (Pdb) continue
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001846 TestResults(failed=0, attempted=2)
Edward Loper2de91ba2004-08-27 02:07:46 +00001847
1848 During interactive debugging, source code is shown, even for
1849 doctest examples:
1850
1851 >>> doc = '''
1852 ... >>> def f(x):
1853 ... ... g(x*2)
1854 ... >>> def g(x):
1855 ... ... print x+3
1856 ... ... import pdb; pdb.set_trace()
1857 ... >>> f(3)
1858 ... '''
Florent Xiclunab67660f2010-10-14 21:10:45 +00001859 >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
Edward Loper2de91ba2004-08-27 02:07:46 +00001860 >>> real_stdin = sys.stdin
1861 >>> sys.stdin = _FakeInput([
1862 ... 'list', # list source from example 2
1863 ... 'next', # return from g()
1864 ... 'list', # list source from example 1
1865 ... 'next', # return from f()
1866 ... 'list', # list source from example 3
1867 ... 'continue', # stop debugging
1868 ... ''])
1869 >>> try: runner.run(test)
1870 ... finally: sys.stdin = real_stdin
1871 ... # doctest: +NORMALIZE_WHITESPACE
1872 --Return--
Florent Xiclunab67660f2010-10-14 21:10:45 +00001873 > <doctest foo-bär@baz[1]>(3)g()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001874 -> import pdb; pdb.set_trace()
1875 (Pdb) list
1876 1 def g(x):
1877 2 print x+3
1878 3 -> import pdb; pdb.set_trace()
1879 [EOF]
1880 (Pdb) next
1881 --Return--
Florent Xiclunab67660f2010-10-14 21:10:45 +00001882 > <doctest foo-bär@baz[0]>(2)f()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001883 -> g(x*2)
1884 (Pdb) list
1885 1 def f(x):
1886 2 -> g(x*2)
1887 [EOF]
1888 (Pdb) next
1889 --Return--
Florent Xiclunab67660f2010-10-14 21:10:45 +00001890 > <doctest foo-bär@baz[2]>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001891 -> f(3)
1892 (Pdb) list
1893 1 -> f(3)
1894 [EOF]
1895 (Pdb) continue
1896 **********************************************************************
Florent Xiclunab67660f2010-10-14 21:10:45 +00001897 File "foo-bär@baz.py", line 7, in foo-bär@baz
Edward Loper2de91ba2004-08-27 02:07:46 +00001898 Failed example:
1899 f(3)
1900 Expected nothing
1901 Got:
1902 9
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001903 TestResults(failed=1, attempted=3)
Jim Fulton356fd192004-08-09 11:34:47 +00001904 """
1905
Tim Peters50c6bdb2004-11-08 22:07:37 +00001906def test_pdb_set_trace_nested():
1907 """This illustrates more-demanding use of set_trace with nested functions.
1908
1909 >>> class C(object):
1910 ... def calls_set_trace(self):
1911 ... y = 1
1912 ... import pdb; pdb.set_trace()
1913 ... self.f1()
1914 ... y = 2
1915 ... def f1(self):
1916 ... x = 1
1917 ... self.f2()
1918 ... x = 2
1919 ... def f2(self):
1920 ... z = 1
1921 ... z = 2
1922
1923 >>> calls_set_trace = C().calls_set_trace
1924
1925 >>> doc = '''
1926 ... >>> a = 1
1927 ... >>> calls_set_trace()
1928 ... '''
1929 >>> parser = doctest.DocTestParser()
1930 >>> runner = doctest.DocTestRunner(verbose=False)
Florent Xiclunab67660f2010-10-14 21:10:45 +00001931 >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001932 >>> real_stdin = sys.stdin
1933 >>> sys.stdin = _FakeInput([
1934 ... 'print y', # print data defined in the function
1935 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print z',
1936 ... 'up', 'print x',
1937 ... 'up', 'print y',
1938 ... 'up', 'print foo',
1939 ... 'continue', # stop debugging
1940 ... ''])
1941
1942 >>> try:
1943 ... runner.run(test)
1944 ... finally:
1945 ... sys.stdin = real_stdin
1946 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1947 -> self.f1()
1948 (Pdb) print y
1949 1
1950 (Pdb) step
1951 --Call--
1952 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
1953 -> def f1(self):
1954 (Pdb) step
1955 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
1956 -> x = 1
1957 (Pdb) step
1958 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1959 -> self.f2()
1960 (Pdb) step
1961 --Call--
1962 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
1963 -> def f2(self):
1964 (Pdb) step
1965 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
1966 -> z = 1
1967 (Pdb) step
1968 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
1969 -> z = 2
1970 (Pdb) print z
1971 1
1972 (Pdb) up
1973 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1974 -> self.f2()
1975 (Pdb) print x
1976 1
1977 (Pdb) up
1978 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1979 -> self.f1()
1980 (Pdb) print y
1981 1
1982 (Pdb) up
Florent Xiclunab67660f2010-10-14 21:10:45 +00001983 > <doctest foo-bär@baz[1]>(1)<module>()
Tim Peters50c6bdb2004-11-08 22:07:37 +00001984 -> calls_set_trace()
1985 (Pdb) print foo
1986 *** NameError: name 'foo' is not defined
1987 (Pdb) continue
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00001988 TestResults(failed=0, attempted=2)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001989"""
1990
Tim Peters19397e52004-08-06 22:02:59 +00001991def test_DocTestSuite():
Tim Peters1e277ee2004-08-07 05:37:52 +00001992 """DocTestSuite creates a unittest test suite from a doctest.
Tim Peters19397e52004-08-06 22:02:59 +00001993
1994 We create a Suite by providing a module. A module can be provided
1995 by passing a module object:
1996
1997 >>> import unittest
1998 >>> import test.sample_doctest
1999 >>> suite = doctest.DocTestSuite(test.sample_doctest)
2000 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002001 <unittest.result.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00002002
2003 We can also supply the module by name:
2004
2005 >>> suite = doctest.DocTestSuite('test.sample_doctest')
2006 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002007 <unittest.result.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00002008
R David Murray8d580532012-09-10 10:17:13 -04002009 The module need not contain any doctest examples:
2010
2011 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_doctests')
2012 >>> suite.run(unittest.TestResult())
2013 <unittest.result.TestResult run=0 errors=0 failures=0>
2014
2015 However, if DocTestSuite finds no docstrings, it raises an error:
2016
2017 >>> try:
2018 ... doctest.DocTestSuite('test.sample_doctest_no_docstrings')
2019 ... except ValueError as e:
2020 ... error = e
2021
2022 >>> print(error.args[1])
2023 has no docstrings
2024
2025 You can prevent this error by passing a DocTestFinder instance with
2026 the `exclude_empty` keyword argument set to False:
2027
2028 >>> finder = doctest.DocTestFinder(exclude_empty=False)
2029 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings',
2030 ... test_finder=finder)
2031 >>> suite.run(unittest.TestResult())
2032 <unittest.result.TestResult run=0 errors=0 failures=0>
2033
Tim Peters19397e52004-08-06 22:02:59 +00002034 We can use the current module:
2035
2036 >>> suite = test.sample_doctest.test_suite()
2037 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002038 <unittest.result.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00002039
2040 We can supply global variables. If we pass globs, they will be
2041 used instead of the module globals. Here we'll pass an empty
2042 globals, triggering an extra error:
2043
2044 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
2045 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002046 <unittest.result.TestResult run=9 errors=0 failures=5>
Tim Peters19397e52004-08-06 22:02:59 +00002047
2048 Alternatively, we can provide extra globals. Here we'll make an
2049 error go away by providing an extra global variable:
2050
2051 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2052 ... extraglobs={'y': 1})
2053 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002054 <unittest.result.TestResult run=9 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00002055
2056 You can pass option flags. Here we'll cause an extra error
2057 by disabling the blank-line feature:
2058
2059 >>> suite = doctest.DocTestSuite('test.sample_doctest',
Tim Peters1e277ee2004-08-07 05:37:52 +00002060 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
Tim Peters19397e52004-08-06 22:02:59 +00002061 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002062 <unittest.result.TestResult run=9 errors=0 failures=5>
Tim Peters19397e52004-08-06 22:02:59 +00002063
Tim Peters1e277ee2004-08-07 05:37:52 +00002064 You can supply setUp and tearDown functions:
Tim Peters19397e52004-08-06 22:02:59 +00002065
Jim Fultonf54bad42004-08-28 14:57:56 +00002066 >>> def setUp(t):
Tim Peters19397e52004-08-06 22:02:59 +00002067 ... import test.test_doctest
2068 ... test.test_doctest.sillySetup = True
2069
Jim Fultonf54bad42004-08-28 14:57:56 +00002070 >>> def tearDown(t):
Tim Peters19397e52004-08-06 22:02:59 +00002071 ... import test.test_doctest
2072 ... del test.test_doctest.sillySetup
2073
2074 Here, we installed a silly variable that the test expects:
2075
2076 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2077 ... setUp=setUp, tearDown=tearDown)
2078 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002079 <unittest.result.TestResult run=9 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00002080
2081 But the tearDown restores sanity:
2082
2083 >>> import test.test_doctest
2084 >>> test.test_doctest.sillySetup
2085 Traceback (most recent call last):
2086 ...
2087 AttributeError: 'module' object has no attribute 'sillySetup'
2088
Jim Fultonf54bad42004-08-28 14:57:56 +00002089 The setUp and tearDown funtions are passed test objects. Here
2090 we'll use the setUp function to supply the missing variable y:
2091
2092 >>> def setUp(test):
2093 ... test.globs['y'] = 1
2094
2095 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
2096 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002097 <unittest.result.TestResult run=9 errors=0 failures=3>
Jim Fultonf54bad42004-08-28 14:57:56 +00002098
2099 Here, we didn't need to use a tearDown function because we
2100 modified the test globals, which are a copy of the
2101 sample_doctest module dictionary. The test globals are
2102 automatically cleared for us after a test.
Tim Peters19397e52004-08-06 22:02:59 +00002103 """
2104
2105def test_DocFileSuite():
2106 """We can test tests found in text files using a DocFileSuite.
2107
2108 We create a suite by providing the names of one or more text
2109 files that include examples:
2110
2111 >>> import unittest
2112 >>> suite = doctest.DocFileSuite('test_doctest.txt',
George Yoshidaf3c65de2006-05-28 16:39:09 +00002113 ... 'test_doctest2.txt',
2114 ... 'test_doctest4.txt')
Tim Peters19397e52004-08-06 22:02:59 +00002115 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002116 <unittest.result.TestResult run=3 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00002117
2118 The test files are looked for in the directory containing the
2119 calling module. A package keyword argument can be provided to
2120 specify a different relative location.
2121
2122 >>> import unittest
2123 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2124 ... 'test_doctest2.txt',
George Yoshidaf3c65de2006-05-28 16:39:09 +00002125 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00002126 ... package='test')
2127 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002128 <unittest.result.TestResult run=3 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00002129
Brett Cannon43e53f82007-11-21 00:47:36 +00002130 Support for using a package's __loader__.get_data() is also
2131 provided.
2132
2133 >>> import unittest, pkgutil, test
Brett Cannoneaa2c982007-11-23 00:06:51 +00002134 >>> added_loader = False
Brett Cannon43e53f82007-11-21 00:47:36 +00002135 >>> if not hasattr(test, '__loader__'):
2136 ... test.__loader__ = pkgutil.get_loader(test)
2137 ... added_loader = True
2138 >>> try:
2139 ... suite = doctest.DocFileSuite('test_doctest.txt',
2140 ... 'test_doctest2.txt',
2141 ... 'test_doctest4.txt',
2142 ... package='test')
2143 ... suite.run(unittest.TestResult())
2144 ... finally:
Brett Cannon9db1d5a2007-11-21 00:58:03 +00002145 ... if added_loader:
2146 ... del test.__loader__
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002147 <unittest.result.TestResult run=3 errors=0 failures=3>
Brett Cannon43e53f82007-11-21 00:47:36 +00002148
Edward Loper0273f5b2004-09-18 20:27:04 +00002149 '/' should be used as a path separator. It will be converted
2150 to a native separator at run time:
Tim Peters19397e52004-08-06 22:02:59 +00002151
2152 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2153 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002154 <unittest.result.TestResult run=1 errors=0 failures=1>
Tim Peters19397e52004-08-06 22:02:59 +00002155
Edward Loper0273f5b2004-09-18 20:27:04 +00002156 If DocFileSuite is used from an interactive session, then files
2157 are resolved relative to the directory of sys.argv[0]:
2158
Christian Heimesc756d002007-11-27 21:34:01 +00002159 >>> import types, os.path, test.test_doctest
Edward Loper0273f5b2004-09-18 20:27:04 +00002160 >>> save_argv = sys.argv
2161 >>> sys.argv = [test.test_doctest.__file__]
2162 >>> suite = doctest.DocFileSuite('test_doctest.txt',
Christian Heimesc756d002007-11-27 21:34:01 +00002163 ... package=types.ModuleType('__main__'))
Edward Loper0273f5b2004-09-18 20:27:04 +00002164 >>> sys.argv = save_argv
2165
Edward Loper052d0cd2004-09-19 17:19:33 +00002166 By setting `module_relative=False`, os-specific paths may be
2167 used (including absolute paths and paths relative to the
2168 working directory):
Edward Loper0273f5b2004-09-18 20:27:04 +00002169
2170 >>> # Get the absolute path of the test package.
2171 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2172 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
2173
2174 >>> # Use it to find the absolute path of test_doctest.txt.
2175 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2176
Edward Loper052d0cd2004-09-19 17:19:33 +00002177 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
Edward Loper0273f5b2004-09-18 20:27:04 +00002178 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002179 <unittest.result.TestResult run=1 errors=0 failures=1>
Edward Loper0273f5b2004-09-18 20:27:04 +00002180
Edward Loper052d0cd2004-09-19 17:19:33 +00002181 It is an error to specify `package` when `module_relative=False`:
2182
2183 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2184 ... package='test')
2185 Traceback (most recent call last):
2186 ValueError: Package may only be specified for module-relative paths.
2187
Tim Peters19397e52004-08-06 22:02:59 +00002188 You can specify initial global variables:
2189
2190 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2191 ... 'test_doctest2.txt',
George Yoshidaf3c65de2006-05-28 16:39:09 +00002192 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00002193 ... globs={'favorite_color': 'blue'})
2194 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002195 <unittest.result.TestResult run=3 errors=0 failures=2>
Tim Peters19397e52004-08-06 22:02:59 +00002196
2197 In this case, we supplied a missing favorite color. You can
2198 provide doctest options:
2199
2200 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2201 ... 'test_doctest2.txt',
George Yoshidaf3c65de2006-05-28 16:39:09 +00002202 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00002203 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2204 ... globs={'favorite_color': 'blue'})
2205 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002206 <unittest.result.TestResult run=3 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00002207
2208 And, you can provide setUp and tearDown functions:
2209
Jim Fultonf54bad42004-08-28 14:57:56 +00002210 >>> def setUp(t):
Tim Peters19397e52004-08-06 22:02:59 +00002211 ... import test.test_doctest
2212 ... test.test_doctest.sillySetup = True
2213
Jim Fultonf54bad42004-08-28 14:57:56 +00002214 >>> def tearDown(t):
Tim Peters19397e52004-08-06 22:02:59 +00002215 ... import test.test_doctest
2216 ... del test.test_doctest.sillySetup
2217
2218 Here, we installed a silly variable that the test expects:
2219
2220 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2221 ... 'test_doctest2.txt',
George Yoshidaf3c65de2006-05-28 16:39:09 +00002222 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00002223 ... setUp=setUp, tearDown=tearDown)
2224 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002225 <unittest.result.TestResult run=3 errors=0 failures=2>
Tim Peters19397e52004-08-06 22:02:59 +00002226
2227 But the tearDown restores sanity:
2228
2229 >>> import test.test_doctest
2230 >>> test.test_doctest.sillySetup
2231 Traceback (most recent call last):
2232 ...
2233 AttributeError: 'module' object has no attribute 'sillySetup'
2234
Jim Fultonf54bad42004-08-28 14:57:56 +00002235 The setUp and tearDown funtions are passed test objects.
2236 Here, we'll use a setUp function to set the favorite color in
2237 test_doctest.txt:
2238
2239 >>> def setUp(test):
2240 ... test.globs['favorite_color'] = 'blue'
2241
2242 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2243 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002244 <unittest.result.TestResult run=1 errors=0 failures=0>
Jim Fultonf54bad42004-08-28 14:57:56 +00002245
2246 Here, we didn't need to use a tearDown function because we
2247 modified the test globals. The test globals are
2248 automatically cleared for us after a test.
Tim Petersdf7a2082004-08-29 00:38:17 +00002249
Fred Drake7c404a42004-12-21 23:46:34 +00002250 Tests in a file run using `DocFileSuite` can also access the
2251 `__file__` global, which is set to the name of the file
2252 containing the tests:
2253
2254 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2255 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002256 <unittest.result.TestResult run=1 errors=0 failures=0>
Fred Drake7c404a42004-12-21 23:46:34 +00002257
George Yoshidaf3c65de2006-05-28 16:39:09 +00002258 If the tests contain non-ASCII characters, we have to specify which
2259 encoding the file is encoded with. We do so by using the `encoding`
2260 parameter:
2261
2262 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2263 ... 'test_doctest2.txt',
2264 ... 'test_doctest4.txt',
2265 ... encoding='utf-8')
2266 >>> suite.run(unittest.TestResult())
Benjamin Petersond7b0eeb2009-07-19 20:18:21 +00002267 <unittest.result.TestResult run=3 errors=0 failures=2>
George Yoshidaf3c65de2006-05-28 16:39:09 +00002268
Jim Fultonf54bad42004-08-28 14:57:56 +00002269 """
Tim Peters19397e52004-08-06 22:02:59 +00002270
Jim Fulton07a349c2004-08-22 14:10:00 +00002271def test_trailing_space_in_test():
2272 """
Tim Petersa7def722004-08-23 22:13:22 +00002273 Trailing spaces in expected output are significant:
Tim Petersc6cbab02004-08-22 19:43:28 +00002274
Jim Fulton07a349c2004-08-22 14:10:00 +00002275 >>> x, y = 'foo', ''
2276 >>> print x, y
2277 foo \n
2278 """
Tim Peters19397e52004-08-06 22:02:59 +00002279
Jim Fultonf54bad42004-08-28 14:57:56 +00002280
2281def test_unittest_reportflags():
2282 """Default unittest reporting flags can be set to control reporting
2283
2284 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2285 only the first failure of each test. First, we'll look at the
2286 output without the flag. The file test_doctest.txt file has two
2287 tests. They both fail if blank lines are disabled:
2288
2289 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2290 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2291 >>> import unittest
2292 >>> result = suite.run(unittest.TestResult())
2293 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2294 Traceback ...
2295 Failed example:
2296 favorite_color
2297 ...
2298 Failed example:
2299 if 1:
2300 ...
2301
2302 Note that we see both failures displayed.
2303
2304 >>> old = doctest.set_unittest_reportflags(
2305 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2306
2307 Now, when we run the test:
2308
2309 >>> result = suite.run(unittest.TestResult())
2310 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2311 Traceback ...
2312 Failed example:
2313 favorite_color
2314 Exception raised:
2315 ...
2316 NameError: name 'favorite_color' is not defined
2317 <BLANKLINE>
2318 <BLANKLINE>
Tim Petersdf7a2082004-08-29 00:38:17 +00002319
Jim Fultonf54bad42004-08-28 14:57:56 +00002320 We get only the first failure.
2321
2322 If we give any reporting options when we set up the tests,
2323 however:
2324
2325 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2326 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2327
2328 Then the default eporting options are ignored:
2329
2330 >>> result = suite.run(unittest.TestResult())
2331 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2332 Traceback ...
2333 Failed example:
2334 favorite_color
2335 ...
2336 Failed example:
2337 if 1:
2338 print 'a'
2339 print
2340 print 'b'
2341 Differences (ndiff with -expected +actual):
2342 a
2343 - <BLANKLINE>
2344 +
2345 b
2346 <BLANKLINE>
2347 <BLANKLINE>
2348
2349
2350 Test runners can restore the formatting flags after they run:
2351
2352 >>> ignored = doctest.set_unittest_reportflags(old)
2353
2354 """
2355
Edward Loper052d0cd2004-09-19 17:19:33 +00002356def test_testfile(): r"""
2357Tests for the `testfile()` function. This function runs all the
2358doctest examples in a given file. In its simple invokation, it is
2359called with the name of a file, which is taken to be relative to the
2360calling module. The return value is (#failures, #tests).
2361
Florent Xicluna2a903b22010-02-27 13:31:23 +00002362We don't want `-v` in sys.argv for these tests.
2363
2364 >>> save_argv = sys.argv
2365 >>> if '-v' in sys.argv:
2366 ... sys.argv = [arg for arg in save_argv if arg != '-v']
2367
2368
Edward Loper052d0cd2004-09-19 17:19:33 +00002369 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2370 **********************************************************************
2371 File "...", line 6, in test_doctest.txt
2372 Failed example:
2373 favorite_color
2374 Exception raised:
2375 ...
2376 NameError: name 'favorite_color' is not defined
2377 **********************************************************************
2378 1 items had failures:
2379 1 of 2 in test_doctest.txt
2380 ***Test Failed*** 1 failures.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002381 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002382 >>> doctest.master = None # Reset master.
2383
2384(Note: we'll be clearing doctest.master after each call to
Florent Xicluna07627882010-03-21 01:14:24 +00002385`doctest.testfile`, to suppress warnings about multiple tests with the
Edward Loper052d0cd2004-09-19 17:19:33 +00002386same name.)
2387
2388Globals may be specified with the `globs` and `extraglobs` parameters:
2389
2390 >>> globs = {'favorite_color': 'blue'}
2391 >>> doctest.testfile('test_doctest.txt', globs=globs)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002392 TestResults(failed=0, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002393 >>> doctest.master = None # Reset master.
2394
2395 >>> extraglobs = {'favorite_color': 'red'}
2396 >>> doctest.testfile('test_doctest.txt', globs=globs,
2397 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2398 **********************************************************************
2399 File "...", line 6, in test_doctest.txt
2400 Failed example:
2401 favorite_color
2402 Expected:
2403 'blue'
2404 Got:
2405 'red'
2406 **********************************************************************
2407 1 items had failures:
2408 1 of 2 in test_doctest.txt
2409 ***Test Failed*** 1 failures.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002410 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002411 >>> doctest.master = None # Reset master.
2412
2413The file may be made relative to a given module or package, using the
2414optional `module_relative` parameter:
2415
2416 >>> doctest.testfile('test_doctest.txt', globs=globs,
2417 ... module_relative='test')
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002418 TestResults(failed=0, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002419 >>> doctest.master = None # Reset master.
2420
Ezio Melottic2077b02011-03-16 12:34:31 +02002421Verbosity can be increased with the optional `verbose` parameter:
Edward Loper052d0cd2004-09-19 17:19:33 +00002422
2423 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2424 Trying:
2425 favorite_color
2426 Expecting:
2427 'blue'
2428 ok
2429 Trying:
2430 if 1:
2431 print 'a'
2432 print
2433 print 'b'
2434 Expecting:
2435 a
2436 <BLANKLINE>
2437 b
2438 ok
2439 1 items passed all tests:
2440 2 tests in test_doctest.txt
2441 2 tests in 1 items.
2442 2 passed and 0 failed.
2443 Test passed.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002444 TestResults(failed=0, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002445 >>> doctest.master = None # Reset master.
2446
2447The name of the test may be specified with the optional `name`
2448parameter:
2449
2450 >>> doctest.testfile('test_doctest.txt', name='newname')
2451 ... # doctest: +ELLIPSIS
2452 **********************************************************************
2453 File "...", line 6, in newname
2454 ...
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002455 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002456 >>> doctest.master = None # Reset master.
2457
Ezio Melottic2077b02011-03-16 12:34:31 +02002458The summary report may be suppressed with the optional `report`
Edward Loper052d0cd2004-09-19 17:19:33 +00002459parameter:
2460
2461 >>> doctest.testfile('test_doctest.txt', report=False)
2462 ... # doctest: +ELLIPSIS
2463 **********************************************************************
2464 File "...", line 6, in test_doctest.txt
2465 Failed example:
2466 favorite_color
2467 Exception raised:
2468 ...
2469 NameError: name 'favorite_color' is not defined
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002470 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002471 >>> doctest.master = None # Reset master.
2472
2473The optional keyword argument `raise_on_error` can be used to raise an
2474exception on the first error (which may be useful for postmortem
2475debugging):
2476
2477 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2478 ... # doctest: +ELLIPSIS
2479 Traceback (most recent call last):
2480 UnexpectedException: ...
2481 >>> doctest.master = None # Reset master.
George Yoshidaf3c65de2006-05-28 16:39:09 +00002482
2483If the tests contain non-ASCII characters, the tests might fail, since
2484it's unknown which encoding is used. The encoding can be specified
2485using the optional keyword argument `encoding`:
2486
2487 >>> doctest.testfile('test_doctest4.txt') # doctest: +ELLIPSIS
2488 **********************************************************************
2489 File "...", line 7, in test_doctest4.txt
2490 Failed example:
2491 u'...'
2492 Expected:
2493 u'f\xf6\xf6'
2494 Got:
2495 u'f\xc3\xb6\xc3\xb6'
2496 **********************************************************************
2497 ...
2498 **********************************************************************
2499 1 items had failures:
2500 2 of 4 in test_doctest4.txt
2501 ***Test Failed*** 2 failures.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002502 TestResults(failed=2, attempted=4)
George Yoshidaf3c65de2006-05-28 16:39:09 +00002503 >>> doctest.master = None # Reset master.
2504
2505 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002506 TestResults(failed=0, attempted=4)
George Yoshidaf3c65de2006-05-28 16:39:09 +00002507 >>> doctest.master = None # Reset master.
Florent Xicluna2a903b22010-02-27 13:31:23 +00002508
2509Switch the module encoding to 'utf-8' to test the verbose output without
2510bothering with the current sys.stdout encoding.
2511
2512 >>> doctest._encoding, saved_encoding = 'utf-8', doctest._encoding
2513 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2514 Trying:
2515 u'föö'
2516 Expecting:
2517 u'f\xf6\xf6'
2518 ok
2519 Trying:
2520 u'bÄ…r'
2521 Expecting:
2522 u'b\u0105r'
2523 ok
2524 Trying:
2525 'föö'
2526 Expecting:
2527 'f\xc3\xb6\xc3\xb6'
2528 ok
2529 Trying:
2530 'bÄ…r'
2531 Expecting:
2532 'b\xc4\x85r'
2533 ok
2534 1 items passed all tests:
2535 4 tests in test_doctest4.txt
2536 4 tests in 1 items.
2537 4 passed and 0 failed.
2538 Test passed.
2539 TestResults(failed=0, attempted=4)
2540 >>> doctest._encoding = saved_encoding
2541 >>> doctest.master = None # Reset master.
2542 >>> sys.argv = save_argv
Edward Loper052d0cd2004-09-19 17:19:33 +00002543"""
2544
Tim Petersa7def722004-08-23 22:13:22 +00002545# old_test1, ... used to live in doctest.py, but cluttered it. Note
2546# that these use the deprecated doctest.Tester, so should go away (or
2547# be rewritten) someday.
2548
Tim Petersa7def722004-08-23 22:13:22 +00002549def old_test1(): r"""
2550>>> from doctest import Tester
2551>>> t = Tester(globs={'x': 42}, verbose=0)
2552>>> t.runstring(r'''
2553... >>> x = x * 2
2554... >>> print x
2555... 42
2556... ''', 'XYZ')
2557**********************************************************************
2558Line 3, in XYZ
2559Failed example:
2560 print x
2561Expected:
2562 42
2563Got:
2564 84
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002565TestResults(failed=1, attempted=2)
Tim Petersa7def722004-08-23 22:13:22 +00002566>>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002567TestResults(failed=0, attempted=2)
Tim Petersa7def722004-08-23 22:13:22 +00002568>>> t.summarize()
2569**********************************************************************
25701 items had failures:
2571 1 of 2 in XYZ
2572***Test Failed*** 1 failures.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002573TestResults(failed=1, attempted=4)
Tim Petersa7def722004-08-23 22:13:22 +00002574>>> t.summarize(verbose=1)
25751 items passed all tests:
2576 2 tests in example2
2577**********************************************************************
25781 items had failures:
2579 1 of 2 in XYZ
25804 tests in 2 items.
25813 passed and 1 failed.
2582***Test Failed*** 1 failures.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002583TestResults(failed=1, attempted=4)
Tim Petersa7def722004-08-23 22:13:22 +00002584"""
2585
2586def old_test2(): r"""
2587 >>> from doctest import Tester
2588 >>> t = Tester(globs={}, verbose=1)
2589 >>> test = r'''
2590 ... # just an example
2591 ... >>> x = 1 + 2
2592 ... >>> x
2593 ... 3
2594 ... '''
2595 >>> t.runstring(test, "Example")
2596 Running string Example
Edward Loperaacf0832004-08-26 01:19:50 +00002597 Trying:
2598 x = 1 + 2
2599 Expecting nothing
Tim Petersa7def722004-08-23 22:13:22 +00002600 ok
Edward Loperaacf0832004-08-26 01:19:50 +00002601 Trying:
2602 x
2603 Expecting:
2604 3
Tim Petersa7def722004-08-23 22:13:22 +00002605 ok
2606 0 of 2 examples failed in string Example
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002607 TestResults(failed=0, attempted=2)
Tim Petersa7def722004-08-23 22:13:22 +00002608"""
2609
2610def old_test3(): r"""
2611 >>> from doctest import Tester
2612 >>> t = Tester(globs={}, verbose=0)
2613 >>> def _f():
2614 ... '''Trivial docstring example.
2615 ... >>> assert 2 == 2
2616 ... '''
2617 ... return 32
2618 ...
2619 >>> t.rundoc(_f) # expect 0 failures in 1 example
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002620 TestResults(failed=0, attempted=1)
Tim Petersa7def722004-08-23 22:13:22 +00002621"""
2622
2623def old_test4(): """
Christian Heimesc756d002007-11-27 21:34:01 +00002624 >>> import types
2625 >>> m1 = types.ModuleType('_m1')
2626 >>> m2 = types.ModuleType('_m2')
Tim Petersa7def722004-08-23 22:13:22 +00002627 >>> test_data = \"""
2628 ... def _f():
2629 ... '''>>> assert 1 == 1
2630 ... '''
2631 ... def g():
2632 ... '''>>> assert 2 != 1
2633 ... '''
2634 ... class H:
2635 ... '''>>> assert 2 > 1
2636 ... '''
2637 ... def bar(self):
2638 ... '''>>> assert 1 < 2
2639 ... '''
2640 ... \"""
2641 >>> exec test_data in m1.__dict__
2642 >>> exec test_data in m2.__dict__
2643 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
2644
2645 Tests that objects outside m1 are excluded:
2646
2647 >>> from doctest import Tester
2648 >>> t = Tester(globs={}, verbose=0)
2649 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002650 TestResults(failed=0, attempted=4)
Tim Petersa7def722004-08-23 22:13:22 +00002651
2652 Once more, not excluding stuff outside m1:
2653
2654 >>> t = Tester(globs={}, verbose=0)
2655 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002656 TestResults(failed=0, attempted=8)
Tim Petersa7def722004-08-23 22:13:22 +00002657
2658 The exclusion of objects from outside the designated module is
2659 meant to be invoked automagically by testmod.
2660
2661 >>> doctest.testmod(m1, verbose=False)
Raymond Hettingerfff4e6e2008-01-11 01:25:54 +00002662 TestResults(failed=0, attempted=4)
Tim Petersa7def722004-08-23 22:13:22 +00002663"""
2664
Tim Peters8485b562004-08-04 18:46:34 +00002665######################################################################
2666## Main
2667######################################################################
2668
2669def test_main():
2670 # Check the doctest cases in doctest itself:
2671 test_support.run_doctest(doctest, verbosity=True)
Florent Xicluna07627882010-03-21 01:14:24 +00002672
Tim Peters8485b562004-08-04 18:46:34 +00002673 from test import test_doctest
Florent Xicluna6257a7b2010-03-31 22:01:03 +00002674
2675 # Ignore all warnings about the use of class Tester in this module.
Benjamin Petersonca01a762012-10-15 20:38:21 -04002676 deprecations = []
2677 if __debug__:
2678 deprecations.append(("class Tester is deprecated", DeprecationWarning))
Florent Xicluna6257a7b2010-03-31 22:01:03 +00002679 if sys.py3kwarning:
2680 deprecations += [("backquote not supported", SyntaxWarning),
2681 ("execfile.. not supported", DeprecationWarning)]
2682 with test_support.check_warnings(*deprecations):
Florent Xicluna07627882010-03-21 01:14:24 +00002683 # Check the doctest cases defined here:
2684 test_support.run_doctest(test_doctest, verbosity=True)
Tim Peters8485b562004-08-04 18:46:34 +00002685
Victor Stinneredb9f872010-04-27 21:51:26 +00002686import sys
Tim Peters8485b562004-08-04 18:46:34 +00002687def test_coverage(coverdir):
Victor Stinneredb9f872010-04-27 21:51:26 +00002688 trace = test_support.import_module('trace')
Tim Peters8485b562004-08-04 18:46:34 +00002689 tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
2690 trace=0, count=1)
2691 tracer.run('reload(doctest); test_main()')
2692 r = tracer.results()
2693 print 'Writing coverage results...'
2694 r.write_results(show_missing=True, summary=True,
2695 coverdir=coverdir)
2696
2697if __name__ == '__main__':
2698 if '-c' in sys.argv:
2699 test_coverage('/tmp/doctest.cover')
2700 else:
2701 test_main()