move sections
[python/dscho.git] / Lib / test / test_doctest.py
blob105106809c830fcdf20aaf19781fd1587cc1f60f
1 # -*- coding: utf-8 -*-
2 """
3 Test script for doctest.
4 """
6 import sys
7 from test import test_support
8 import doctest
10 # NOTE: There are some additional tests relating to interaction with
11 # zipimport in the test_zipimport_support test module.
13 ######################################################################
14 ## Sample Objects (used by test cases)
15 ######################################################################
17 def sample_func(v):
18 """
19 Blah blah
21 >>> print sample_func(22)
24 Yee ha!
25 """
26 return v+v
28 class SampleClass:
29 """
30 >>> print 1
33 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
34 >>>
35 ...
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
43 """
44 def __init__(self, val):
45 """
46 >>> print SampleClass(12).get()
48 """
49 self.val = val
51 def double(self):
52 """
53 >>> print SampleClass(12).double().get()
55 """
56 return SampleClass(self.val + self.val)
58 def get(self):
59 """
60 >>> print SampleClass(-5).get()
62 """
63 return self.val
65 def a_staticmethod(v):
66 """
67 >>> print SampleClass.a_staticmethod(10)
69 """
70 return v+1
71 a_staticmethod = staticmethod(a_staticmethod)
73 def a_classmethod(cls, v):
74 """
75 >>> print SampleClass.a_classmethod(10)
77 >>> print SampleClass(0).a_classmethod(10)
79 """
80 return v+2
81 a_classmethod = classmethod(a_classmethod)
83 a_property = property(get, doc="""
84 >>> print SampleClass(22).a_property
86 """)
88 class NestedClass:
89 """
90 >>> x = SampleClass.NestedClass(5)
91 >>> y = x.square()
92 >>> print y.get()
94 """
95 def __init__(self, val=0):
96 """
97 >>> print SampleClass.NestedClass().get()
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
106 class SampleNewStyleClass(object):
107 r"""
108 >>> print '1\n2\n3'
113 def __init__(self, val):
115 >>> print SampleNewStyleClass(12).get()
118 self.val = val
120 def double(self):
122 >>> print SampleNewStyleClass(12).double().get()
125 return SampleNewStyleClass(self.val + self.val)
127 def get(self):
129 >>> print SampleNewStyleClass(-5).get()
132 return self.val
134 ######################################################################
135 ## Fake stdin (for testing interactive debugging)
136 ######################################################################
138 class _FakeInput:
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.
145 def __init__(self, lines):
146 self.lines = lines
148 def readline(self):
149 line = self.lines.pop(0)
150 print line
151 return line+'\n'
153 ######################################################################
154 ## Test Cases
155 ######################################################################
157 def test_Example(): r"""
158 Unit tests for the `Example` class.
160 Example 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.
170 These attributes are set by the constructor. `source` and `want` are
171 required; the other attributes all have default values:
173 >>> 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, {})
178 The first three attributes (`source`, `want`, and `exc_msg`) may be
179 specified positionally; the remaining arguments should be specified as
180 keyword arguments:
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})
190 The constructor normalizes the `source` string to end in a newline:
192 Source spans a single line: no terminating newline.
193 >>> e = doctest.Example('print 1', '1\n')
194 >>> e.source, e.want
195 ('print 1\n', '1\n')
197 >>> e = doctest.Example('print 1\n', '1\n')
198 >>> e.source, e.want
199 ('print 1\n', '1\n')
201 Source spans multiple lines: require terminating newline.
202 >>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n')
203 >>> e.source, e.want
204 ('print 1;\nprint 2\n', '1\n2\n')
206 >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')
207 >>> e.source, e.want
208 ('print 1;\nprint 2\n', '1\n2\n')
210 Empty source string (which should never appear in real examples)
211 >>> e = doctest.Example('', '')
212 >>> e.source, e.want
213 ('\n', '')
215 The constructor normalizes the `want` string to end in a newline,
216 unless it's the empty string:
218 >>> e = doctest.Example('print 1', '1\n')
219 >>> e.source, e.want
220 ('print 1\n', '1\n')
222 >>> e = doctest.Example('print 1', '1')
223 >>> e.source, e.want
224 ('print 1\n', '1\n')
226 >>> e = doctest.Example('print', '')
227 >>> e.source, e.want
228 ('print\n', '')
230 The constructor normalizes the `exc_msg` string to end in a newline,
231 unless it's `None`:
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'
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'
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'
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'
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'
263 def test_DocTest(): r"""
264 Unit tests for the `DocTest` class.
266 DocTest is a collection of examples, extracted from a docstring, along
267 with information about where the docstring comes from (a name,
268 filename, and line number). The docstring is parsed by the `DocTest`
269 constructor:
271 >>> docstring = '''
272 ... >>> print 12
273 ... 12
275 ... Non-example text.
277 ... >>> print 'another\example'
278 ... another
279 ... example
280 ... '''
281 >>> globs = {} # globals to run the test in.
282 >>> parser = doctest.DocTestParser()
283 >>> test = parser.get_doctest(docstring, globs, 'some_test',
284 ... 'some_file', 20)
285 >>> print test
286 <DocTest some_test from some_file:20 (2 examples)>
287 >>> len(test.examples)
289 >>> e1, e2 = test.examples
290 >>> (e1.source, e1.want, e1.lineno)
291 ('print 12\n', '12\n', 1)
292 >>> (e2.source, e2.want, e2.lineno)
293 ("print 'another\\example'\n", 'another\nexample\n', 6)
295 Source information (name, filename, and line number) is available as
296 attributes on the doctest object:
298 >>> (test.name, test.filename, test.lineno)
299 ('some_test', 'some_file', 20)
301 The line number of an example within its containing file is found by
302 adding the line number of the example and the line number of its
303 containing test:
305 >>> test.lineno + e1.lineno
307 >>> test.lineno + e2.lineno
310 If the docstring contains inconsistant leading whitespace in the
311 expected output of an example, then `DocTest` will raise a ValueError:
313 >>> docstring = r'''
314 ... >>> print 'bad\nindentation'
315 ... bad
316 ... indentation
317 ... '''
318 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
319 Traceback (most recent call last):
320 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
322 If the docstring contains inconsistent leading whitespace on
323 continuation lines, then `DocTest` will raise a ValueError:
325 >>> docstring = r'''
326 ... >>> print ('bad indentation',
327 ... ... 2)
328 ... ('bad', 'indentation')
329 ... '''
330 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
331 Traceback (most recent call last):
332 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2)'
334 If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
335 will raise a ValueError:
337 >>> docstring = '>>>print 1\n1'
338 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
339 Traceback (most recent call last):
340 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1'
342 If there's no blank space after a PS2 prompt ('...'), then `DocTest`
343 will raise a ValueError:
345 >>> docstring = '>>> if 1:\n...print 1\n1'
346 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
347 Traceback (most recent call last):
348 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1'
352 def test_DocTestFinder(): r"""
353 Unit tests for the `DocTestFinder` class.
355 DocTestFinder is used to extract DocTests from an object's docstring
356 and the docstrings of its contained objects. It can be used with
357 modules, functions, classes, methods, staticmethods, classmethods, and
358 properties.
360 Finding Tests in Functions
361 ~~~~~~~~~~~~~~~~~~~~~~~~~~
362 For a function whose docstring contains examples, DocTestFinder.find()
363 will return a single test (for that function's docstring):
365 >>> finder = doctest.DocTestFinder()
367 We'll simulate a __file__ attr that ends in pyc:
369 >>> import test.test_doctest
370 >>> old = test.test_doctest.__file__
371 >>> test.test_doctest.__file__ = 'test_doctest.pyc'
373 >>> tests = finder.find(sample_func)
375 >>> print tests # doctest: +ELLIPSIS
376 [<DocTest sample_func from ...:17 (1 example)>]
378 The exact name depends on how test_doctest was invoked, so allow for
379 leading path components.
381 >>> tests[0].filename # doctest: +ELLIPSIS
382 '...test_doctest.py'
384 >>> test.test_doctest.__file__ = old
387 >>> e = tests[0].examples[0]
388 >>> (e.source, e.want, e.lineno)
389 ('print sample_func(22)\n', '44\n', 3)
391 By default, tests are created for objects with no docstring:
393 >>> def no_docstring(v):
394 ... pass
395 >>> finder.find(no_docstring)
398 However, the optional argument `exclude_empty` to the DocTestFinder
399 constructor can be used to exclude tests for objects with empty
400 docstrings:
402 >>> def no_docstring(v):
403 ... pass
404 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
405 >>> excl_empty_finder.find(no_docstring)
408 If the function has a docstring with no examples, then a test with no
409 examples is returned. (This lets `DocTestRunner` collect statistics
410 about which functions have no tests -- but is that useful? And should
411 an empty test also be created when there's no docstring?)
413 >>> def no_examples(v):
414 ... ''' no doctest examples '''
415 >>> finder.find(no_examples) # doctest: +ELLIPSIS
416 [<DocTest no_examples from ...:1 (no examples)>]
418 Finding Tests in Classes
419 ~~~~~~~~~~~~~~~~~~~~~~~~
420 For a class, DocTestFinder will create a test for the class's
421 docstring, and will recursively explore its contents, including
422 methods, classmethods, staticmethods, properties, and nested classes.
424 >>> finder = doctest.DocTestFinder()
425 >>> tests = finder.find(SampleClass)
426 >>> for t in tests:
427 ... print '%2s %s' % (len(t.examples), t.name)
428 3 SampleClass
429 3 SampleClass.NestedClass
430 1 SampleClass.NestedClass.__init__
431 1 SampleClass.__init__
432 2 SampleClass.a_classmethod
433 1 SampleClass.a_property
434 1 SampleClass.a_staticmethod
435 1 SampleClass.double
436 1 SampleClass.get
438 New-style classes are also supported:
440 >>> tests = finder.find(SampleNewStyleClass)
441 >>> for t in tests:
442 ... print '%2s %s' % (len(t.examples), t.name)
443 1 SampleNewStyleClass
444 1 SampleNewStyleClass.__init__
445 1 SampleNewStyleClass.double
446 1 SampleNewStyleClass.get
448 Finding Tests in Modules
449 ~~~~~~~~~~~~~~~~~~~~~~~~
450 For a module, DocTestFinder will create a test for the class's
451 docstring, and will recursively explore its contents, including
452 functions, classes, and the `__test__` dictionary, if it exists:
454 >>> # A module
455 >>> import types
456 >>> m = types.ModuleType('some_module')
457 >>> def triple(val):
458 ... '''
459 ... >>> print triple(11)
460 ... 33
461 ... '''
462 ... return val*3
463 >>> m.__dict__.update({
464 ... 'sample_func': sample_func,
465 ... 'SampleClass': SampleClass,
466 ... '__doc__': '''
467 ... Module docstring.
468 ... >>> print 'module'
469 ... module
470 ... ''',
471 ... '__test__': {
472 ... 'd': '>>> print 6\n6\n>>> print 7\n7\n',
473 ... 'c': triple}})
475 >>> finder = doctest.DocTestFinder()
476 >>> # Use module=test.test_doctest, to prevent doctest from
477 >>> # ignoring the objects since they weren't defined in m.
478 >>> import test.test_doctest
479 >>> tests = finder.find(m, module=test.test_doctest)
480 >>> for t in tests:
481 ... print '%2s %s' % (len(t.examples), t.name)
482 1 some_module
483 3 some_module.SampleClass
484 3 some_module.SampleClass.NestedClass
485 1 some_module.SampleClass.NestedClass.__init__
486 1 some_module.SampleClass.__init__
487 2 some_module.SampleClass.a_classmethod
488 1 some_module.SampleClass.a_property
489 1 some_module.SampleClass.a_staticmethod
490 1 some_module.SampleClass.double
491 1 some_module.SampleClass.get
492 1 some_module.__test__.c
493 2 some_module.__test__.d
494 1 some_module.sample_func
496 Duplicate Removal
497 ~~~~~~~~~~~~~~~~~
498 If a single object is listed twice (under different names), then tests
499 will only be generated for it once:
501 >>> from test import doctest_aliases
502 >>> assert doctest_aliases.TwoNames.f
503 >>> assert doctest_aliases.TwoNames.g
504 >>> tests = excl_empty_finder.find(doctest_aliases)
505 >>> print len(tests)
507 >>> print tests[0].name
508 test.doctest_aliases.TwoNames
510 TwoNames.f and TwoNames.g are bound to the same object.
511 We can't guess which will be found in doctest's traversal of
512 TwoNames.__dict__ first, so we have to allow for either.
514 >>> tests[1].name.split('.')[-1] in ['f', 'g']
515 True
517 Empty Tests
518 ~~~~~~~~~~~
519 By default, an object with no doctests doesn't create any tests:
521 >>> tests = doctest.DocTestFinder().find(SampleClass)
522 >>> for t in tests:
523 ... print '%2s %s' % (len(t.examples), t.name)
524 3 SampleClass
525 3 SampleClass.NestedClass
526 1 SampleClass.NestedClass.__init__
527 1 SampleClass.__init__
528 2 SampleClass.a_classmethod
529 1 SampleClass.a_property
530 1 SampleClass.a_staticmethod
531 1 SampleClass.double
532 1 SampleClass.get
534 By default, that excluded objects with no doctests. exclude_empty=False
535 tells it to include (empty) tests for objects with no doctests. This feature
536 is really to support backward compatibility in what doctest.master.summarize()
537 displays.
539 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
540 >>> for t in tests:
541 ... print '%2s %s' % (len(t.examples), t.name)
542 3 SampleClass
543 3 SampleClass.NestedClass
544 1 SampleClass.NestedClass.__init__
545 0 SampleClass.NestedClass.get
546 0 SampleClass.NestedClass.square
547 1 SampleClass.__init__
548 2 SampleClass.a_classmethod
549 1 SampleClass.a_property
550 1 SampleClass.a_staticmethod
551 1 SampleClass.double
552 1 SampleClass.get
554 Turning off Recursion
555 ~~~~~~~~~~~~~~~~~~~~~
556 DocTestFinder can be told not to look for tests in contained objects
557 using the `recurse` flag:
559 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
560 >>> for t in tests:
561 ... print '%2s %s' % (len(t.examples), t.name)
562 3 SampleClass
564 Line numbers
565 ~~~~~~~~~~~~
566 DocTestFinder finds the line number of each example:
568 >>> def f(x):
569 ... '''
570 ... >>> x = 12
572 ... some text
574 ... >>> # examples are not created for comments & bare prompts.
575 ... >>>
576 ... ...
578 ... >>> for x in range(10):
579 ... ... print x,
580 ... 0 1 2 3 4 5 6 7 8 9
581 ... >>> x//2
582 ... 6
583 ... '''
584 >>> test = doctest.DocTestFinder().find(f)[0]
585 >>> [e.lineno for e in test.examples]
586 [1, 9, 12]
589 def test_DocTestParser(): r"""
590 Unit tests for the `DocTestParser` class.
592 DocTestParser is used to parse docstrings containing doctest examples.
594 The `parse` method divides a docstring into examples and intervening
595 text:
597 >>> s = '''
598 ... >>> x, y = 2, 3 # no output expected
599 ... >>> if 1:
600 ... ... print x
601 ... ... print y
602 ... 2
603 ... 3
605 ... Some text.
606 ... >>> x+y
607 ... 5
608 ... '''
609 >>> parser = doctest.DocTestParser()
610 >>> for piece in parser.parse(s):
611 ... if isinstance(piece, doctest.Example):
612 ... print 'Example:', (piece.source, piece.want, piece.lineno)
613 ... else:
614 ... print ' Text:', `piece`
615 Text: '\n'
616 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
617 Text: ''
618 Example: ('if 1:\n print x\n print y\n', '2\n3\n', 2)
619 Text: '\nSome text.\n'
620 Example: ('x+y\n', '5\n', 9)
621 Text: ''
623 The `get_examples` method returns just the examples:
625 >>> for piece in parser.get_examples(s):
626 ... print (piece.source, piece.want, piece.lineno)
627 ('x, y = 2, 3 # no output expected\n', '', 1)
628 ('if 1:\n print x\n print y\n', '2\n3\n', 2)
629 ('x+y\n', '5\n', 9)
631 The `get_doctest` method creates a Test from the examples, along with the
632 given arguments:
634 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
635 >>> (test.name, test.filename, test.lineno)
636 ('name', 'filename', 5)
637 >>> for piece in test.examples:
638 ... print (piece.source, piece.want, piece.lineno)
639 ('x, y = 2, 3 # no output expected\n', '', 1)
640 ('if 1:\n print x\n print y\n', '2\n3\n', 2)
641 ('x+y\n', '5\n', 9)
644 class test_DocTestRunner:
645 def basics(): r"""
646 Unit tests for the `DocTestRunner` class.
648 DocTestRunner is used to run DocTest test cases, and to accumulate
649 statistics. Here's a simple DocTest case we can use:
651 >>> def f(x):
652 ... '''
653 ... >>> x = 12
654 ... >>> print x
655 ... 12
656 ... >>> x//2
657 ... 6
658 ... '''
659 >>> test = doctest.DocTestFinder().find(f)[0]
661 The main DocTestRunner interface is the `run` method, which runs a
662 given DocTest case in a given namespace (globs). It returns a tuple
663 `(f,t)`, where `f` is the number of failed tests and `t` is the number
664 of tried tests.
666 >>> doctest.DocTestRunner(verbose=False).run(test)
667 TestResults(failed=0, attempted=3)
669 If any example produces incorrect output, then the test runner reports
670 the failure and proceeds to the next example:
672 >>> def f(x):
673 ... '''
674 ... >>> x = 12
675 ... >>> print x
676 ... 14
677 ... >>> x//2
678 ... 6
679 ... '''
680 >>> test = doctest.DocTestFinder().find(f)[0]
681 >>> doctest.DocTestRunner(verbose=True).run(test)
682 ... # doctest: +ELLIPSIS
683 Trying:
684 x = 12
685 Expecting nothing
687 Trying:
688 print x
689 Expecting:
691 **********************************************************************
692 File ..., line 4, in f
693 Failed example:
694 print x
695 Expected:
697 Got:
699 Trying:
700 x//2
701 Expecting:
704 TestResults(failed=1, attempted=3)
706 def verbose_flag(): r"""
707 The `verbose` flag makes the test runner generate more detailed
708 output:
710 >>> def f(x):
711 ... '''
712 ... >>> x = 12
713 ... >>> print x
714 ... 12
715 ... >>> x//2
716 ... 6
717 ... '''
718 >>> test = doctest.DocTestFinder().find(f)[0]
720 >>> doctest.DocTestRunner(verbose=True).run(test)
721 Trying:
722 x = 12
723 Expecting nothing
725 Trying:
726 print x
727 Expecting:
730 Trying:
731 x//2
732 Expecting:
735 TestResults(failed=0, attempted=3)
737 If the `verbose` flag is unspecified, then the output will be verbose
738 iff `-v` appears in sys.argv:
740 >>> # Save the real sys.argv list.
741 >>> old_argv = sys.argv
743 >>> # If -v does not appear in sys.argv, then output isn't verbose.
744 >>> sys.argv = ['test']
745 >>> doctest.DocTestRunner().run(test)
746 TestResults(failed=0, attempted=3)
748 >>> # If -v does appear in sys.argv, then output is verbose.
749 >>> sys.argv = ['test', '-v']
750 >>> doctest.DocTestRunner().run(test)
751 Trying:
752 x = 12
753 Expecting nothing
755 Trying:
756 print x
757 Expecting:
760 Trying:
761 x//2
762 Expecting:
765 TestResults(failed=0, attempted=3)
767 >>> # Restore sys.argv
768 >>> sys.argv = old_argv
770 In the remaining examples, the test runner's verbosity will be
771 explicitly set, to ensure that the test behavior is consistent.
773 def exceptions(): r"""
774 Tests of `DocTestRunner`'s exception handling.
776 An expected exception is specified with a traceback message. The
777 lines between the first line and the type/value may be omitted or
778 replaced with any other string:
780 >>> def f(x):
781 ... '''
782 ... >>> x = 12
783 ... >>> print x//0
784 ... Traceback (most recent call last):
785 ... ZeroDivisionError: integer division or modulo by zero
786 ... '''
787 >>> test = doctest.DocTestFinder().find(f)[0]
788 >>> doctest.DocTestRunner(verbose=False).run(test)
789 TestResults(failed=0, attempted=2)
791 An example may not generate output before it raises an exception; if
792 it does, then the traceback message will not be recognized as
793 signaling an expected exception, so the example will be reported as an
794 unexpected exception:
796 >>> def f(x):
797 ... '''
798 ... >>> x = 12
799 ... >>> print 'pre-exception output', x//0
800 ... pre-exception output
801 ... Traceback (most recent call last):
802 ... ZeroDivisionError: integer division or modulo by zero
803 ... '''
804 >>> test = doctest.DocTestFinder().find(f)[0]
805 >>> doctest.DocTestRunner(verbose=False).run(test)
806 ... # doctest: +ELLIPSIS
807 **********************************************************************
808 File ..., line 4, in f
809 Failed example:
810 print 'pre-exception output', x//0
811 Exception raised:
813 ZeroDivisionError: integer division or modulo by zero
814 TestResults(failed=1, attempted=2)
816 Exception messages may contain newlines:
818 >>> def f(x):
819 ... r'''
820 ... >>> raise ValueError, 'multi\nline\nmessage'
821 ... Traceback (most recent call last):
822 ... ValueError: multi
823 ... line
824 ... message
825 ... '''
826 >>> test = doctest.DocTestFinder().find(f)[0]
827 >>> doctest.DocTestRunner(verbose=False).run(test)
828 TestResults(failed=0, attempted=1)
830 If an exception is expected, but an exception with the wrong type or
831 message is raised, then it is reported as a failure:
833 >>> def f(x):
834 ... r'''
835 ... >>> raise ValueError, 'message'
836 ... Traceback (most recent call last):
837 ... ValueError: wrong message
838 ... '''
839 >>> test = doctest.DocTestFinder().find(f)[0]
840 >>> doctest.DocTestRunner(verbose=False).run(test)
841 ... # doctest: +ELLIPSIS
842 **********************************************************************
843 File ..., line 3, in f
844 Failed example:
845 raise ValueError, 'message'
846 Expected:
847 Traceback (most recent call last):
848 ValueError: wrong message
849 Got:
850 Traceback (most recent call last):
852 ValueError: message
853 TestResults(failed=1, attempted=1)
855 However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
856 detail:
858 >>> def f(x):
859 ... r'''
860 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
861 ... Traceback (most recent call last):
862 ... ValueError: wrong message
863 ... '''
864 >>> test = doctest.DocTestFinder().find(f)[0]
865 >>> doctest.DocTestRunner(verbose=False).run(test)
866 TestResults(failed=0, attempted=1)
868 IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
869 between Python versions. For example, in Python 3.x, the module path of
870 the exception is in the output, but this will fail under Python 2:
872 >>> def f(x):
873 ... r'''
874 ... >>> from httplib import HTTPException
875 ... >>> raise HTTPException('message')
876 ... Traceback (most recent call last):
877 ... httplib.HTTPException: message
878 ... '''
879 >>> test = doctest.DocTestFinder().find(f)[0]
880 >>> doctest.DocTestRunner(verbose=False).run(test)
881 ... # doctest: +ELLIPSIS
882 **********************************************************************
883 File ..., line 4, in f
884 Failed example:
885 raise HTTPException('message')
886 Expected:
887 Traceback (most recent call last):
888 httplib.HTTPException: message
889 Got:
890 Traceback (most recent call last):
892 HTTPException: message
893 TestResults(failed=1, attempted=2)
895 But in Python 2 the module path is not included, an therefore a test must look
896 like the following test to succeed in Python 2. But that test will fail under
897 Python 3.
899 >>> def f(x):
900 ... r'''
901 ... >>> from httplib import HTTPException
902 ... >>> raise HTTPException('message')
903 ... Traceback (most recent call last):
904 ... HTTPException: message
905 ... '''
906 >>> test = doctest.DocTestFinder().find(f)[0]
907 >>> doctest.DocTestRunner(verbose=False).run(test)
908 TestResults(failed=0, attempted=2)
910 However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
911 (if any) will be ignored:
913 >>> def f(x):
914 ... r'''
915 ... >>> from httplib import HTTPException
916 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
917 ... Traceback (most recent call last):
918 ... HTTPException: message
919 ... '''
920 >>> test = doctest.DocTestFinder().find(f)[0]
921 >>> doctest.DocTestRunner(verbose=False).run(test)
922 TestResults(failed=0, attempted=2)
924 The module path will be completely ignored, so two different module paths will
925 still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
926 be used when exceptions have changed module.
928 >>> def f(x):
929 ... r'''
930 ... >>> from httplib import HTTPException
931 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
932 ... Traceback (most recent call last):
933 ... foo.bar.HTTPException: message
934 ... '''
935 >>> test = doctest.DocTestFinder().find(f)[0]
936 >>> doctest.DocTestRunner(verbose=False).run(test)
937 TestResults(failed=0, attempted=2)
939 But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
941 >>> def f(x):
942 ... r'''
943 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
944 ... Traceback (most recent call last):
945 ... TypeError: wrong type
946 ... '''
947 >>> test = doctest.DocTestFinder().find(f)[0]
948 >>> doctest.DocTestRunner(verbose=False).run(test)
949 ... # doctest: +ELLIPSIS
950 **********************************************************************
951 File ..., line 3, in f
952 Failed example:
953 raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
954 Expected:
955 Traceback (most recent call last):
956 TypeError: wrong type
957 Got:
958 Traceback (most recent call last):
960 ValueError: message
961 TestResults(failed=1, attempted=1)
963 If an exception is raised but not expected, then it is reported as an
964 unexpected exception:
966 >>> def f(x):
967 ... r'''
968 ... >>> 1//0
969 ... 0
970 ... '''
971 >>> test = doctest.DocTestFinder().find(f)[0]
972 >>> doctest.DocTestRunner(verbose=False).run(test)
973 ... # doctest: +ELLIPSIS
974 **********************************************************************
975 File ..., line 3, in f
976 Failed example:
977 1//0
978 Exception raised:
979 Traceback (most recent call last):
981 ZeroDivisionError: integer division or modulo by zero
982 TestResults(failed=1, attempted=1)
984 def optionflags(): r"""
985 Tests of `DocTestRunner`'s option flag handling.
987 Several option flags can be used to customize the behavior of the test
988 runner. These are defined as module constants in doctest, and passed
989 to the DocTestRunner constructor (multiple constants should be ORed
990 together).
992 The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
993 and 1/0:
995 >>> def f(x):
996 ... '>>> True\n1\n'
998 >>> # Without the flag:
999 >>> test = doctest.DocTestFinder().find(f)[0]
1000 >>> doctest.DocTestRunner(verbose=False).run(test)
1001 TestResults(failed=0, attempted=1)
1003 >>> # With the flag:
1004 >>> test = doctest.DocTestFinder().find(f)[0]
1005 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1006 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1007 ... # doctest: +ELLIPSIS
1008 **********************************************************************
1009 File ..., line 2, in f
1010 Failed example:
1011 True
1012 Expected:
1014 Got:
1015 True
1016 TestResults(failed=1, attempted=1)
1018 The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1019 and the '<BLANKLINE>' marker:
1021 >>> def f(x):
1022 ... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n'
1024 >>> # Without the flag:
1025 >>> test = doctest.DocTestFinder().find(f)[0]
1026 >>> doctest.DocTestRunner(verbose=False).run(test)
1027 TestResults(failed=0, attempted=1)
1029 >>> # With the flag:
1030 >>> test = doctest.DocTestFinder().find(f)[0]
1031 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
1032 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1033 ... # doctest: +ELLIPSIS
1034 **********************************************************************
1035 File ..., line 2, in f
1036 Failed example:
1037 print "a\n\nb"
1038 Expected:
1040 <BLANKLINE>
1042 Got:
1044 <BLANKLINE>
1046 TestResults(failed=1, attempted=1)
1048 The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1049 treated as equal:
1051 >>> def f(x):
1052 ... '>>> print 1, 2, 3\n 1 2\n 3'
1054 >>> # Without the flag:
1055 >>> test = doctest.DocTestFinder().find(f)[0]
1056 >>> doctest.DocTestRunner(verbose=False).run(test)
1057 ... # doctest: +ELLIPSIS
1058 **********************************************************************
1059 File ..., line 2, in f
1060 Failed example:
1061 print 1, 2, 3
1062 Expected:
1065 Got:
1066 1 2 3
1067 TestResults(failed=1, attempted=1)
1069 >>> # With the flag:
1070 >>> test = doctest.DocTestFinder().find(f)[0]
1071 >>> flags = doctest.NORMALIZE_WHITESPACE
1072 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1073 TestResults(failed=0, attempted=1)
1075 An example from the docs:
1076 >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
1077 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1078 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1080 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1081 output to match any substring in the actual output:
1083 >>> def f(x):
1084 ... '>>> print range(15)\n[0, 1, 2, ..., 14]\n'
1086 >>> # Without the flag:
1087 >>> test = doctest.DocTestFinder().find(f)[0]
1088 >>> doctest.DocTestRunner(verbose=False).run(test)
1089 ... # doctest: +ELLIPSIS
1090 **********************************************************************
1091 File ..., line 2, in f
1092 Failed example:
1093 print range(15)
1094 Expected:
1095 [0, 1, 2, ..., 14]
1096 Got:
1097 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1098 TestResults(failed=1, attempted=1)
1100 >>> # With the flag:
1101 >>> test = doctest.DocTestFinder().find(f)[0]
1102 >>> flags = doctest.ELLIPSIS
1103 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1104 TestResults(failed=0, attempted=1)
1106 ... also matches nothing:
1108 >>> for i in range(100):
1109 ... print i**2, #doctest: +ELLIPSIS
1110 0 1...4...9 16 ... 36 49 64 ... 9801
1112 ... can be surprising; e.g., this test passes:
1114 >>> for i in range(21): #doctest: +ELLIPSIS
1115 ... print i,
1116 0 1 2 ...1...2...0
1118 Examples from the docs:
1120 >>> print range(20) # doctest:+ELLIPSIS
1121 [0, 1, ..., 18, 19]
1123 >>> print range(20) # doctest: +ELLIPSIS
1124 ... # doctest: +NORMALIZE_WHITESPACE
1125 [0, 1, ..., 18, 19]
1127 The SKIP flag causes an example to be skipped entirely. I.e., the
1128 example is not run. It can be useful in contexts where doctest
1129 examples serve as both documentation and test cases, and an example
1130 should be included for documentation purposes, but should not be
1131 checked (e.g., because its output is random, or depends on resources
1132 which would be unavailable.) The SKIP flag can also be used for
1133 'commenting out' broken examples.
1135 >>> import unavailable_resource # doctest: +SKIP
1136 >>> unavailable_resource.do_something() # doctest: +SKIP
1137 >>> unavailable_resource.blow_up() # doctest: +SKIP
1138 Traceback (most recent call last):
1140 UncheckedBlowUpError: Nobody checks me.
1142 >>> import random
1143 >>> print random.random() # doctest: +SKIP
1144 0.721216923889
1146 The REPORT_UDIFF flag causes failures that involve multi-line expected
1147 and actual outputs to be displayed using a unified diff:
1149 >>> def f(x):
1150 ... r'''
1151 ... >>> print '\n'.join('abcdefg')
1152 ... a
1153 ... B
1154 ... c
1155 ... d
1156 ... f
1157 ... g
1158 ... h
1159 ... '''
1161 >>> # Without the flag:
1162 >>> test = doctest.DocTestFinder().find(f)[0]
1163 >>> doctest.DocTestRunner(verbose=False).run(test)
1164 ... # doctest: +ELLIPSIS
1165 **********************************************************************
1166 File ..., line 3, in f
1167 Failed example:
1168 print '\n'.join('abcdefg')
1169 Expected:
1177 Got:
1185 TestResults(failed=1, attempted=1)
1187 >>> # With the flag:
1188 >>> test = doctest.DocTestFinder().find(f)[0]
1189 >>> flags = doctest.REPORT_UDIFF
1190 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1191 ... # doctest: +ELLIPSIS
1192 **********************************************************************
1193 File ..., line 3, in f
1194 Failed example:
1195 print '\n'.join('abcdefg')
1196 Differences (unified diff with -expected +actual):
1197 @@ -1,7 +1,7 @@
1207 TestResults(failed=1, attempted=1)
1209 The REPORT_CDIFF flag causes failures that involve multi-line expected
1210 and actual outputs to be displayed using a context diff:
1212 >>> # Reuse f() from the REPORT_UDIFF example, above.
1213 >>> test = doctest.DocTestFinder().find(f)[0]
1214 >>> flags = doctest.REPORT_CDIFF
1215 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1216 ... # doctest: +ELLIPSIS
1217 **********************************************************************
1218 File ..., line 3, in f
1219 Failed example:
1220 print '\n'.join('abcdefg')
1221 Differences (context diff with expected followed by actual):
1222 ***************
1223 *** 1,7 ****
1231 --- 1,7 ----
1239 TestResults(failed=1, attempted=1)
1242 The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1243 used by the popular ndiff.py utility. This does intraline difference
1244 marking, as well as interline differences.
1246 >>> def f(x):
1247 ... r'''
1248 ... >>> print "a b c d e f g h i j k l m"
1249 ... a b c d e f g h i j k 1 m
1250 ... '''
1251 >>> test = doctest.DocTestFinder().find(f)[0]
1252 >>> flags = doctest.REPORT_NDIFF
1253 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1254 ... # doctest: +ELLIPSIS
1255 **********************************************************************
1256 File ..., line 3, in f
1257 Failed example:
1258 print "a b c d e f g h i j k l m"
1259 Differences (ndiff with -expected +actual):
1260 - a b c d e f g h i j k 1 m
1262 + a b c d e f g h i j k l m
1263 ? + ++ ^
1264 TestResults(failed=1, attempted=1)
1266 The REPORT_ONLY_FIRST_FAILURE supresses result output after the first
1267 failing example:
1269 >>> def f(x):
1270 ... r'''
1271 ... >>> print 1 # first success
1272 ... 1
1273 ... >>> print 2 # first failure
1274 ... 200
1275 ... >>> print 3 # second failure
1276 ... 300
1277 ... >>> print 4 # second success
1278 ... 4
1279 ... >>> print 5 # third failure
1280 ... 500
1281 ... '''
1282 >>> test = doctest.DocTestFinder().find(f)[0]
1283 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1284 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1285 ... # doctest: +ELLIPSIS
1286 **********************************************************************
1287 File ..., line 5, in f
1288 Failed example:
1289 print 2 # first failure
1290 Expected:
1292 Got:
1294 TestResults(failed=3, attempted=5)
1296 However, output from `report_start` is not supressed:
1298 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1299 ... # doctest: +ELLIPSIS
1300 Trying:
1301 print 1 # first success
1302 Expecting:
1305 Trying:
1306 print 2 # first failure
1307 Expecting:
1309 **********************************************************************
1310 File ..., line 5, in f
1311 Failed example:
1312 print 2 # first failure
1313 Expected:
1315 Got:
1317 TestResults(failed=3, attempted=5)
1319 For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
1320 count as failures:
1322 >>> def f(x):
1323 ... r'''
1324 ... >>> print 1 # first success
1325 ... 1
1326 ... >>> raise ValueError(2) # first failure
1327 ... 200
1328 ... >>> print 3 # second failure
1329 ... 300
1330 ... >>> print 4 # second success
1331 ... 4
1332 ... >>> print 5 # third failure
1333 ... 500
1334 ... '''
1335 >>> test = doctest.DocTestFinder().find(f)[0]
1336 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1337 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1338 ... # doctest: +ELLIPSIS
1339 **********************************************************************
1340 File ..., line 5, in f
1341 Failed example:
1342 raise ValueError(2) # first failure
1343 Exception raised:
1345 ValueError: 2
1346 TestResults(failed=3, attempted=5)
1348 New option flags can also be registered, via register_optionflag(). Here
1349 we reach into doctest's internals a bit.
1351 >>> unlikely = "UNLIKELY_OPTION_NAME"
1352 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1353 False
1354 >>> new_flag_value = doctest.register_optionflag(unlikely)
1355 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1356 True
1358 Before 2.4.4/2.5, registering a name more than once erroneously created
1359 more than one flag value. Here we verify that's fixed:
1361 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1362 >>> redundant_flag_value == new_flag_value
1363 True
1365 Clean up.
1366 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1370 def option_directives(): r"""
1371 Tests of `DocTestRunner`'s option directive mechanism.
1373 Option directives can be used to turn option flags on or off for a
1374 single example. To turn an option on for an example, follow that
1375 example with a comment of the form ``# doctest: +OPTION``:
1377 >>> def f(x): r'''
1378 ... >>> print range(10) # should fail: no ellipsis
1379 ... [0, 1, ..., 9]
1381 ... >>> print range(10) # doctest: +ELLIPSIS
1382 ... [0, 1, ..., 9]
1383 ... '''
1384 >>> test = doctest.DocTestFinder().find(f)[0]
1385 >>> doctest.DocTestRunner(verbose=False).run(test)
1386 ... # doctest: +ELLIPSIS
1387 **********************************************************************
1388 File ..., line 2, in f
1389 Failed example:
1390 print range(10) # should fail: no ellipsis
1391 Expected:
1392 [0, 1, ..., 9]
1393 Got:
1394 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1395 TestResults(failed=1, attempted=2)
1397 To turn an option off for an example, follow that example with a
1398 comment of the form ``# doctest: -OPTION``:
1400 >>> def f(x): r'''
1401 ... >>> print range(10)
1402 ... [0, 1, ..., 9]
1404 ... >>> # should fail: no ellipsis
1405 ... >>> print range(10) # doctest: -ELLIPSIS
1406 ... [0, 1, ..., 9]
1407 ... '''
1408 >>> test = doctest.DocTestFinder().find(f)[0]
1409 >>> doctest.DocTestRunner(verbose=False,
1410 ... optionflags=doctest.ELLIPSIS).run(test)
1411 ... # doctest: +ELLIPSIS
1412 **********************************************************************
1413 File ..., line 6, in f
1414 Failed example:
1415 print range(10) # doctest: -ELLIPSIS
1416 Expected:
1417 [0, 1, ..., 9]
1418 Got:
1419 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1420 TestResults(failed=1, attempted=2)
1422 Option directives affect only the example that they appear with; they
1423 do not change the options for surrounding examples:
1425 >>> def f(x): r'''
1426 ... >>> print range(10) # Should fail: no ellipsis
1427 ... [0, 1, ..., 9]
1429 ... >>> print range(10) # doctest: +ELLIPSIS
1430 ... [0, 1, ..., 9]
1432 ... >>> print range(10) # Should fail: no ellipsis
1433 ... [0, 1, ..., 9]
1434 ... '''
1435 >>> test = doctest.DocTestFinder().find(f)[0]
1436 >>> doctest.DocTestRunner(verbose=False).run(test)
1437 ... # doctest: +ELLIPSIS
1438 **********************************************************************
1439 File ..., line 2, in f
1440 Failed example:
1441 print range(10) # Should fail: no ellipsis
1442 Expected:
1443 [0, 1, ..., 9]
1444 Got:
1445 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1446 **********************************************************************
1447 File ..., line 8, in f
1448 Failed example:
1449 print range(10) # Should fail: no ellipsis
1450 Expected:
1451 [0, 1, ..., 9]
1452 Got:
1453 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1454 TestResults(failed=2, attempted=3)
1456 Multiple options may be modified by a single option directive. They
1457 may be separated by whitespace, commas, or both:
1459 >>> def f(x): r'''
1460 ... >>> print range(10) # Should fail
1461 ... [0, 1, ..., 9]
1462 ... >>> print range(10) # Should succeed
1463 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1464 ... [0, 1, ..., 9]
1465 ... '''
1466 >>> test = doctest.DocTestFinder().find(f)[0]
1467 >>> doctest.DocTestRunner(verbose=False).run(test)
1468 ... # doctest: +ELLIPSIS
1469 **********************************************************************
1470 File ..., line 2, in f
1471 Failed example:
1472 print range(10) # Should fail
1473 Expected:
1474 [0, 1, ..., 9]
1475 Got:
1476 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1477 TestResults(failed=1, attempted=2)
1479 >>> def f(x): r'''
1480 ... >>> print range(10) # Should fail
1481 ... [0, 1, ..., 9]
1482 ... >>> print range(10) # Should succeed
1483 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1484 ... [0, 1, ..., 9]
1485 ... '''
1486 >>> test = doctest.DocTestFinder().find(f)[0]
1487 >>> doctest.DocTestRunner(verbose=False).run(test)
1488 ... # doctest: +ELLIPSIS
1489 **********************************************************************
1490 File ..., line 2, in f
1491 Failed example:
1492 print range(10) # Should fail
1493 Expected:
1494 [0, 1, ..., 9]
1495 Got:
1496 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1497 TestResults(failed=1, attempted=2)
1499 >>> def f(x): r'''
1500 ... >>> print range(10) # Should fail
1501 ... [0, 1, ..., 9]
1502 ... >>> print range(10) # Should succeed
1503 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1504 ... [0, 1, ..., 9]
1505 ... '''
1506 >>> test = doctest.DocTestFinder().find(f)[0]
1507 >>> doctest.DocTestRunner(verbose=False).run(test)
1508 ... # doctest: +ELLIPSIS
1509 **********************************************************************
1510 File ..., line 2, in f
1511 Failed example:
1512 print range(10) # Should fail
1513 Expected:
1514 [0, 1, ..., 9]
1515 Got:
1516 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1517 TestResults(failed=1, attempted=2)
1519 The option directive may be put on the line following the source, as
1520 long as a continuation prompt is used:
1522 >>> def f(x): r'''
1523 ... >>> print range(10)
1524 ... ... # doctest: +ELLIPSIS
1525 ... [0, 1, ..., 9]
1526 ... '''
1527 >>> test = doctest.DocTestFinder().find(f)[0]
1528 >>> doctest.DocTestRunner(verbose=False).run(test)
1529 TestResults(failed=0, attempted=1)
1531 For examples with multi-line source, the option directive may appear
1532 at the end of any line:
1534 >>> def f(x): r'''
1535 ... >>> for x in range(10): # doctest: +ELLIPSIS
1536 ... ... print x,
1537 ... 0 1 2 ... 9
1539 ... >>> for x in range(10):
1540 ... ... print x, # doctest: +ELLIPSIS
1541 ... 0 1 2 ... 9
1542 ... '''
1543 >>> test = doctest.DocTestFinder().find(f)[0]
1544 >>> doctest.DocTestRunner(verbose=False).run(test)
1545 TestResults(failed=0, attempted=2)
1547 If more than one line of an example with multi-line source has an
1548 option directive, then they are combined:
1550 >>> def f(x): r'''
1551 ... Should fail (option directive not on the last line):
1552 ... >>> for x in range(10): # doctest: +ELLIPSIS
1553 ... ... print x, # doctest: +NORMALIZE_WHITESPACE
1554 ... 0 1 2...9
1555 ... '''
1556 >>> test = doctest.DocTestFinder().find(f)[0]
1557 >>> doctest.DocTestRunner(verbose=False).run(test)
1558 TestResults(failed=0, attempted=1)
1560 It is an error to have a comment of the form ``# doctest:`` that is
1561 *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1562 ``OPTION`` is an option that has been registered with
1563 `register_option`:
1565 >>> # Error: Option not registered
1566 >>> s = '>>> print 12 #doctest: +BADOPTION'
1567 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1568 Traceback (most recent call last):
1569 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1571 >>> # Error: No + or - prefix
1572 >>> s = '>>> print 12 #doctest: ELLIPSIS'
1573 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1574 Traceback (most recent call last):
1575 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1577 It is an error to use an option directive on a line that contains no
1578 source:
1580 >>> s = '>>> # doctest: +ELLIPSIS'
1581 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1582 Traceback (most recent call last):
1583 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1586 def test_testsource(): r"""
1587 Unit tests for `testsource()`.
1589 The testsource() function takes a module and a name, finds the (first)
1590 test with that name in that module, and converts it to a script. The
1591 example code is converted to regular Python code. The surrounding
1592 words and expected output are converted to comments:
1594 >>> import test.test_doctest
1595 >>> name = 'test.test_doctest.sample_func'
1596 >>> print doctest.testsource(test.test_doctest, name)
1597 # Blah blah
1599 print sample_func(22)
1600 # Expected:
1601 ## 44
1603 # Yee ha!
1604 <BLANKLINE>
1606 >>> name = 'test.test_doctest.SampleNewStyleClass'
1607 >>> print doctest.testsource(test.test_doctest, name)
1608 print '1\n2\n3'
1609 # Expected:
1610 ## 1
1611 ## 2
1612 ## 3
1613 <BLANKLINE>
1615 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1616 >>> print doctest.testsource(test.test_doctest, name)
1617 print SampleClass.a_classmethod(10)
1618 # Expected:
1619 ## 12
1620 print SampleClass(0).a_classmethod(10)
1621 # Expected:
1622 ## 12
1623 <BLANKLINE>
1626 def test_debug(): r"""
1628 Create a docstring that we want to debug:
1630 >>> s = '''
1631 ... >>> x = 12
1632 ... >>> print x
1633 ... 12
1634 ... '''
1636 Create some fake stdin input, to feed to the debugger:
1638 >>> import tempfile
1639 >>> real_stdin = sys.stdin
1640 >>> sys.stdin = _FakeInput(['next', 'print x', 'continue'])
1642 Run the debugger on the docstring, and then restore sys.stdin.
1644 >>> try: doctest.debug_src(s)
1645 ... finally: sys.stdin = real_stdin
1646 > <string>(1)<module>()
1647 (Pdb) next
1649 --Return--
1650 > <string>(1)<module>()->None
1651 (Pdb) print x
1653 (Pdb) continue
1657 def test_pdb_set_trace():
1658 """Using pdb.set_trace from a doctest.
1660 You can use pdb.set_trace from a doctest. To do so, you must
1661 retrieve the set_trace function from the pdb module at the time
1662 you use it. The doctest module changes sys.stdout so that it can
1663 capture program output. It also temporarily replaces pdb.set_trace
1664 with a version that restores stdout. This is necessary for you to
1665 see debugger output.
1667 >>> doc = '''
1668 ... >>> x = 42
1669 ... >>> import pdb; pdb.set_trace()
1670 ... '''
1671 >>> parser = doctest.DocTestParser()
1672 >>> test = parser.get_doctest(doc, {}, "foo", "foo.py", 0)
1673 >>> runner = doctest.DocTestRunner(verbose=False)
1675 To demonstrate this, we'll create a fake standard input that
1676 captures our debugger input:
1678 >>> import tempfile
1679 >>> real_stdin = sys.stdin
1680 >>> sys.stdin = _FakeInput([
1681 ... 'print x', # print data defined by the example
1682 ... 'continue', # stop debugging
1683 ... ''])
1685 >>> try: runner.run(test)
1686 ... finally: sys.stdin = real_stdin
1687 --Return--
1688 > <doctest foo[1]>(1)<module>()->None
1689 -> import pdb; pdb.set_trace()
1690 (Pdb) print x
1692 (Pdb) continue
1693 TestResults(failed=0, attempted=2)
1695 You can also put pdb.set_trace in a function called from a test:
1697 >>> def calls_set_trace():
1698 ... y=2
1699 ... import pdb; pdb.set_trace()
1701 >>> doc = '''
1702 ... >>> x=1
1703 ... >>> calls_set_trace()
1704 ... '''
1705 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1706 >>> real_stdin = sys.stdin
1707 >>> sys.stdin = _FakeInput([
1708 ... 'print y', # print data defined in the function
1709 ... 'up', # out of function
1710 ... 'print x', # print data defined by the example
1711 ... 'continue', # stop debugging
1712 ... ''])
1714 >>> try:
1715 ... runner.run(test)
1716 ... finally:
1717 ... sys.stdin = real_stdin
1718 --Return--
1719 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
1720 -> import pdb; pdb.set_trace()
1721 (Pdb) print y
1723 (Pdb) up
1724 > <doctest foo[1]>(1)<module>()
1725 -> calls_set_trace()
1726 (Pdb) print x
1728 (Pdb) continue
1729 TestResults(failed=0, attempted=2)
1731 During interactive debugging, source code is shown, even for
1732 doctest examples:
1734 >>> doc = '''
1735 ... >>> def f(x):
1736 ... ... g(x*2)
1737 ... >>> def g(x):
1738 ... ... print x+3
1739 ... ... import pdb; pdb.set_trace()
1740 ... >>> f(3)
1741 ... '''
1742 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1743 >>> real_stdin = sys.stdin
1744 >>> sys.stdin = _FakeInput([
1745 ... 'list', # list source from example 2
1746 ... 'next', # return from g()
1747 ... 'list', # list source from example 1
1748 ... 'next', # return from f()
1749 ... 'list', # list source from example 3
1750 ... 'continue', # stop debugging
1751 ... ''])
1752 >>> try: runner.run(test)
1753 ... finally: sys.stdin = real_stdin
1754 ... # doctest: +NORMALIZE_WHITESPACE
1755 --Return--
1756 > <doctest foo[1]>(3)g()->None
1757 -> import pdb; pdb.set_trace()
1758 (Pdb) list
1759 1 def g(x):
1760 2 print x+3
1761 3 -> import pdb; pdb.set_trace()
1762 [EOF]
1763 (Pdb) next
1764 --Return--
1765 > <doctest foo[0]>(2)f()->None
1766 -> g(x*2)
1767 (Pdb) list
1768 1 def f(x):
1769 2 -> g(x*2)
1770 [EOF]
1771 (Pdb) next
1772 --Return--
1773 > <doctest foo[2]>(1)<module>()->None
1774 -> f(3)
1775 (Pdb) list
1776 1 -> f(3)
1777 [EOF]
1778 (Pdb) continue
1779 **********************************************************************
1780 File "foo.py", line 7, in foo
1781 Failed example:
1782 f(3)
1783 Expected nothing
1784 Got:
1786 TestResults(failed=1, attempted=3)
1789 def test_pdb_set_trace_nested():
1790 """This illustrates more-demanding use of set_trace with nested functions.
1792 >>> class C(object):
1793 ... def calls_set_trace(self):
1794 ... y = 1
1795 ... import pdb; pdb.set_trace()
1796 ... self.f1()
1797 ... y = 2
1798 ... def f1(self):
1799 ... x = 1
1800 ... self.f2()
1801 ... x = 2
1802 ... def f2(self):
1803 ... z = 1
1804 ... z = 2
1806 >>> calls_set_trace = C().calls_set_trace
1808 >>> doc = '''
1809 ... >>> a = 1
1810 ... >>> calls_set_trace()
1811 ... '''
1812 >>> parser = doctest.DocTestParser()
1813 >>> runner = doctest.DocTestRunner(verbose=False)
1814 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1815 >>> real_stdin = sys.stdin
1816 >>> sys.stdin = _FakeInput([
1817 ... 'print y', # print data defined in the function
1818 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print z',
1819 ... 'up', 'print x',
1820 ... 'up', 'print y',
1821 ... 'up', 'print foo',
1822 ... 'continue', # stop debugging
1823 ... ''])
1825 >>> try:
1826 ... runner.run(test)
1827 ... finally:
1828 ... sys.stdin = real_stdin
1829 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1830 -> self.f1()
1831 (Pdb) print y
1833 (Pdb) step
1834 --Call--
1835 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
1836 -> def f1(self):
1837 (Pdb) step
1838 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
1839 -> x = 1
1840 (Pdb) step
1841 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1842 -> self.f2()
1843 (Pdb) step
1844 --Call--
1845 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
1846 -> def f2(self):
1847 (Pdb) step
1848 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
1849 -> z = 1
1850 (Pdb) step
1851 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
1852 -> z = 2
1853 (Pdb) print z
1855 (Pdb) up
1856 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1857 -> self.f2()
1858 (Pdb) print x
1860 (Pdb) up
1861 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1862 -> self.f1()
1863 (Pdb) print y
1865 (Pdb) up
1866 > <doctest foo[1]>(1)<module>()
1867 -> calls_set_trace()
1868 (Pdb) print foo
1869 *** NameError: name 'foo' is not defined
1870 (Pdb) continue
1871 TestResults(failed=0, attempted=2)
1874 def test_DocTestSuite():
1875 """DocTestSuite creates a unittest test suite from a doctest.
1877 We create a Suite by providing a module. A module can be provided
1878 by passing a module object:
1880 >>> import unittest
1881 >>> import test.sample_doctest
1882 >>> suite = doctest.DocTestSuite(test.sample_doctest)
1883 >>> suite.run(unittest.TestResult())
1884 <unittest.result.TestResult run=9 errors=0 failures=4>
1886 We can also supply the module by name:
1888 >>> suite = doctest.DocTestSuite('test.sample_doctest')
1889 >>> suite.run(unittest.TestResult())
1890 <unittest.result.TestResult run=9 errors=0 failures=4>
1892 We can use the current module:
1894 >>> suite = test.sample_doctest.test_suite()
1895 >>> suite.run(unittest.TestResult())
1896 <unittest.result.TestResult run=9 errors=0 failures=4>
1898 We can supply global variables. If we pass globs, they will be
1899 used instead of the module globals. Here we'll pass an empty
1900 globals, triggering an extra error:
1902 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
1903 >>> suite.run(unittest.TestResult())
1904 <unittest.result.TestResult run=9 errors=0 failures=5>
1906 Alternatively, we can provide extra globals. Here we'll make an
1907 error go away by providing an extra global variable:
1909 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1910 ... extraglobs={'y': 1})
1911 >>> suite.run(unittest.TestResult())
1912 <unittest.result.TestResult run=9 errors=0 failures=3>
1914 You can pass option flags. Here we'll cause an extra error
1915 by disabling the blank-line feature:
1917 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1918 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
1919 >>> suite.run(unittest.TestResult())
1920 <unittest.result.TestResult run=9 errors=0 failures=5>
1922 You can supply setUp and tearDown functions:
1924 >>> def setUp(t):
1925 ... import test.test_doctest
1926 ... test.test_doctest.sillySetup = True
1928 >>> def tearDown(t):
1929 ... import test.test_doctest
1930 ... del test.test_doctest.sillySetup
1932 Here, we installed a silly variable that the test expects:
1934 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1935 ... setUp=setUp, tearDown=tearDown)
1936 >>> suite.run(unittest.TestResult())
1937 <unittest.result.TestResult run=9 errors=0 failures=3>
1939 But the tearDown restores sanity:
1941 >>> import test.test_doctest
1942 >>> test.test_doctest.sillySetup
1943 Traceback (most recent call last):
1945 AttributeError: 'module' object has no attribute 'sillySetup'
1947 The setUp and tearDown funtions are passed test objects. Here
1948 we'll use the setUp function to supply the missing variable y:
1950 >>> def setUp(test):
1951 ... test.globs['y'] = 1
1953 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
1954 >>> suite.run(unittest.TestResult())
1955 <unittest.result.TestResult run=9 errors=0 failures=3>
1957 Here, we didn't need to use a tearDown function because we
1958 modified the test globals, which are a copy of the
1959 sample_doctest module dictionary. The test globals are
1960 automatically cleared for us after a test.
1963 def test_DocFileSuite():
1964 """We can test tests found in text files using a DocFileSuite.
1966 We create a suite by providing the names of one or more text
1967 files that include examples:
1969 >>> import unittest
1970 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1971 ... 'test_doctest2.txt',
1972 ... 'test_doctest4.txt')
1973 >>> suite.run(unittest.TestResult())
1974 <unittest.result.TestResult run=3 errors=0 failures=3>
1976 The test files are looked for in the directory containing the
1977 calling module. A package keyword argument can be provided to
1978 specify a different relative location.
1980 >>> import unittest
1981 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1982 ... 'test_doctest2.txt',
1983 ... 'test_doctest4.txt',
1984 ... package='test')
1985 >>> suite.run(unittest.TestResult())
1986 <unittest.result.TestResult run=3 errors=0 failures=3>
1988 Support for using a package's __loader__.get_data() is also
1989 provided.
1991 >>> import unittest, pkgutil, test
1992 >>> added_loader = False
1993 >>> if not hasattr(test, '__loader__'):
1994 ... test.__loader__ = pkgutil.get_loader(test)
1995 ... added_loader = True
1996 >>> try:
1997 ... suite = doctest.DocFileSuite('test_doctest.txt',
1998 ... 'test_doctest2.txt',
1999 ... 'test_doctest4.txt',
2000 ... package='test')
2001 ... suite.run(unittest.TestResult())
2002 ... finally:
2003 ... if added_loader:
2004 ... del test.__loader__
2005 <unittest.result.TestResult run=3 errors=0 failures=3>
2007 '/' should be used as a path separator. It will be converted
2008 to a native separator at run time:
2010 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2011 >>> suite.run(unittest.TestResult())
2012 <unittest.result.TestResult run=1 errors=0 failures=1>
2014 If DocFileSuite is used from an interactive session, then files
2015 are resolved relative to the directory of sys.argv[0]:
2017 >>> import types, os.path, test.test_doctest
2018 >>> save_argv = sys.argv
2019 >>> sys.argv = [test.test_doctest.__file__]
2020 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2021 ... package=types.ModuleType('__main__'))
2022 >>> sys.argv = save_argv
2024 By setting `module_relative=False`, os-specific paths may be
2025 used (including absolute paths and paths relative to the
2026 working directory):
2028 >>> # Get the absolute path of the test package.
2029 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2030 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
2032 >>> # Use it to find the absolute path of test_doctest.txt.
2033 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2035 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
2036 >>> suite.run(unittest.TestResult())
2037 <unittest.result.TestResult run=1 errors=0 failures=1>
2039 It is an error to specify `package` when `module_relative=False`:
2041 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2042 ... package='test')
2043 Traceback (most recent call last):
2044 ValueError: Package may only be specified for module-relative paths.
2046 You can specify initial global variables:
2048 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2049 ... 'test_doctest2.txt',
2050 ... 'test_doctest4.txt',
2051 ... globs={'favorite_color': 'blue'})
2052 >>> suite.run(unittest.TestResult())
2053 <unittest.result.TestResult run=3 errors=0 failures=2>
2055 In this case, we supplied a missing favorite color. You can
2056 provide doctest options:
2058 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2059 ... 'test_doctest2.txt',
2060 ... 'test_doctest4.txt',
2061 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2062 ... globs={'favorite_color': 'blue'})
2063 >>> suite.run(unittest.TestResult())
2064 <unittest.result.TestResult run=3 errors=0 failures=3>
2066 And, you can provide setUp and tearDown functions:
2068 >>> def setUp(t):
2069 ... import test.test_doctest
2070 ... test.test_doctest.sillySetup = True
2072 >>> def tearDown(t):
2073 ... import test.test_doctest
2074 ... del test.test_doctest.sillySetup
2076 Here, we installed a silly variable that the test expects:
2078 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2079 ... 'test_doctest2.txt',
2080 ... 'test_doctest4.txt',
2081 ... setUp=setUp, tearDown=tearDown)
2082 >>> suite.run(unittest.TestResult())
2083 <unittest.result.TestResult run=3 errors=0 failures=2>
2085 But the tearDown restores sanity:
2087 >>> import test.test_doctest
2088 >>> test.test_doctest.sillySetup
2089 Traceback (most recent call last):
2091 AttributeError: 'module' object has no attribute 'sillySetup'
2093 The setUp and tearDown funtions are passed test objects.
2094 Here, we'll use a setUp function to set the favorite color in
2095 test_doctest.txt:
2097 >>> def setUp(test):
2098 ... test.globs['favorite_color'] = 'blue'
2100 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2101 >>> suite.run(unittest.TestResult())
2102 <unittest.result.TestResult run=1 errors=0 failures=0>
2104 Here, we didn't need to use a tearDown function because we
2105 modified the test globals. The test globals are
2106 automatically cleared for us after a test.
2108 Tests in a file run using `DocFileSuite` can also access the
2109 `__file__` global, which is set to the name of the file
2110 containing the tests:
2112 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2113 >>> suite.run(unittest.TestResult())
2114 <unittest.result.TestResult run=1 errors=0 failures=0>
2116 If the tests contain non-ASCII characters, we have to specify which
2117 encoding the file is encoded with. We do so by using the `encoding`
2118 parameter:
2120 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2121 ... 'test_doctest2.txt',
2122 ... 'test_doctest4.txt',
2123 ... encoding='utf-8')
2124 >>> suite.run(unittest.TestResult())
2125 <unittest.result.TestResult run=3 errors=0 failures=2>
2129 def test_trailing_space_in_test():
2131 Trailing spaces in expected output are significant:
2133 >>> x, y = 'foo', ''
2134 >>> print x, y
2135 foo \n
2139 def test_unittest_reportflags():
2140 """Default unittest reporting flags can be set to control reporting
2142 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2143 only the first failure of each test. First, we'll look at the
2144 output without the flag. The file test_doctest.txt file has two
2145 tests. They both fail if blank lines are disabled:
2147 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2148 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2149 >>> import unittest
2150 >>> result = suite.run(unittest.TestResult())
2151 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2152 Traceback ...
2153 Failed example:
2154 favorite_color
2156 Failed example:
2157 if 1:
2160 Note that we see both failures displayed.
2162 >>> old = doctest.set_unittest_reportflags(
2163 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2165 Now, when we run the test:
2167 >>> result = suite.run(unittest.TestResult())
2168 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2169 Traceback ...
2170 Failed example:
2171 favorite_color
2172 Exception raised:
2174 NameError: name 'favorite_color' is not defined
2175 <BLANKLINE>
2176 <BLANKLINE>
2178 We get only the first failure.
2180 If we give any reporting options when we set up the tests,
2181 however:
2183 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2184 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2186 Then the default eporting options are ignored:
2188 >>> result = suite.run(unittest.TestResult())
2189 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2190 Traceback ...
2191 Failed example:
2192 favorite_color
2194 Failed example:
2195 if 1:
2196 print 'a'
2197 print
2198 print 'b'
2199 Differences (ndiff with -expected +actual):
2201 - <BLANKLINE>
2204 <BLANKLINE>
2205 <BLANKLINE>
2208 Test runners can restore the formatting flags after they run:
2210 >>> ignored = doctest.set_unittest_reportflags(old)
2214 def test_testfile(): r"""
2215 Tests for the `testfile()` function. This function runs all the
2216 doctest examples in a given file. In its simple invokation, it is
2217 called with the name of a file, which is taken to be relative to the
2218 calling module. The return value is (#failures, #tests).
2220 We don't want `-v` in sys.argv for these tests.
2222 >>> save_argv = sys.argv
2223 >>> if '-v' in sys.argv:
2224 ... sys.argv = [arg for arg in save_argv if arg != '-v']
2227 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2228 **********************************************************************
2229 File "...", line 6, in test_doctest.txt
2230 Failed example:
2231 favorite_color
2232 Exception raised:
2234 NameError: name 'favorite_color' is not defined
2235 **********************************************************************
2236 1 items had failures:
2237 1 of 2 in test_doctest.txt
2238 ***Test Failed*** 1 failures.
2239 TestResults(failed=1, attempted=2)
2240 >>> doctest.master = None # Reset master.
2242 (Note: we'll be clearing doctest.master after each call to
2243 `doctest.testfile`, to suppress warnings about multiple tests with the
2244 same name.)
2246 Globals may be specified with the `globs` and `extraglobs` parameters:
2248 >>> globs = {'favorite_color': 'blue'}
2249 >>> doctest.testfile('test_doctest.txt', globs=globs)
2250 TestResults(failed=0, attempted=2)
2251 >>> doctest.master = None # Reset master.
2253 >>> extraglobs = {'favorite_color': 'red'}
2254 >>> doctest.testfile('test_doctest.txt', globs=globs,
2255 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2256 **********************************************************************
2257 File "...", line 6, in test_doctest.txt
2258 Failed example:
2259 favorite_color
2260 Expected:
2261 'blue'
2262 Got:
2263 'red'
2264 **********************************************************************
2265 1 items had failures:
2266 1 of 2 in test_doctest.txt
2267 ***Test Failed*** 1 failures.
2268 TestResults(failed=1, attempted=2)
2269 >>> doctest.master = None # Reset master.
2271 The file may be made relative to a given module or package, using the
2272 optional `module_relative` parameter:
2274 >>> doctest.testfile('test_doctest.txt', globs=globs,
2275 ... module_relative='test')
2276 TestResults(failed=0, attempted=2)
2277 >>> doctest.master = None # Reset master.
2279 Verbosity can be increased with the optional `verbose` paremter:
2281 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2282 Trying:
2283 favorite_color
2284 Expecting:
2285 'blue'
2287 Trying:
2288 if 1:
2289 print 'a'
2290 print
2291 print 'b'
2292 Expecting:
2294 <BLANKLINE>
2297 1 items passed all tests:
2298 2 tests in test_doctest.txt
2299 2 tests in 1 items.
2300 2 passed and 0 failed.
2301 Test passed.
2302 TestResults(failed=0, attempted=2)
2303 >>> doctest.master = None # Reset master.
2305 The name of the test may be specified with the optional `name`
2306 parameter:
2308 >>> doctest.testfile('test_doctest.txt', name='newname')
2309 ... # doctest: +ELLIPSIS
2310 **********************************************************************
2311 File "...", line 6, in newname
2313 TestResults(failed=1, attempted=2)
2314 >>> doctest.master = None # Reset master.
2316 The summary report may be supressed with the optional `report`
2317 parameter:
2319 >>> doctest.testfile('test_doctest.txt', report=False)
2320 ... # doctest: +ELLIPSIS
2321 **********************************************************************
2322 File "...", line 6, in test_doctest.txt
2323 Failed example:
2324 favorite_color
2325 Exception raised:
2327 NameError: name 'favorite_color' is not defined
2328 TestResults(failed=1, attempted=2)
2329 >>> doctest.master = None # Reset master.
2331 The optional keyword argument `raise_on_error` can be used to raise an
2332 exception on the first error (which may be useful for postmortem
2333 debugging):
2335 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2336 ... # doctest: +ELLIPSIS
2337 Traceback (most recent call last):
2338 UnexpectedException: ...
2339 >>> doctest.master = None # Reset master.
2341 If the tests contain non-ASCII characters, the tests might fail, since
2342 it's unknown which encoding is used. The encoding can be specified
2343 using the optional keyword argument `encoding`:
2345 >>> doctest.testfile('test_doctest4.txt') # doctest: +ELLIPSIS
2346 **********************************************************************
2347 File "...", line 7, in test_doctest4.txt
2348 Failed example:
2349 u'...'
2350 Expected:
2351 u'f\xf6\xf6'
2352 Got:
2353 u'f\xc3\xb6\xc3\xb6'
2354 **********************************************************************
2356 **********************************************************************
2357 1 items had failures:
2358 2 of 4 in test_doctest4.txt
2359 ***Test Failed*** 2 failures.
2360 TestResults(failed=2, attempted=4)
2361 >>> doctest.master = None # Reset master.
2363 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2364 TestResults(failed=0, attempted=4)
2365 >>> doctest.master = None # Reset master.
2367 Switch the module encoding to 'utf-8' to test the verbose output without
2368 bothering with the current sys.stdout encoding.
2370 >>> doctest._encoding, saved_encoding = 'utf-8', doctest._encoding
2371 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2372 Trying:
2373 u'föö'
2374 Expecting:
2375 u'f\xf6\xf6'
2377 Trying:
2378 u'bąr'
2379 Expecting:
2380 u'b\u0105r'
2382 Trying:
2383 'föö'
2384 Expecting:
2385 'f\xc3\xb6\xc3\xb6'
2387 Trying:
2388 'bąr'
2389 Expecting:
2390 'b\xc4\x85r'
2392 1 items passed all tests:
2393 4 tests in test_doctest4.txt
2394 4 tests in 1 items.
2395 4 passed and 0 failed.
2396 Test passed.
2397 TestResults(failed=0, attempted=4)
2398 >>> doctest._encoding = saved_encoding
2399 >>> doctest.master = None # Reset master.
2400 >>> sys.argv = save_argv
2403 # old_test1, ... used to live in doctest.py, but cluttered it. Note
2404 # that these use the deprecated doctest.Tester, so should go away (or
2405 # be rewritten) someday.
2407 def old_test1(): r"""
2408 >>> from doctest import Tester
2409 >>> t = Tester(globs={'x': 42}, verbose=0)
2410 >>> t.runstring(r'''
2411 ... >>> x = x * 2
2412 ... >>> print x
2413 ... 42
2414 ... ''', 'XYZ')
2415 **********************************************************************
2416 Line 3, in XYZ
2417 Failed example:
2418 print x
2419 Expected:
2421 Got:
2423 TestResults(failed=1, attempted=2)
2424 >>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
2425 TestResults(failed=0, attempted=2)
2426 >>> t.summarize()
2427 **********************************************************************
2428 1 items had failures:
2429 1 of 2 in XYZ
2430 ***Test Failed*** 1 failures.
2431 TestResults(failed=1, attempted=4)
2432 >>> t.summarize(verbose=1)
2433 1 items passed all tests:
2434 2 tests in example2
2435 **********************************************************************
2436 1 items had failures:
2437 1 of 2 in XYZ
2438 4 tests in 2 items.
2439 3 passed and 1 failed.
2440 ***Test Failed*** 1 failures.
2441 TestResults(failed=1, attempted=4)
2444 def old_test2(): r"""
2445 >>> from doctest import Tester
2446 >>> t = Tester(globs={}, verbose=1)
2447 >>> test = r'''
2448 ... # just an example
2449 ... >>> x = 1 + 2
2450 ... >>> x
2451 ... 3
2452 ... '''
2453 >>> t.runstring(test, "Example")
2454 Running string Example
2455 Trying:
2456 x = 1 + 2
2457 Expecting nothing
2459 Trying:
2461 Expecting:
2464 0 of 2 examples failed in string Example
2465 TestResults(failed=0, attempted=2)
2468 def old_test3(): r"""
2469 >>> from doctest import Tester
2470 >>> t = Tester(globs={}, verbose=0)
2471 >>> def _f():
2472 ... '''Trivial docstring example.
2473 ... >>> assert 2 == 2
2474 ... '''
2475 ... return 32
2477 >>> t.rundoc(_f) # expect 0 failures in 1 example
2478 TestResults(failed=0, attempted=1)
2481 def old_test4(): """
2482 >>> import types
2483 >>> m1 = types.ModuleType('_m1')
2484 >>> m2 = types.ModuleType('_m2')
2485 >>> test_data = \"""
2486 ... def _f():
2487 ... '''>>> assert 1 == 1
2488 ... '''
2489 ... def g():
2490 ... '''>>> assert 2 != 1
2491 ... '''
2492 ... class H:
2493 ... '''>>> assert 2 > 1
2494 ... '''
2495 ... def bar(self):
2496 ... '''>>> assert 1 < 2
2497 ... '''
2498 ... \"""
2499 >>> exec test_data in m1.__dict__
2500 >>> exec test_data in m2.__dict__
2501 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
2503 Tests that objects outside m1 are excluded:
2505 >>> from doctest import Tester
2506 >>> t = Tester(globs={}, verbose=0)
2507 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
2508 TestResults(failed=0, attempted=4)
2510 Once more, not excluding stuff outside m1:
2512 >>> t = Tester(globs={}, verbose=0)
2513 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
2514 TestResults(failed=0, attempted=8)
2516 The exclusion of objects from outside the designated module is
2517 meant to be invoked automagically by testmod.
2519 >>> doctest.testmod(m1, verbose=False)
2520 TestResults(failed=0, attempted=4)
2523 ######################################################################
2524 ## Main
2525 ######################################################################
2527 def test_main():
2528 # Check the doctest cases in doctest itself:
2529 test_support.run_doctest(doctest, verbosity=True)
2531 from test import test_doctest
2533 # Ignore all warnings about the use of class Tester in this module.
2534 deprecations = [("class Tester is deprecated", DeprecationWarning)]
2535 if sys.py3kwarning:
2536 deprecations += [("backquote not supported", SyntaxWarning),
2537 ("execfile.. not supported", DeprecationWarning)]
2538 with test_support.check_warnings(*deprecations):
2539 # Check the doctest cases defined here:
2540 test_support.run_doctest(test_doctest, verbosity=True)
2542 import sys
2543 def test_coverage(coverdir):
2544 trace = test_support.import_module('trace')
2545 tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
2546 trace=0, count=1)
2547 tracer.run('reload(doctest); test_main()')
2548 r = tracer.results()
2549 print 'Writing coverage results...'
2550 r.write_results(show_missing=True, summary=True,
2551 coverdir=coverdir)
2553 if __name__ == '__main__':
2554 if '-c' in sys.argv:
2555 test_coverage('/tmp/doctest.cover')
2556 else:
2557 test_main()