]>
git.proxmox.com Git - mirror_edk2.git/blob - AppPkg/Applications/Python/Python-2.7.2/Lib/test/test_doctest.py
1 # -*- coding: utf-8 -*-
3 Test script for doctest.
7 from test
import test_support
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 ######################################################################
21 >>> print sample_func(22)
33 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
38 >>> sc = SampleClass(3)
39 >>> for i in range(10):
42 6 12 24 48 96 192 384 768 1536 3072
44 def __init__(self
, val
):
46 >>> print SampleClass(12).get()
53 >>> print SampleClass(12).double().get()
56 return SampleClass(self
.val
+ self
.val
)
60 >>> print SampleClass(-5).get()
65 def a_staticmethod(v
):
67 >>> print SampleClass.a_staticmethod(10)
71 a_staticmethod
= staticmethod(a_staticmethod
)
73 def a_classmethod(cls
, v
):
75 >>> print SampleClass.a_classmethod(10)
77 >>> print SampleClass(0).a_classmethod(10)
81 a_classmethod
= classmethod(a_classmethod
)
83 a_property
= property(get
, doc
="""
84 >>> print SampleClass(22).a_property
90 >>> x = SampleClass.NestedClass(5)
95 def __init__(self
, val
=0):
97 >>> print SampleClass.NestedClass().get()
102 return SampleClass
.NestedClass(self
.val
*self
.val
)
106 class SampleNewStyleClass(object):
113 def __init__(self
, val
):
115 >>> print SampleNewStyleClass(12).get()
122 >>> print SampleNewStyleClass(12).double().get()
125 return SampleNewStyleClass(self
.val
+ self
.val
)
129 >>> print SampleNewStyleClass(-5).get()
134 ######################################################################
135 ## Fake stdin (for testing interactive debugging)
136 ######################################################################
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
):
149 line
= self
.lines
.pop(0)
153 ######################################################################
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
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
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')
197 >>> e = doctest.Example('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')
204 ('print 1;\nprint 2\n', '1\n2\n')
206 >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')
208 ('print 1;\nprint 2\n', '1\n2\n')
210 Empty source string (which should never appear in real examples)
211 >>> e = doctest.Example('', '')
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')
222 >>> e = doctest.Example('print 1', '1')
226 >>> e = doctest.Example('print', '')
230 The constructor normalizes the `exc_msg` string to end in a newline,
233 Message spans one line
234 >>> exc_msg = 'IndexError: pop from an empty list'
235 >>> e = doctest.Example('[].pop()', '', 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)
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)
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)
253 'ValueError: 1\n 2\n'
255 Empty (but non-None) exception message (which should never appear
258 >>> e = doctest.Example('raise X()', '', exc_msg)
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`
275 ... Non-example text.
277 ... >>> print 'another\example'
281 >>> globs = {} # globals to run the test in.
282 >>> parser = doctest.DocTestParser()
283 >>> test = parser.get_doctest(docstring, globs, 'some_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
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:
314 ... >>> print 'bad\nindentation'
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:
326 ... >>> print ('bad indentation',
328 ... ('bad', 'indentation')
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
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
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):
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
402 >>> def no_docstring(v):
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)
427 ... print '%2s %s' % (len(t.examples), t.name)
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
438 New-style classes are also supported:
440 >>> tests = finder.find(SampleNewStyleClass)
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:
456 >>> m = types.ModuleType('some_module')
459 ... >>> print triple(11)
463 >>> m.__dict__.update({
464 ... 'sample_func': sample_func,
465 ... 'SampleClass': SampleClass,
467 ... Module docstring.
468 ... >>> print 'module'
472 ... 'd': '>>> print 6\n6\n>>> print 7\n7\n',
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)
481 ... print '%2s %s' % (len(t.examples), t.name)
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
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)
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']
519 By default, an object with no doctests doesn't create any tests:
521 >>> tests = doctest.DocTestFinder().find(SampleClass)
523 ... print '%2s %s' % (len(t.examples), t.name)
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
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()
539 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
541 ... print '%2s %s' % (len(t.examples), t.name)
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
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)
561 ... print '%2s %s' % (len(t.examples), t.name)
566 DocTestFinder finds the line number of each example:
574 ... >>> # examples are not created for comments & bare prompts.
578 ... >>> for x in range(10):
580 ... 0 1 2 3 4 5 6 7 8 9
584 >>> test = doctest.DocTestFinder().find(f)[0]
585 >>> [e.lineno for e in test.examples]
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
598 ... >>> x, y = 2, 3 # no output expected
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)
614 ... print ' Text:', `piece`
616 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
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)
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)
631 The `get_doctest` method creates a Test from the examples, along with the
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)
644 class test_DocTestRunner
:
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:
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
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:
680 >>> test = doctest.DocTestFinder().find(f)[0]
681 >>> doctest.DocTestRunner(verbose=True).run(test)
682 ... # doctest: +ELLIPSIS
691 **********************************************************************
692 File ..., line 4, in f
704 TestResults(failed=1, attempted=3)
706 def verbose_flag(): r
"""
707 The `verbose` flag makes the test runner generate more detailed
718 >>> test = doctest.DocTestFinder().find(f)[0]
720 >>> doctest.DocTestRunner(verbose=True).run(test)
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)
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:
784 ... Traceback (most recent call last):
785 ... ZeroDivisionError: integer division or modulo by zero
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:
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
804 >>> test = doctest.DocTestFinder().find(f)[0]
805 >>> doctest.DocTestRunner(verbose=False).run(test)
806 ... # doctest: +ELLIPSIS
807 **********************************************************************
808 File ..., line 4, in f
810 print 'pre-exception output', x//0
813 ZeroDivisionError: integer division or modulo by zero
814 TestResults(failed=1, attempted=2)
816 Exception messages may contain newlines:
820 ... >>> raise ValueError, 'multi\nline\nmessage'
821 ... Traceback (most recent call last):
822 ... ValueError: multi
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:
835 ... >>> raise ValueError, 'message'
836 ... Traceback (most recent call last):
837 ... ValueError: wrong message
839 >>> test = doctest.DocTestFinder().find(f)[0]
840 >>> doctest.DocTestRunner(verbose=False).run(test)
841 ... # doctest: +ELLIPSIS
842 **********************************************************************
843 File ..., line 3, in f
845 raise ValueError, 'message'
847 Traceback (most recent call last):
848 ValueError: wrong message
850 Traceback (most recent call last):
853 TestResults(failed=1, attempted=1)
855 However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
860 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
861 ... Traceback (most recent call last):
862 ... ValueError: wrong message
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:
874 ... >>> from httplib import HTTPException
875 ... >>> raise HTTPException('message')
876 ... Traceback (most recent call last):
877 ... httplib.HTTPException: message
879 >>> test = doctest.DocTestFinder().find(f)[0]
880 >>> doctest.DocTestRunner(verbose=False).run(test)
881 ... # doctest: +ELLIPSIS
882 **********************************************************************
883 File ..., line 4, in f
885 raise HTTPException('message')
887 Traceback (most recent call last):
888 httplib.HTTPException: message
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
901 ... >>> from httplib import HTTPException
902 ... >>> raise HTTPException('message')
903 ... Traceback (most recent call last):
904 ... HTTPException: message
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:
915 ... >>> from httplib import HTTPException
916 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
917 ... Traceback (most recent call last):
918 ... HTTPException: message
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.
930 ... >>> from httplib import HTTPException
931 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
932 ... Traceback (most recent call last):
933 ... foo.bar.HTTPException: message
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:
943 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
944 ... Traceback (most recent call last):
945 ... TypeError: wrong type
947 >>> test = doctest.DocTestFinder().find(f)[0]
948 >>> doctest.DocTestRunner(verbose=False).run(test)
949 ... # doctest: +ELLIPSIS
950 **********************************************************************
951 File ..., line 3, in f
953 raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
955 Traceback (most recent call last):
956 TypeError: wrong type
958 Traceback (most recent call last):
961 TestResults(failed=1, attempted=1)
963 If an exception is raised but not expected, then it is reported as an
964 unexpected exception:
971 >>> test = doctest.DocTestFinder().find(f)[0]
972 >>> doctest.DocTestRunner(verbose=False).run(test)
973 ... # doctest: +ELLIPSIS
974 **********************************************************************
975 File ..., line 3, in f
979 Traceback (most recent call last):
981 ZeroDivisionError: integer division or modulo by zero
982 TestResults(failed=1, attempted=1)
984 def displayhook(): r
"""
985 Test that changing sys.displayhook doesn't matter for doctest.
988 >>> orig_displayhook = sys.displayhook
989 >>> def my_displayhook(x):
991 >>> sys.displayhook = my_displayhook
997 >>> test = doctest.DocTestFinder().find(f)[0]
998 >>> r = doctest.DocTestRunner(verbose=False).run(test)
999 >>> post_displayhook = sys.displayhook
1001 We need to restore sys.displayhook now, so that we'll be able to test
1004 >>> sys.displayhook = orig_displayhook
1006 Ok, now we can check that everything is ok.
1009 TestResults(failed=0, attempted=1)
1010 >>> post_displayhook is my_displayhook
1013 def optionflags(): r
"""
1014 Tests of `DocTestRunner`'s option flag handling.
1016 Several option flags can be used to customize the behavior of the test
1017 runner. These are defined as module constants in doctest, and passed
1018 to the DocTestRunner constructor (multiple constants should be ORed
1021 The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
1027 >>> # Without the flag:
1028 >>> test = doctest.DocTestFinder().find(f)[0]
1029 >>> doctest.DocTestRunner(verbose=False).run(test)
1030 TestResults(failed=0, attempted=1)
1032 >>> # With the flag:
1033 >>> test = doctest.DocTestFinder().find(f)[0]
1034 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1035 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1036 ... # doctest: +ELLIPSIS
1037 **********************************************************************
1038 File ..., line 2, in f
1045 TestResults(failed=1, attempted=1)
1047 The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1048 and the '<BLANKLINE>' marker:
1051 ... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n'
1053 >>> # Without the flag:
1054 >>> test = doctest.DocTestFinder().find(f)[0]
1055 >>> doctest.DocTestRunner(verbose=False).run(test)
1056 TestResults(failed=0, attempted=1)
1058 >>> # With the flag:
1059 >>> test = doctest.DocTestFinder().find(f)[0]
1060 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
1061 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1062 ... # doctest: +ELLIPSIS
1063 **********************************************************************
1064 File ..., line 2, in f
1075 TestResults(failed=1, attempted=1)
1077 The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1081 ... '>>> print 1, 2, 3\n 1 2\n 3'
1083 >>> # Without the flag:
1084 >>> test = doctest.DocTestFinder().find(f)[0]
1085 >>> doctest.DocTestRunner(verbose=False).run(test)
1086 ... # doctest: +ELLIPSIS
1087 **********************************************************************
1088 File ..., line 2, in f
1096 TestResults(failed=1, attempted=1)
1098 >>> # With the flag:
1099 >>> test = doctest.DocTestFinder().find(f)[0]
1100 >>> flags = doctest.NORMALIZE_WHITESPACE
1101 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1102 TestResults(failed=0, attempted=1)
1104 An example from the docs:
1105 >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
1106 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1107 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1109 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1110 output to match any substring in the actual output:
1113 ... '>>> print range(15)\n[0, 1, 2, ..., 14]\n'
1115 >>> # Without the flag:
1116 >>> test = doctest.DocTestFinder().find(f)[0]
1117 >>> doctest.DocTestRunner(verbose=False).run(test)
1118 ... # doctest: +ELLIPSIS
1119 **********************************************************************
1120 File ..., line 2, in f
1126 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1127 TestResults(failed=1, attempted=1)
1129 >>> # With the flag:
1130 >>> test = doctest.DocTestFinder().find(f)[0]
1131 >>> flags = doctest.ELLIPSIS
1132 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1133 TestResults(failed=0, attempted=1)
1135 ... also matches nothing:
1137 >>> for i in range(100):
1138 ... print i**2, #doctest: +ELLIPSIS
1139 0 1...4...9 16 ... 36 49 64 ... 9801
1141 ... can be surprising; e.g., this test passes:
1143 >>> for i in range(21): #doctest: +ELLIPSIS
1147 Examples from the docs:
1149 >>> print range(20) # doctest:+ELLIPSIS
1152 >>> print range(20) # doctest: +ELLIPSIS
1153 ... # doctest: +NORMALIZE_WHITESPACE
1156 The SKIP flag causes an example to be skipped entirely. I.e., the
1157 example is not run. It can be useful in contexts where doctest
1158 examples serve as both documentation and test cases, and an example
1159 should be included for documentation purposes, but should not be
1160 checked (e.g., because its output is random, or depends on resources
1161 which would be unavailable.) The SKIP flag can also be used for
1162 'commenting out' broken examples.
1164 >>> import unavailable_resource # doctest: +SKIP
1165 >>> unavailable_resource.do_something() # doctest: +SKIP
1166 >>> unavailable_resource.blow_up() # doctest: +SKIP
1167 Traceback (most recent call last):
1169 UncheckedBlowUpError: Nobody checks me.
1172 >>> print random.random() # doctest: +SKIP
1175 The REPORT_UDIFF flag causes failures that involve multi-line expected
1176 and actual outputs to be displayed using a unified diff:
1180 ... >>> print '\n'.join('abcdefg')
1190 >>> # Without the flag:
1191 >>> test = doctest.DocTestFinder().find(f)[0]
1192 >>> doctest.DocTestRunner(verbose=False).run(test)
1193 ... # doctest: +ELLIPSIS
1194 **********************************************************************
1195 File ..., line 3, in f
1197 print '\n'.join('abcdefg')
1214 TestResults(failed=1, attempted=1)
1216 >>> # With the flag:
1217 >>> test = doctest.DocTestFinder().find(f)[0]
1218 >>> flags = doctest.REPORT_UDIFF
1219 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1220 ... # doctest: +ELLIPSIS
1221 **********************************************************************
1222 File ..., line 3, in f
1224 print '\n'.join('abcdefg')
1225 Differences (unified diff with -expected +actual):
1236 TestResults(failed=1, attempted=1)
1238 The REPORT_CDIFF flag causes failures that involve multi-line expected
1239 and actual outputs to be displayed using a context diff:
1241 >>> # Reuse f() from the REPORT_UDIFF example, above.
1242 >>> test = doctest.DocTestFinder().find(f)[0]
1243 >>> flags = doctest.REPORT_CDIFF
1244 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1245 ... # doctest: +ELLIPSIS
1246 **********************************************************************
1247 File ..., line 3, in f
1249 print '\n'.join('abcdefg')
1250 Differences (context diff with expected followed by actual):
1268 TestResults(failed=1, attempted=1)
1271 The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1272 used by the popular ndiff.py utility. This does intraline difference
1273 marking, as well as interline differences.
1277 ... >>> print "a b c d e f g h i j k l m"
1278 ... a b c d e f g h i j k 1 m
1280 >>> test = doctest.DocTestFinder().find(f)[0]
1281 >>> flags = doctest.REPORT_NDIFF
1282 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1283 ... # doctest: +ELLIPSIS
1284 **********************************************************************
1285 File ..., line 3, in f
1287 print "a b c d e f g h i j k l m"
1288 Differences (ndiff with -expected +actual):
1289 - a b c d e f g h i j k 1 m
1291 + a b c d e f g h i j k l m
1293 TestResults(failed=1, attempted=1)
1295 The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
1300 ... >>> print 1 # first success
1302 ... >>> print 2 # first failure
1304 ... >>> print 3 # second failure
1306 ... >>> print 4 # second success
1308 ... >>> print 5 # third failure
1311 >>> test = doctest.DocTestFinder().find(f)[0]
1312 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1313 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1314 ... # doctest: +ELLIPSIS
1315 **********************************************************************
1316 File ..., line 5, in f
1318 print 2 # first failure
1323 TestResults(failed=3, attempted=5)
1325 However, output from `report_start` is not suppressed:
1327 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1328 ... # doctest: +ELLIPSIS
1330 print 1 # first success
1335 print 2 # first failure
1338 **********************************************************************
1339 File ..., line 5, in f
1341 print 2 # first failure
1346 TestResults(failed=3, attempted=5)
1348 For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
1353 ... >>> print 1 # first success
1355 ... >>> raise ValueError(2) # first failure
1357 ... >>> print 3 # second failure
1359 ... >>> print 4 # second success
1361 ... >>> print 5 # third failure
1364 >>> test = doctest.DocTestFinder().find(f)[0]
1365 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1366 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1367 ... # doctest: +ELLIPSIS
1368 **********************************************************************
1369 File ..., line 5, in f
1371 raise ValueError(2) # first failure
1375 TestResults(failed=3, attempted=5)
1377 New option flags can also be registered, via register_optionflag(). Here
1378 we reach into doctest's internals a bit.
1380 >>> unlikely = "UNLIKELY_OPTION_NAME"
1381 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1383 >>> new_flag_value = doctest.register_optionflag(unlikely)
1384 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1387 Before 2.4.4/2.5, registering a name more than once erroneously created
1388 more than one flag value. Here we verify that's fixed:
1390 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1391 >>> redundant_flag_value == new_flag_value
1395 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1399 def option_directives(): r
"""
1400 Tests of `DocTestRunner`'s option directive mechanism.
1402 Option directives can be used to turn option flags on or off for a
1403 single example. To turn an option on for an example, follow that
1404 example with a comment of the form ``# doctest: +OPTION``:
1407 ... >>> print range(10) # should fail: no ellipsis
1410 ... >>> print range(10) # doctest: +ELLIPSIS
1413 >>> test = doctest.DocTestFinder().find(f)[0]
1414 >>> doctest.DocTestRunner(verbose=False).run(test)
1415 ... # doctest: +ELLIPSIS
1416 **********************************************************************
1417 File ..., line 2, in f
1419 print range(10) # should fail: no ellipsis
1423 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1424 TestResults(failed=1, attempted=2)
1426 To turn an option off for an example, follow that example with a
1427 comment of the form ``# doctest: -OPTION``:
1430 ... >>> print range(10)
1433 ... >>> # should fail: no ellipsis
1434 ... >>> print range(10) # doctest: -ELLIPSIS
1437 >>> test = doctest.DocTestFinder().find(f)[0]
1438 >>> doctest.DocTestRunner(verbose=False,
1439 ... optionflags=doctest.ELLIPSIS).run(test)
1440 ... # doctest: +ELLIPSIS
1441 **********************************************************************
1442 File ..., line 6, in f
1444 print range(10) # doctest: -ELLIPSIS
1448 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1449 TestResults(failed=1, attempted=2)
1451 Option directives affect only the example that they appear with; they
1452 do not change the options for surrounding examples:
1455 ... >>> print range(10) # Should fail: no ellipsis
1458 ... >>> print range(10) # doctest: +ELLIPSIS
1461 ... >>> print range(10) # Should fail: no ellipsis
1464 >>> test = doctest.DocTestFinder().find(f)[0]
1465 >>> doctest.DocTestRunner(verbose=False).run(test)
1466 ... # doctest: +ELLIPSIS
1467 **********************************************************************
1468 File ..., line 2, in f
1470 print range(10) # Should fail: no ellipsis
1474 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1475 **********************************************************************
1476 File ..., line 8, in f
1478 print range(10) # Should fail: no ellipsis
1482 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1483 TestResults(failed=2, attempted=3)
1485 Multiple options may be modified by a single option directive. They
1486 may be separated by whitespace, commas, or both:
1489 ... >>> print range(10) # Should fail
1491 ... >>> print range(10) # Should succeed
1492 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1495 >>> test = doctest.DocTestFinder().find(f)[0]
1496 >>> doctest.DocTestRunner(verbose=False).run(test)
1497 ... # doctest: +ELLIPSIS
1498 **********************************************************************
1499 File ..., line 2, in f
1501 print range(10) # Should fail
1505 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1506 TestResults(failed=1, attempted=2)
1509 ... >>> print range(10) # Should fail
1511 ... >>> print range(10) # Should succeed
1512 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1515 >>> test = doctest.DocTestFinder().find(f)[0]
1516 >>> doctest.DocTestRunner(verbose=False).run(test)
1517 ... # doctest: +ELLIPSIS
1518 **********************************************************************
1519 File ..., line 2, in f
1521 print range(10) # Should fail
1525 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1526 TestResults(failed=1, attempted=2)
1529 ... >>> print range(10) # Should fail
1531 ... >>> print range(10) # Should succeed
1532 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1535 >>> test = doctest.DocTestFinder().find(f)[0]
1536 >>> doctest.DocTestRunner(verbose=False).run(test)
1537 ... # doctest: +ELLIPSIS
1538 **********************************************************************
1539 File ..., line 2, in f
1541 print range(10) # Should fail
1545 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1546 TestResults(failed=1, attempted=2)
1548 The option directive may be put on the line following the source, as
1549 long as a continuation prompt is used:
1552 ... >>> print range(10)
1553 ... ... # doctest: +ELLIPSIS
1556 >>> test = doctest.DocTestFinder().find(f)[0]
1557 >>> doctest.DocTestRunner(verbose=False).run(test)
1558 TestResults(failed=0, attempted=1)
1560 For examples with multi-line source, the option directive may appear
1561 at the end of any line:
1564 ... >>> for x in range(10): # doctest: +ELLIPSIS
1568 ... >>> for x in range(10):
1569 ... ... print x, # doctest: +ELLIPSIS
1572 >>> test = doctest.DocTestFinder().find(f)[0]
1573 >>> doctest.DocTestRunner(verbose=False).run(test)
1574 TestResults(failed=0, attempted=2)
1576 If more than one line of an example with multi-line source has an
1577 option directive, then they are combined:
1580 ... Should fail (option directive not on the last line):
1581 ... >>> for x in range(10): # doctest: +ELLIPSIS
1582 ... ... print x, # doctest: +NORMALIZE_WHITESPACE
1585 >>> test = doctest.DocTestFinder().find(f)[0]
1586 >>> doctest.DocTestRunner(verbose=False).run(test)
1587 TestResults(failed=0, attempted=1)
1589 It is an error to have a comment of the form ``# doctest:`` that is
1590 *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1591 ``OPTION`` is an option that has been registered with
1594 >>> # Error: Option not registered
1595 >>> s = '>>> print 12 #doctest: +BADOPTION'
1596 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1597 Traceback (most recent call last):
1598 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1600 >>> # Error: No + or - prefix
1601 >>> s = '>>> print 12 #doctest: ELLIPSIS'
1602 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1603 Traceback (most recent call last):
1604 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1606 It is an error to use an option directive on a line that contains no
1609 >>> s = '>>> # doctest: +ELLIPSIS'
1610 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1611 Traceback (most recent call last):
1612 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1616 def test_unicode_output(self
): r
"""
1618 Check that unicode output works:
1623 If we return unicode, SpoofOut's buf variable becomes automagically
1624 converted to unicode. This means all subsequent output becomes converted
1625 to unicode, and if the output contains non-ascii characters that failed.
1626 It used to be that this state change carried on between tests, meaning
1627 tests would fail if unicode has been output previously in the testrun.
1628 This test tests that this is no longer so:
1633 And then return a string with non-ascii characters:
1635 >>> print u'\xe9'.encode('utf-8')
1641 def test_testsource(): r
"""
1642 Unit tests for `testsource()`.
1644 The testsource() function takes a module and a name, finds the (first)
1645 test with that name in that module, and converts it to a script. The
1646 example code is converted to regular Python code. The surrounding
1647 words and expected output are converted to comments:
1649 >>> import test.test_doctest
1650 >>> name = 'test.test_doctest.sample_func'
1651 >>> print doctest.testsource(test.test_doctest, name)
1654 print sample_func(22)
1661 >>> name = 'test.test_doctest.SampleNewStyleClass'
1662 >>> print doctest.testsource(test.test_doctest, name)
1670 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1671 >>> print doctest.testsource(test.test_doctest, name)
1672 print SampleClass.a_classmethod(10)
1675 print SampleClass(0).a_classmethod(10)
1681 def test_debug(): r
"""
1683 Create a docstring that we want to debug:
1691 Create some fake stdin input, to feed to the debugger:
1694 >>> real_stdin = sys.stdin
1695 >>> sys.stdin = _FakeInput(['next', 'print x', 'continue'])
1697 Run the debugger on the docstring, and then restore sys.stdin.
1699 >>> try: doctest.debug_src(s)
1700 ... finally: sys.stdin = real_stdin
1701 > <string>(1)<module>()
1705 > <string>(1)<module>()->None
1712 def test_pdb_set_trace():
1713 """Using pdb.set_trace from a doctest.
1715 You can use pdb.set_trace from a doctest. To do so, you must
1716 retrieve the set_trace function from the pdb module at the time
1717 you use it. The doctest module changes sys.stdout so that it can
1718 capture program output. It also temporarily replaces pdb.set_trace
1719 with a version that restores stdout. This is necessary for you to
1720 see debugger output.
1724 ... >>> raise Exception('clé')
1725 ... Traceback (most recent call last):
1727 ... >>> import pdb; pdb.set_trace()
1729 >>> parser = doctest.DocTestParser()
1730 >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)
1731 >>> runner = doctest.DocTestRunner(verbose=False)
1733 To demonstrate this, we'll create a fake standard input that
1734 captures our debugger input:
1737 >>> real_stdin = sys.stdin
1738 >>> sys.stdin = _FakeInput([
1739 ... 'print x', # print data defined by the example
1740 ... 'continue', # stop debugging
1743 >>> try: runner.run(test)
1744 ... finally: sys.stdin = real_stdin
1746 > <doctest foo-bär@baz[2]>(1)<module>()->None
1747 -> import pdb; pdb.set_trace()
1751 TestResults(failed=0, attempted=3)
1753 You can also put pdb.set_trace in a function called from a test:
1755 >>> def calls_set_trace():
1757 ... import pdb; pdb.set_trace()
1761 ... >>> calls_set_trace()
1763 >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
1764 >>> real_stdin = sys.stdin
1765 >>> sys.stdin = _FakeInput([
1766 ... 'print y', # print data defined in the function
1767 ... 'up', # out of function
1768 ... 'print x', # print data defined by the example
1769 ... 'continue', # stop debugging
1773 ... runner.run(test)
1775 ... sys.stdin = real_stdin
1777 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
1778 -> import pdb; pdb.set_trace()
1782 > <doctest foo-bär@baz[1]>(1)<module>()
1783 -> calls_set_trace()
1787 TestResults(failed=0, attempted=2)
1789 During interactive debugging, source code is shown, even for
1797 ... ... import pdb; pdb.set_trace()
1800 >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
1801 >>> real_stdin = sys.stdin
1802 >>> sys.stdin = _FakeInput([
1803 ... 'list', # list source from example 2
1804 ... 'next', # return from g()
1805 ... 'list', # list source from example 1
1806 ... 'next', # return from f()
1807 ... 'list', # list source from example 3
1808 ... 'continue', # stop debugging
1810 >>> try: runner.run(test)
1811 ... finally: sys.stdin = real_stdin
1812 ... # doctest: +NORMALIZE_WHITESPACE
1814 > <doctest foo-bär@baz[1]>(3)g()->None
1815 -> import pdb; pdb.set_trace()
1819 3 -> import pdb; pdb.set_trace()
1823 > <doctest foo-bär@baz[0]>(2)f()->None
1831 > <doctest foo-bär@baz[2]>(1)<module>()->None
1837 **********************************************************************
1838 File "foo-bär@baz.py", line 7, in foo-bär@baz
1844 TestResults(failed=1, attempted=3)
1847 def test_pdb_set_trace_nested():
1848 """This illustrates more-demanding use of set_trace with nested functions.
1850 >>> class C(object):
1851 ... def calls_set_trace(self):
1853 ... import pdb; pdb.set_trace()
1864 >>> calls_set_trace = C().calls_set_trace
1868 ... >>> calls_set_trace()
1870 >>> parser = doctest.DocTestParser()
1871 >>> runner = doctest.DocTestRunner(verbose=False)
1872 >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
1873 >>> real_stdin = sys.stdin
1874 >>> sys.stdin = _FakeInput([
1875 ... 'print y', # print data defined in the function
1876 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print z',
1877 ... 'up', 'print x',
1878 ... 'up', 'print y',
1879 ... 'up', 'print foo',
1880 ... 'continue', # stop debugging
1884 ... runner.run(test)
1886 ... sys.stdin = real_stdin
1887 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1893 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
1896 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
1899 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1903 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
1906 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
1909 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
1914 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1919 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1924 > <doctest foo-bär@baz[1]>(1)<module>()
1925 -> calls_set_trace()
1927 *** NameError: name 'foo' is not defined
1929 TestResults(failed=0, attempted=2)
1932 def test_DocTestSuite():
1933 """DocTestSuite creates a unittest test suite from a doctest.
1935 We create a Suite by providing a module. A module can be provided
1936 by passing a module object:
1939 >>> import test.sample_doctest
1940 >>> suite = doctest.DocTestSuite(test.sample_doctest)
1941 >>> suite.run(unittest.TestResult())
1942 <unittest.result.TestResult run=9 errors=0 failures=4>
1944 We can also supply the module by name:
1946 >>> suite = doctest.DocTestSuite('test.sample_doctest')
1947 >>> suite.run(unittest.TestResult())
1948 <unittest.result.TestResult run=9 errors=0 failures=4>
1950 We can use the current module:
1952 >>> suite = test.sample_doctest.test_suite()
1953 >>> suite.run(unittest.TestResult())
1954 <unittest.result.TestResult run=9 errors=0 failures=4>
1956 We can supply global variables. If we pass globs, they will be
1957 used instead of the module globals. Here we'll pass an empty
1958 globals, triggering an extra error:
1960 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
1961 >>> suite.run(unittest.TestResult())
1962 <unittest.result.TestResult run=9 errors=0 failures=5>
1964 Alternatively, we can provide extra globals. Here we'll make an
1965 error go away by providing an extra global variable:
1967 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1968 ... extraglobs={'y': 1})
1969 >>> suite.run(unittest.TestResult())
1970 <unittest.result.TestResult run=9 errors=0 failures=3>
1972 You can pass option flags. Here we'll cause an extra error
1973 by disabling the blank-line feature:
1975 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1976 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
1977 >>> suite.run(unittest.TestResult())
1978 <unittest.result.TestResult run=9 errors=0 failures=5>
1980 You can supply setUp and tearDown functions:
1983 ... import test.test_doctest
1984 ... test.test_doctest.sillySetup = True
1986 >>> def tearDown(t):
1987 ... import test.test_doctest
1988 ... del test.test_doctest.sillySetup
1990 Here, we installed a silly variable that the test expects:
1992 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1993 ... setUp=setUp, tearDown=tearDown)
1994 >>> suite.run(unittest.TestResult())
1995 <unittest.result.TestResult run=9 errors=0 failures=3>
1997 But the tearDown restores sanity:
1999 >>> import test.test_doctest
2000 >>> test.test_doctest.sillySetup
2001 Traceback (most recent call last):
2003 AttributeError: 'module' object has no attribute 'sillySetup'
2005 The setUp and tearDown funtions are passed test objects. Here
2006 we'll use the setUp function to supply the missing variable y:
2008 >>> def setUp(test):
2009 ... test.globs['y'] = 1
2011 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
2012 >>> suite.run(unittest.TestResult())
2013 <unittest.result.TestResult run=9 errors=0 failures=3>
2015 Here, we didn't need to use a tearDown function because we
2016 modified the test globals, which are a copy of the
2017 sample_doctest module dictionary. The test globals are
2018 automatically cleared for us after a test.
2021 def test_DocFileSuite():
2022 """We can test tests found in text files using a DocFileSuite.
2024 We create a suite by providing the names of one or more text
2025 files that include examples:
2028 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2029 ... 'test_doctest2.txt',
2030 ... 'test_doctest4.txt')
2031 >>> suite.run(unittest.TestResult())
2032 <unittest.result.TestResult run=3 errors=0 failures=3>
2034 The test files are looked for in the directory containing the
2035 calling module. A package keyword argument can be provided to
2036 specify a different relative location.
2039 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2040 ... 'test_doctest2.txt',
2041 ... 'test_doctest4.txt',
2043 >>> suite.run(unittest.TestResult())
2044 <unittest.result.TestResult run=3 errors=0 failures=3>
2046 Support for using a package's __loader__.get_data() is also
2049 >>> import unittest, pkgutil, test
2050 >>> added_loader = False
2051 >>> if not hasattr(test, '__loader__'):
2052 ... test.__loader__ = pkgutil.get_loader(test)
2053 ... added_loader = True
2055 ... suite = doctest.DocFileSuite('test_doctest.txt',
2056 ... 'test_doctest2.txt',
2057 ... 'test_doctest4.txt',
2059 ... suite.run(unittest.TestResult())
2061 ... if added_loader:
2062 ... del test.__loader__
2063 <unittest.result.TestResult run=3 errors=0 failures=3>
2065 '/' should be used as a path separator. It will be converted
2066 to a native separator at run time:
2068 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2069 >>> suite.run(unittest.TestResult())
2070 <unittest.result.TestResult run=1 errors=0 failures=1>
2072 If DocFileSuite is used from an interactive session, then files
2073 are resolved relative to the directory of sys.argv[0]:
2075 >>> import types, os.path, test.test_doctest
2076 >>> save_argv = sys.argv
2077 >>> sys.argv = [test.test_doctest.__file__]
2078 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2079 ... package=types.ModuleType('__main__'))
2080 >>> sys.argv = save_argv
2082 By setting `module_relative=False`, os-specific paths may be
2083 used (including absolute paths and paths relative to the
2086 >>> # Get the absolute path of the test package.
2087 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2088 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
2090 >>> # Use it to find the absolute path of test_doctest.txt.
2091 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2093 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
2094 >>> suite.run(unittest.TestResult())
2095 <unittest.result.TestResult run=1 errors=0 failures=1>
2097 It is an error to specify `package` when `module_relative=False`:
2099 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2101 Traceback (most recent call last):
2102 ValueError: Package may only be specified for module-relative paths.
2104 You can specify initial global variables:
2106 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2107 ... 'test_doctest2.txt',
2108 ... 'test_doctest4.txt',
2109 ... globs={'favorite_color': 'blue'})
2110 >>> suite.run(unittest.TestResult())
2111 <unittest.result.TestResult run=3 errors=0 failures=2>
2113 In this case, we supplied a missing favorite color. You can
2114 provide doctest options:
2116 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2117 ... 'test_doctest2.txt',
2118 ... 'test_doctest4.txt',
2119 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2120 ... globs={'favorite_color': 'blue'})
2121 >>> suite.run(unittest.TestResult())
2122 <unittest.result.TestResult run=3 errors=0 failures=3>
2124 And, you can provide setUp and tearDown functions:
2127 ... import test.test_doctest
2128 ... test.test_doctest.sillySetup = True
2130 >>> def tearDown(t):
2131 ... import test.test_doctest
2132 ... del test.test_doctest.sillySetup
2134 Here, we installed a silly variable that the test expects:
2136 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2137 ... 'test_doctest2.txt',
2138 ... 'test_doctest4.txt',
2139 ... setUp=setUp, tearDown=tearDown)
2140 >>> suite.run(unittest.TestResult())
2141 <unittest.result.TestResult run=3 errors=0 failures=2>
2143 But the tearDown restores sanity:
2145 >>> import test.test_doctest
2146 >>> test.test_doctest.sillySetup
2147 Traceback (most recent call last):
2149 AttributeError: 'module' object has no attribute 'sillySetup'
2151 The setUp and tearDown funtions are passed test objects.
2152 Here, we'll use a setUp function to set the favorite color in
2155 >>> def setUp(test):
2156 ... test.globs['favorite_color'] = 'blue'
2158 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2159 >>> suite.run(unittest.TestResult())
2160 <unittest.result.TestResult run=1 errors=0 failures=0>
2162 Here, we didn't need to use a tearDown function because we
2163 modified the test globals. The test globals are
2164 automatically cleared for us after a test.
2166 Tests in a file run using `DocFileSuite` can also access the
2167 `__file__` global, which is set to the name of the file
2168 containing the tests:
2170 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2171 >>> suite.run(unittest.TestResult())
2172 <unittest.result.TestResult run=1 errors=0 failures=0>
2174 If the tests contain non-ASCII characters, we have to specify which
2175 encoding the file is encoded with. We do so by using the `encoding`
2178 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2179 ... 'test_doctest2.txt',
2180 ... 'test_doctest4.txt',
2181 ... encoding='utf-8')
2182 >>> suite.run(unittest.TestResult())
2183 <unittest.result.TestResult run=3 errors=0 failures=2>
2187 def test_trailing_space_in_test():
2189 Trailing spaces in expected output are significant:
2191 >>> x, y = 'foo', ''
2197 def test_unittest_reportflags():
2198 """Default unittest reporting flags can be set to control reporting
2200 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2201 only the first failure of each test. First, we'll look at the
2202 output without the flag. The file test_doctest.txt file has two
2203 tests. They both fail if blank lines are disabled:
2205 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2206 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2208 >>> result = suite.run(unittest.TestResult())
2209 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2218 Note that we see both failures displayed.
2220 >>> old = doctest.set_unittest_reportflags(
2221 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2223 Now, when we run the test:
2225 >>> result = suite.run(unittest.TestResult())
2226 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2232 NameError: name 'favorite_color' is not defined
2236 We get only the first failure.
2238 If we give any reporting options when we set up the tests,
2241 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2242 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2244 Then the default eporting options are ignored:
2246 >>> result = suite.run(unittest.TestResult())
2247 >>> print result.failures[0][1] # doctest: +ELLIPSIS
2257 Differences (ndiff with -expected +actual):
2266 Test runners can restore the formatting flags after they run:
2268 >>> ignored = doctest.set_unittest_reportflags(old)
2272 def test_testfile(): r
"""
2273 Tests for the `testfile()` function. This function runs all the
2274 doctest examples in a given file. In its simple invokation, it is
2275 called with the name of a file, which is taken to be relative to the
2276 calling module. The return value is (#failures, #tests).
2278 We don't want `-v` in sys.argv for these tests.
2280 >>> save_argv = sys.argv
2281 >>> if '-v' in sys.argv:
2282 ... sys.argv = [arg for arg in save_argv if arg != '-v']
2285 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2286 **********************************************************************
2287 File "...", line 6, in test_doctest.txt
2292 NameError: name 'favorite_color' is not defined
2293 **********************************************************************
2294 1 items had failures:
2295 1 of 2 in test_doctest.txt
2296 ***Test Failed*** 1 failures.
2297 TestResults(failed=1, attempted=2)
2298 >>> doctest.master = None # Reset master.
2300 (Note: we'll be clearing doctest.master after each call to
2301 `doctest.testfile`, to suppress warnings about multiple tests with the
2304 Globals may be specified with the `globs` and `extraglobs` parameters:
2306 >>> globs = {'favorite_color': 'blue'}
2307 >>> doctest.testfile('test_doctest.txt', globs=globs)
2308 TestResults(failed=0, attempted=2)
2309 >>> doctest.master = None # Reset master.
2311 >>> extraglobs = {'favorite_color': 'red'}
2312 >>> doctest.testfile('test_doctest.txt', globs=globs,
2313 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2314 **********************************************************************
2315 File "...", line 6, in test_doctest.txt
2322 **********************************************************************
2323 1 items had failures:
2324 1 of 2 in test_doctest.txt
2325 ***Test Failed*** 1 failures.
2326 TestResults(failed=1, attempted=2)
2327 >>> doctest.master = None # Reset master.
2329 The file may be made relative to a given module or package, using the
2330 optional `module_relative` parameter:
2332 >>> doctest.testfile('test_doctest.txt', globs=globs,
2333 ... module_relative='test')
2334 TestResults(failed=0, attempted=2)
2335 >>> doctest.master = None # Reset master.
2337 Verbosity can be increased with the optional `verbose` parameter:
2339 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2355 1 items passed all tests:
2356 2 tests in test_doctest.txt
2358 2 passed and 0 failed.
2360 TestResults(failed=0, attempted=2)
2361 >>> doctest.master = None # Reset master.
2363 The name of the test may be specified with the optional `name`
2366 >>> doctest.testfile('test_doctest.txt', name='newname')
2367 ... # doctest: +ELLIPSIS
2368 **********************************************************************
2369 File "...", line 6, in newname
2371 TestResults(failed=1, attempted=2)
2372 >>> doctest.master = None # Reset master.
2374 The summary report may be suppressed with the optional `report`
2377 >>> doctest.testfile('test_doctest.txt', report=False)
2378 ... # doctest: +ELLIPSIS
2379 **********************************************************************
2380 File "...", line 6, in test_doctest.txt
2385 NameError: name 'favorite_color' is not defined
2386 TestResults(failed=1, attempted=2)
2387 >>> doctest.master = None # Reset master.
2389 The optional keyword argument `raise_on_error` can be used to raise an
2390 exception on the first error (which may be useful for postmortem
2393 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2394 ... # doctest: +ELLIPSIS
2395 Traceback (most recent call last):
2396 UnexpectedException: ...
2397 >>> doctest.master = None # Reset master.
2399 If the tests contain non-ASCII characters, the tests might fail, since
2400 it's unknown which encoding is used. The encoding can be specified
2401 using the optional keyword argument `encoding`:
2403 >>> doctest.testfile('test_doctest4.txt') # doctest: +ELLIPSIS
2404 **********************************************************************
2405 File "...", line 7, in test_doctest4.txt
2411 u'f\xc3\xb6\xc3\xb6'
2412 **********************************************************************
2414 **********************************************************************
2415 1 items had failures:
2416 2 of 4 in test_doctest4.txt
2417 ***Test Failed*** 2 failures.
2418 TestResults(failed=2, attempted=4)
2419 >>> doctest.master = None # Reset master.
2421 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2422 TestResults(failed=0, attempted=4)
2423 >>> doctest.master = None # Reset master.
2425 Switch the module encoding to 'utf-8' to test the verbose output without
2426 bothering with the current sys.stdout encoding.
2428 >>> doctest._encoding, saved_encoding = 'utf-8', doctest._encoding
2429 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2450 1 items passed all tests:
2451 4 tests in test_doctest4.txt
2453 4 passed and 0 failed.
2455 TestResults(failed=0, attempted=4)
2456 >>> doctest._encoding = saved_encoding
2457 >>> doctest.master = None # Reset master.
2458 >>> sys.argv = save_argv
2461 # old_test1, ... used to live in doctest.py, but cluttered it. Note
2462 # that these use the deprecated doctest.Tester, so should go away (or
2463 # be rewritten) someday.
2465 def old_test1(): r
"""
2466 >>> from doctest import Tester
2467 >>> t = Tester(globs={'x': 42}, verbose=0)
2468 >>> t.runstring(r'''
2473 **********************************************************************
2481 TestResults(failed=1, attempted=2)
2482 >>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
2483 TestResults(failed=0, attempted=2)
2485 **********************************************************************
2486 1 items had failures:
2488 ***Test Failed*** 1 failures.
2489 TestResults(failed=1, attempted=4)
2490 >>> t.summarize(verbose=1)
2491 1 items passed all tests:
2493 **********************************************************************
2494 1 items had failures:
2497 3 passed and 1 failed.
2498 ***Test Failed*** 1 failures.
2499 TestResults(failed=1, attempted=4)
2502 def old_test2(): r
"""
2503 >>> from doctest import Tester
2504 >>> t = Tester(globs={}, verbose=1)
2506 ... # just an example
2511 >>> t.runstring(test, "Example")
2512 Running string Example
2522 0 of 2 examples failed in string Example
2523 TestResults(failed=0, attempted=2)
2526 def old_test3(): r
"""
2527 >>> from doctest import Tester
2528 >>> t = Tester(globs={}, verbose=0)
2530 ... '''Trivial docstring example.
2531 ... >>> assert 2 == 2
2535 >>> t.rundoc(_f) # expect 0 failures in 1 example
2536 TestResults(failed=0, attempted=1)
2539 def old_test4(): """
2541 >>> m1 = types.ModuleType('_m1')
2542 >>> m2 = types.ModuleType('_m2')
2543 >>> test_data = \"""
2545 ... '''>>> assert 1 == 1
2548 ... '''>>> assert 2 != 1
2551 ... '''>>> assert 2 > 1
2554 ... '''>>> assert 1 < 2
2557 >>> exec test_data in m1.__dict__
2558 >>> exec test_data in m2.__dict__
2559 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
2561 Tests that objects outside m1 are excluded:
2563 >>> from doctest import Tester
2564 >>> t = Tester(globs={}, verbose=0)
2565 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
2566 TestResults(failed=0, attempted=4)
2568 Once more, not excluding stuff outside m1:
2570 >>> t = Tester(globs={}, verbose=0)
2571 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
2572 TestResults(failed=0, attempted=8)
2574 The exclusion of objects from outside the designated module is
2575 meant to be invoked automagically by testmod.
2577 >>> doctest.testmod(m1, verbose=False)
2578 TestResults(failed=0, attempted=4)
2581 ######################################################################
2583 ######################################################################
2586 # Check the doctest cases in doctest itself:
2587 test_support
.run_doctest(doctest
, verbosity
=True)
2589 from test
import test_doctest
2591 # Ignore all warnings about the use of class Tester in this module.
2592 deprecations
= [("class Tester is deprecated", DeprecationWarning)]
2594 deprecations
+= [("backquote not supported", SyntaxWarning),
2595 ("execfile.. not supported", DeprecationWarning)]
2596 with test_support
.check_warnings(*deprecations
):
2597 # Check the doctest cases defined here:
2598 test_support
.run_doctest(test_doctest
, verbosity
=True)
2601 def test_coverage(coverdir
):
2602 trace
= test_support
.import_module('trace')
2603 tracer
= trace
.Trace(ignoredirs
=[sys
.prefix
, sys
.exec_prefix
,],
2605 tracer
.run('reload(doctest); test_main()')
2606 r
= tracer
.results()
2607 print 'Writing coverage results...'
2608 r
.write_results(show_missing
=True, summary
=True,
2611 if __name__
== '__main__':
2612 if '-c' in sys
.argv
:
2613 test_coverage('/tmp/doctest.cover')