python (3.12.0)
1 """
2 Test script for doctest.
3 """
4
5 from test import support
6 from test.support import import_helper
7 import doctest
8 import functools
9 import os
10 import sys
11 import importlib
12 import importlib.abc
13 import importlib.util
14 import unittest
15 import tempfile
16 import types
17 import contextlib
18
19
20 if not support.has_subprocess_support:
21 raise unittest.SkipTest("test_CLI requires subprocess support.")
22
23
24 # NOTE: There are some additional tests relating to interaction with
25 # zipimport in the test_zipimport_support test module.
26 # There are also related tests in `test_doctest2` module.
27
28 ######################################################################
29 ## Sample Objects (used by test cases)
30 ######################################################################
31
32 def sample_func(v):
33 """
34 Blah blah
35
36 >>> print(sample_func(22))
37 44
38
39 Yee ha!
40 """
41 return v+v
42
43 class ESC[4;38;5;81mSampleClass:
44 """
45 >>> print(1)
46 1
47
48 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
49 >>>
50 ...
51
52 Multiline example:
53 >>> sc = SampleClass(3)
54 >>> for i in range(10):
55 ... sc = sc.double()
56 ... print(' ', sc.get(), sep='', end='')
57 6 12 24 48 96 192 384 768 1536 3072
58 """
59 def __init__(self, val):
60 """
61 >>> print(SampleClass(12).get())
62 12
63 """
64 self.val = val
65
66 def double(self):
67 """
68 >>> print(SampleClass(12).double().get())
69 24
70 """
71 return SampleClass(self.val + self.val)
72
73 def get(self):
74 """
75 >>> print(SampleClass(-5).get())
76 -5
77 """
78 return self.val
79
80 def a_staticmethod(v):
81 """
82 >>> print(SampleClass.a_staticmethod(10))
83 11
84 """
85 return v+1
86 a_staticmethod = staticmethod(a_staticmethod)
87
88 def a_classmethod(cls, v):
89 """
90 >>> print(SampleClass.a_classmethod(10))
91 12
92 >>> print(SampleClass(0).a_classmethod(10))
93 12
94 """
95 return v+2
96 a_classmethod = classmethod(a_classmethod)
97
98 a_property = property(get, doc="""
99 >>> print(SampleClass(22).a_property)
100 22
101 """)
102
103 a_class_attribute = 42
104
105 @classmethod
106 @property
107 def a_classmethod_property(cls):
108 """
109 >>> print(SampleClass.a_classmethod_property)
110 42
111 """
112 return cls.a_class_attribute
113
114 class ESC[4;38;5;81mNestedClass:
115 """
116 >>> x = SampleClass.NestedClass(5)
117 >>> y = x.square()
118 >>> print(y.get())
119 25
120 """
121 def __init__(self, val=0):
122 """
123 >>> print(SampleClass.NestedClass().get())
124 0
125 """
126 self.val = val
127 def square(self):
128 return SampleClass.NestedClass(self.val*self.val)
129 def get(self):
130 return self.val
131
132 class ESC[4;38;5;81mSampleNewStyleClass(ESC[4;38;5;149mobject):
133 r"""
134 >>> print('1\n2\n3')
135 1
136 2
137 3
138 """
139 def __init__(self, val):
140 """
141 >>> print(SampleNewStyleClass(12).get())
142 12
143 """
144 self.val = val
145
146 def double(self):
147 """
148 >>> print(SampleNewStyleClass(12).double().get())
149 24
150 """
151 return SampleNewStyleClass(self.val + self.val)
152
153 def get(self):
154 """
155 >>> print(SampleNewStyleClass(-5).get())
156 -5
157 """
158 return self.val
159
160 ######################################################################
161 ## Fake stdin (for testing interactive debugging)
162 ######################################################################
163
164 class ESC[4;38;5;81m_FakeInput:
165 """
166 A fake input stream for pdb's interactive debugger. Whenever a
167 line is read, print it (to simulate the user typing it), and then
168 return it. The set of lines to return is specified in the
169 constructor; they should not have trailing newlines.
170 """
171 def __init__(self, lines):
172 self.lines = lines
173
174 def readline(self):
175 line = self.lines.pop(0)
176 print(line)
177 return line+'\n'
178
179 ######################################################################
180 ## Test Cases
181 ######################################################################
182
183 def test_Example(): r"""
184 Unit tests for the `Example` class.
185
186 Example is a simple container class that holds:
187 - `source`: A source string.
188 - `want`: An expected output string.
189 - `exc_msg`: An expected exception message string (or None if no
190 exception is expected).
191 - `lineno`: A line number (within the docstring).
192 - `indent`: The example's indentation in the input string.
193 - `options`: An option dictionary, mapping option flags to True or
194 False.
195
196 These attributes are set by the constructor. `source` and `want` are
197 required; the other attributes all have default values:
198
199 >>> example = doctest.Example('print(1)', '1\n')
200 >>> (example.source, example.want, example.exc_msg,
201 ... example.lineno, example.indent, example.options)
202 ('print(1)\n', '1\n', None, 0, 0, {})
203
204 The first three attributes (`source`, `want`, and `exc_msg`) may be
205 specified positionally; the remaining arguments should be specified as
206 keyword arguments:
207
208 >>> exc_msg = 'IndexError: pop from an empty list'
209 >>> example = doctest.Example('[].pop()', '', exc_msg,
210 ... lineno=5, indent=4,
211 ... options={doctest.ELLIPSIS: True})
212 >>> (example.source, example.want, example.exc_msg,
213 ... example.lineno, example.indent, example.options)
214 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
215
216 The constructor normalizes the `source` string to end in a newline:
217
218 Source spans a single line: no terminating newline.
219 >>> e = doctest.Example('print(1)', '1\n')
220 >>> e.source, e.want
221 ('print(1)\n', '1\n')
222
223 >>> e = doctest.Example('print(1)\n', '1\n')
224 >>> e.source, e.want
225 ('print(1)\n', '1\n')
226
227 Source spans multiple lines: require terminating newline.
228 >>> e = doctest.Example('print(1);\nprint(2)\n', '1\n2\n')
229 >>> e.source, e.want
230 ('print(1);\nprint(2)\n', '1\n2\n')
231
232 >>> e = doctest.Example('print(1);\nprint(2)', '1\n2\n')
233 >>> e.source, e.want
234 ('print(1);\nprint(2)\n', '1\n2\n')
235
236 Empty source string (which should never appear in real examples)
237 >>> e = doctest.Example('', '')
238 >>> e.source, e.want
239 ('\n', '')
240
241 The constructor normalizes the `want` string to end in a newline,
242 unless it's the empty string:
243
244 >>> e = doctest.Example('print(1)', '1\n')
245 >>> e.source, e.want
246 ('print(1)\n', '1\n')
247
248 >>> e = doctest.Example('print(1)', '1')
249 >>> e.source, e.want
250 ('print(1)\n', '1\n')
251
252 >>> e = doctest.Example('print', '')
253 >>> e.source, e.want
254 ('print\n', '')
255
256 The constructor normalizes the `exc_msg` string to end in a newline,
257 unless it's `None`:
258
259 Message spans one line
260 >>> exc_msg = 'IndexError: pop from an empty list'
261 >>> e = doctest.Example('[].pop()', '', exc_msg)
262 >>> e.exc_msg
263 'IndexError: pop from an empty list\n'
264
265 >>> exc_msg = 'IndexError: pop from an empty list\n'
266 >>> e = doctest.Example('[].pop()', '', exc_msg)
267 >>> e.exc_msg
268 'IndexError: pop from an empty list\n'
269
270 Message spans multiple lines
271 >>> exc_msg = 'ValueError: 1\n 2'
272 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
273 >>> e.exc_msg
274 'ValueError: 1\n 2\n'
275
276 >>> exc_msg = 'ValueError: 1\n 2\n'
277 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
278 >>> e.exc_msg
279 'ValueError: 1\n 2\n'
280
281 Empty (but non-None) exception message (which should never appear
282 in real examples)
283 >>> exc_msg = ''
284 >>> e = doctest.Example('raise X()', '', exc_msg)
285 >>> e.exc_msg
286 '\n'
287
288 Compare `Example`:
289 >>> example = doctest.Example('print 1', '1\n')
290 >>> same_example = doctest.Example('print 1', '1\n')
291 >>> other_example = doctest.Example('print 42', '42\n')
292 >>> example == same_example
293 True
294 >>> example != same_example
295 False
296 >>> hash(example) == hash(same_example)
297 True
298 >>> example == other_example
299 False
300 >>> example != other_example
301 True
302 """
303
304 def test_DocTest(): r"""
305 Unit tests for the `DocTest` class.
306
307 DocTest is a collection of examples, extracted from a docstring, along
308 with information about where the docstring comes from (a name,
309 filename, and line number). The docstring is parsed by the `DocTest`
310 constructor:
311
312 >>> docstring = '''
313 ... >>> print(12)
314 ... 12
315 ...
316 ... Non-example text.
317 ...
318 ... >>> print('another\\example')
319 ... another
320 ... example
321 ... '''
322 >>> globs = {} # globals to run the test in.
323 >>> parser = doctest.DocTestParser()
324 >>> test = parser.get_doctest(docstring, globs, 'some_test',
325 ... 'some_file', 20)
326 >>> print(test)
327 <DocTest some_test from some_file:20 (2 examples)>
328 >>> len(test.examples)
329 2
330 >>> e1, e2 = test.examples
331 >>> (e1.source, e1.want, e1.lineno)
332 ('print(12)\n', '12\n', 1)
333 >>> (e2.source, e2.want, e2.lineno)
334 ("print('another\\example')\n", 'another\nexample\n', 6)
335
336 Source information (name, filename, and line number) is available as
337 attributes on the doctest object:
338
339 >>> (test.name, test.filename, test.lineno)
340 ('some_test', 'some_file', 20)
341
342 The line number of an example within its containing file is found by
343 adding the line number of the example and the line number of its
344 containing test:
345
346 >>> test.lineno + e1.lineno
347 21
348 >>> test.lineno + e2.lineno
349 26
350
351 If the docstring contains inconsistent leading whitespace in the
352 expected output of an example, then `DocTest` will raise a ValueError:
353
354 >>> docstring = r'''
355 ... >>> print('bad\nindentation')
356 ... bad
357 ... indentation
358 ... '''
359 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
360 Traceback (most recent call last):
361 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
362
363 If the docstring contains inconsistent leading whitespace on
364 continuation lines, then `DocTest` will raise a ValueError:
365
366 >>> docstring = r'''
367 ... >>> print(('bad indentation',
368 ... ... 2))
369 ... ('bad', 'indentation')
370 ... '''
371 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
372 Traceback (most recent call last):
373 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2))'
374
375 If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
376 will raise a ValueError:
377
378 >>> docstring = '>>>print(1)\n1'
379 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
380 Traceback (most recent call last):
381 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print(1)'
382
383 If there's no blank space after a PS2 prompt ('...'), then `DocTest`
384 will raise a ValueError:
385
386 >>> docstring = '>>> if 1:\n...print(1)\n1'
387 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
388 Traceback (most recent call last):
389 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print(1)'
390
391 Compare `DocTest`:
392
393 >>> docstring = '''
394 ... >>> print 12
395 ... 12
396 ... '''
397 >>> test = parser.get_doctest(docstring, globs, 'some_test',
398 ... 'some_test', 20)
399 >>> same_test = parser.get_doctest(docstring, globs, 'some_test',
400 ... 'some_test', 20)
401 >>> test == same_test
402 True
403 >>> test != same_test
404 False
405 >>> hash(test) == hash(same_test)
406 True
407 >>> docstring = '''
408 ... >>> print 42
409 ... 42
410 ... '''
411 >>> other_test = parser.get_doctest(docstring, globs, 'other_test',
412 ... 'other_file', 10)
413 >>> test == other_test
414 False
415 >>> test != other_test
416 True
417
418 Compare `DocTestCase`:
419
420 >>> DocTestCase = doctest.DocTestCase
421 >>> test_case = DocTestCase(test)
422 >>> same_test_case = DocTestCase(same_test)
423 >>> other_test_case = DocTestCase(other_test)
424 >>> test_case == same_test_case
425 True
426 >>> test_case != same_test_case
427 False
428 >>> hash(test_case) == hash(same_test_case)
429 True
430 >>> test == other_test_case
431 False
432 >>> test != other_test_case
433 True
434
435 """
436
437 class ESC[4;38;5;81mtest_DocTestFinder:
438 def basics(): r"""
439 Unit tests for the `DocTestFinder` class.
440
441 DocTestFinder is used to extract DocTests from an object's docstring
442 and the docstrings of its contained objects. It can be used with
443 modules, functions, classes, methods, staticmethods, classmethods, and
444 properties.
445
446 Finding Tests in Functions
447 ~~~~~~~~~~~~~~~~~~~~~~~~~~
448 For a function whose docstring contains examples, DocTestFinder.find()
449 will return a single test (for that function's docstring):
450
451 >>> finder = doctest.DocTestFinder()
452
453 We'll simulate a __file__ attr that ends in pyc:
454
455 >>> import test.test_doctest
456 >>> old = test.test_doctest.__file__
457 >>> test.test_doctest.__file__ = 'test_doctest.pyc'
458
459 >>> tests = finder.find(sample_func)
460
461 >>> print(tests) # doctest: +ELLIPSIS
462 [<DocTest sample_func from test_doctest.py:32 (1 example)>]
463
464 The exact name depends on how test_doctest was invoked, so allow for
465 leading path components.
466
467 >>> tests[0].filename # doctest: +ELLIPSIS
468 '...test_doctest.py'
469
470 >>> test.test_doctest.__file__ = old
471
472
473 >>> e = tests[0].examples[0]
474 >>> (e.source, e.want, e.lineno)
475 ('print(sample_func(22))\n', '44\n', 3)
476
477 By default, tests are created for objects with no docstring:
478
479 >>> def no_docstring(v):
480 ... pass
481 >>> finder.find(no_docstring)
482 []
483
484 However, the optional argument `exclude_empty` to the DocTestFinder
485 constructor can be used to exclude tests for objects with empty
486 docstrings:
487
488 >>> def no_docstring(v):
489 ... pass
490 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
491 >>> excl_empty_finder.find(no_docstring)
492 []
493
494 If the function has a docstring with no examples, then a test with no
495 examples is returned. (This lets `DocTestRunner` collect statistics
496 about which functions have no tests -- but is that useful? And should
497 an empty test also be created when there's no docstring?)
498
499 >>> def no_examples(v):
500 ... ''' no doctest examples '''
501 >>> finder.find(no_examples) # doctest: +ELLIPSIS
502 [<DocTest no_examples from ...:1 (no examples)>]
503
504 Finding Tests in Classes
505 ~~~~~~~~~~~~~~~~~~~~~~~~
506 For a class, DocTestFinder will create a test for the class's
507 docstring, and will recursively explore its contents, including
508 methods, classmethods, staticmethods, properties, and nested classes.
509
510 >>> finder = doctest.DocTestFinder()
511 >>> tests = finder.find(SampleClass)
512 >>> for t in tests:
513 ... print('%2s %s' % (len(t.examples), t.name))
514 3 SampleClass
515 3 SampleClass.NestedClass
516 1 SampleClass.NestedClass.__init__
517 1 SampleClass.__init__
518 2 SampleClass.a_classmethod
519 1 SampleClass.a_classmethod_property
520 1 SampleClass.a_property
521 1 SampleClass.a_staticmethod
522 1 SampleClass.double
523 1 SampleClass.get
524
525 New-style classes are also supported:
526
527 >>> tests = finder.find(SampleNewStyleClass)
528 >>> for t in tests:
529 ... print('%2s %s' % (len(t.examples), t.name))
530 1 SampleNewStyleClass
531 1 SampleNewStyleClass.__init__
532 1 SampleNewStyleClass.double
533 1 SampleNewStyleClass.get
534
535 Finding Tests in Modules
536 ~~~~~~~~~~~~~~~~~~~~~~~~
537 For a module, DocTestFinder will create a test for the class's
538 docstring, and will recursively explore its contents, including
539 functions, classes, and the `__test__` dictionary, if it exists:
540
541 >>> # A module
542 >>> import types
543 >>> m = types.ModuleType('some_module')
544 >>> def triple(val):
545 ... '''
546 ... >>> print(triple(11))
547 ... 33
548 ... '''
549 ... return val*3
550 >>> m.__dict__.update({
551 ... 'sample_func': sample_func,
552 ... 'SampleClass': SampleClass,
553 ... '__doc__': '''
554 ... Module docstring.
555 ... >>> print('module')
556 ... module
557 ... ''',
558 ... '__test__': {
559 ... 'd': '>>> print(6)\n6\n>>> print(7)\n7\n',
560 ... 'c': triple}})
561
562 >>> finder = doctest.DocTestFinder()
563 >>> # Use module=test.test_doctest, to prevent doctest from
564 >>> # ignoring the objects since they weren't defined in m.
565 >>> import test.test_doctest
566 >>> tests = finder.find(m, module=test.test_doctest)
567 >>> for t in tests:
568 ... print('%2s %s' % (len(t.examples), t.name))
569 1 some_module
570 3 some_module.SampleClass
571 3 some_module.SampleClass.NestedClass
572 1 some_module.SampleClass.NestedClass.__init__
573 1 some_module.SampleClass.__init__
574 2 some_module.SampleClass.a_classmethod
575 1 some_module.SampleClass.a_classmethod_property
576 1 some_module.SampleClass.a_property
577 1 some_module.SampleClass.a_staticmethod
578 1 some_module.SampleClass.double
579 1 some_module.SampleClass.get
580 1 some_module.__test__.c
581 2 some_module.__test__.d
582 1 some_module.sample_func
583
584 Duplicate Removal
585 ~~~~~~~~~~~~~~~~~
586 If a single object is listed twice (under different names), then tests
587 will only be generated for it once:
588
589 >>> from test import doctest_aliases
590 >>> assert doctest_aliases.TwoNames.f
591 >>> assert doctest_aliases.TwoNames.g
592 >>> tests = excl_empty_finder.find(doctest_aliases)
593 >>> print(len(tests))
594 2
595 >>> print(tests[0].name)
596 test.doctest_aliases.TwoNames
597
598 TwoNames.f and TwoNames.g are bound to the same object.
599 We can't guess which will be found in doctest's traversal of
600 TwoNames.__dict__ first, so we have to allow for either.
601
602 >>> tests[1].name.split('.')[-1] in ['f', 'g']
603 True
604
605 Empty Tests
606 ~~~~~~~~~~~
607 By default, an object with no doctests doesn't create any tests:
608
609 >>> tests = doctest.DocTestFinder().find(SampleClass)
610 >>> for t in tests:
611 ... print('%2s %s' % (len(t.examples), t.name))
612 3 SampleClass
613 3 SampleClass.NestedClass
614 1 SampleClass.NestedClass.__init__
615 1 SampleClass.__init__
616 2 SampleClass.a_classmethod
617 1 SampleClass.a_classmethod_property
618 1 SampleClass.a_property
619 1 SampleClass.a_staticmethod
620 1 SampleClass.double
621 1 SampleClass.get
622
623 By default, that excluded objects with no doctests. exclude_empty=False
624 tells it to include (empty) tests for objects with no doctests. This feature
625 is really to support backward compatibility in what doctest.master.summarize()
626 displays.
627
628 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
629 >>> for t in tests:
630 ... print('%2s %s' % (len(t.examples), t.name))
631 3 SampleClass
632 3 SampleClass.NestedClass
633 1 SampleClass.NestedClass.__init__
634 0 SampleClass.NestedClass.get
635 0 SampleClass.NestedClass.square
636 1 SampleClass.__init__
637 2 SampleClass.a_classmethod
638 1 SampleClass.a_classmethod_property
639 1 SampleClass.a_property
640 1 SampleClass.a_staticmethod
641 1 SampleClass.double
642 1 SampleClass.get
643
644 When used with `exclude_empty=False` we are also interested in line numbers
645 of doctests that are empty.
646 It used to be broken for quite some time until `bpo-28249`.
647
648 >>> from test import doctest_lineno
649 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(doctest_lineno)
650 >>> for t in tests:
651 ... print('%5s %s' % (t.lineno, t.name))
652 None test.doctest_lineno
653 22 test.doctest_lineno.ClassWithDocstring
654 30 test.doctest_lineno.ClassWithDoctest
655 None test.doctest_lineno.ClassWithoutDocstring
656 None test.doctest_lineno.MethodWrapper
657 39 test.doctest_lineno.MethodWrapper.method_with_docstring
658 45 test.doctest_lineno.MethodWrapper.method_with_doctest
659 None test.doctest_lineno.MethodWrapper.method_without_docstring
660 4 test.doctest_lineno.func_with_docstring
661 12 test.doctest_lineno.func_with_doctest
662 None test.doctest_lineno.func_without_docstring
663
664 Turning off Recursion
665 ~~~~~~~~~~~~~~~~~~~~~
666 DocTestFinder can be told not to look for tests in contained objects
667 using the `recurse` flag:
668
669 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
670 >>> for t in tests:
671 ... print('%2s %s' % (len(t.examples), t.name))
672 3 SampleClass
673
674 Line numbers
675 ~~~~~~~~~~~~
676 DocTestFinder finds the line number of each example:
677
678 >>> def f(x):
679 ... '''
680 ... >>> x = 12
681 ...
682 ... some text
683 ...
684 ... >>> # examples are not created for comments & bare prompts.
685 ... >>>
686 ... ...
687 ...
688 ... >>> for x in range(10):
689 ... ... print(x, end=' ')
690 ... 0 1 2 3 4 5 6 7 8 9
691 ... >>> x//2
692 ... 6
693 ... '''
694 >>> test = doctest.DocTestFinder().find(f)[0]
695 >>> [e.lineno for e in test.examples]
696 [1, 9, 12]
697 """
698
699 if int.__doc__: # simple check for --without-doc-strings, skip if lacking
700 def non_Python_modules(): r"""
701
702 Finding Doctests in Modules Not Written in Python
703 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
704 DocTestFinder can also find doctests in most modules not written in Python.
705 We'll use builtins as an example, since it almost certainly isn't written in
706 plain ol' Python and is guaranteed to be available.
707
708 >>> import builtins
709 >>> tests = doctest.DocTestFinder().find(builtins)
710 >>> 830 < len(tests) < 860 # approximate number of objects with docstrings
711 True
712 >>> real_tests = [t for t in tests if len(t.examples) > 0]
713 >>> len(real_tests) # objects that actually have doctests
714 14
715 >>> for t in real_tests:
716 ... print('{} {}'.format(len(t.examples), t.name))
717 ...
718 1 builtins.bin
719 5 builtins.bytearray.hex
720 5 builtins.bytes.hex
721 3 builtins.float.as_integer_ratio
722 2 builtins.float.fromhex
723 2 builtins.float.hex
724 1 builtins.hex
725 1 builtins.int
726 3 builtins.int.as_integer_ratio
727 2 builtins.int.bit_count
728 2 builtins.int.bit_length
729 5 builtins.memoryview.hex
730 1 builtins.oct
731 1 builtins.zip
732
733 Note here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',
734 'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,
735 and 'int' is a type.
736 """
737
738
739 class ESC[4;38;5;81mTestDocTestFinder(ESC[4;38;5;149munittestESC[4;38;5;149m.ESC[4;38;5;149mTestCase):
740
741 def test_issue35753(self):
742 # This import of `call` should trigger issue35753 when
743 # DocTestFinder.find() is called due to inspect.unwrap() failing,
744 # however with a patched doctest this should succeed.
745 from unittest.mock import call
746 dummy_module = types.ModuleType("dummy")
747 dummy_module.__dict__['inject_call'] = call
748 finder = doctest.DocTestFinder()
749 self.assertEqual(finder.find(dummy_module), [])
750
751 def test_empty_namespace_package(self):
752 pkg_name = 'doctest_empty_pkg'
753 with tempfile.TemporaryDirectory() as parent_dir:
754 pkg_dir = os.path.join(parent_dir, pkg_name)
755 os.mkdir(pkg_dir)
756 sys.path.append(parent_dir)
757 try:
758 mod = importlib.import_module(pkg_name)
759 finally:
760 import_helper.forget(pkg_name)
761 sys.path.pop()
762
763 include_empty_finder = doctest.DocTestFinder(exclude_empty=False)
764 exclude_empty_finder = doctest.DocTestFinder(exclude_empty=True)
765
766 self.assertEqual(len(include_empty_finder.find(mod)), 1)
767 self.assertEqual(len(exclude_empty_finder.find(mod)), 0)
768
769 def test_DocTestParser(): r"""
770 Unit tests for the `DocTestParser` class.
771
772 DocTestParser is used to parse docstrings containing doctest examples.
773
774 The `parse` method divides a docstring into examples and intervening
775 text:
776
777 >>> s = '''
778 ... >>> x, y = 2, 3 # no output expected
779 ... >>> if 1:
780 ... ... print(x)
781 ... ... print(y)
782 ... 2
783 ... 3
784 ...
785 ... Some text.
786 ... >>> x+y
787 ... 5
788 ... '''
789 >>> parser = doctest.DocTestParser()
790 >>> for piece in parser.parse(s):
791 ... if isinstance(piece, doctest.Example):
792 ... print('Example:', (piece.source, piece.want, piece.lineno))
793 ... else:
794 ... print(' Text:', repr(piece))
795 Text: '\n'
796 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
797 Text: ''
798 Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
799 Text: '\nSome text.\n'
800 Example: ('x+y\n', '5\n', 9)
801 Text: ''
802
803 The `get_examples` method returns just the examples:
804
805 >>> for piece in parser.get_examples(s):
806 ... print((piece.source, piece.want, piece.lineno))
807 ('x, y = 2, 3 # no output expected\n', '', 1)
808 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
809 ('x+y\n', '5\n', 9)
810
811 The `get_doctest` method creates a Test from the examples, along with the
812 given arguments:
813
814 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
815 >>> (test.name, test.filename, test.lineno)
816 ('name', 'filename', 5)
817 >>> for piece in test.examples:
818 ... print((piece.source, piece.want, piece.lineno))
819 ('x, y = 2, 3 # no output expected\n', '', 1)
820 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
821 ('x+y\n', '5\n', 9)
822 """
823
824 class ESC[4;38;5;81mtest_DocTestRunner:
825 def basics(): r"""
826 Unit tests for the `DocTestRunner` class.
827
828 DocTestRunner is used to run DocTest test cases, and to accumulate
829 statistics. Here's a simple DocTest case we can use:
830
831 >>> def f(x):
832 ... '''
833 ... >>> x = 12
834 ... >>> print(x)
835 ... 12
836 ... >>> x//2
837 ... 6
838 ... '''
839 >>> test = doctest.DocTestFinder().find(f)[0]
840
841 The main DocTestRunner interface is the `run` method, which runs a
842 given DocTest case in a given namespace (globs). It returns a tuple
843 `(f,t)`, where `f` is the number of failed tests and `t` is the number
844 of tried tests.
845
846 >>> doctest.DocTestRunner(verbose=False).run(test)
847 TestResults(failed=0, attempted=3)
848
849 If any example produces incorrect output, then the test runner reports
850 the failure and proceeds to the next example:
851
852 >>> def f(x):
853 ... '''
854 ... >>> x = 12
855 ... >>> print(x)
856 ... 14
857 ... >>> x//2
858 ... 6
859 ... '''
860 >>> test = doctest.DocTestFinder().find(f)[0]
861 >>> doctest.DocTestRunner(verbose=True).run(test)
862 ... # doctest: +ELLIPSIS
863 Trying:
864 x = 12
865 Expecting nothing
866 ok
867 Trying:
868 print(x)
869 Expecting:
870 14
871 **********************************************************************
872 File ..., line 4, in f
873 Failed example:
874 print(x)
875 Expected:
876 14
877 Got:
878 12
879 Trying:
880 x//2
881 Expecting:
882 6
883 ok
884 TestResults(failed=1, attempted=3)
885 """
886 def verbose_flag(): r"""
887 The `verbose` flag makes the test runner generate more detailed
888 output:
889
890 >>> def f(x):
891 ... '''
892 ... >>> x = 12
893 ... >>> print(x)
894 ... 12
895 ... >>> x//2
896 ... 6
897 ... '''
898 >>> test = doctest.DocTestFinder().find(f)[0]
899
900 >>> doctest.DocTestRunner(verbose=True).run(test)
901 Trying:
902 x = 12
903 Expecting nothing
904 ok
905 Trying:
906 print(x)
907 Expecting:
908 12
909 ok
910 Trying:
911 x//2
912 Expecting:
913 6
914 ok
915 TestResults(failed=0, attempted=3)
916
917 If the `verbose` flag is unspecified, then the output will be verbose
918 iff `-v` appears in sys.argv:
919
920 >>> # Save the real sys.argv list.
921 >>> old_argv = sys.argv
922
923 >>> # If -v does not appear in sys.argv, then output isn't verbose.
924 >>> sys.argv = ['test']
925 >>> doctest.DocTestRunner().run(test)
926 TestResults(failed=0, attempted=3)
927
928 >>> # If -v does appear in sys.argv, then output is verbose.
929 >>> sys.argv = ['test', '-v']
930 >>> doctest.DocTestRunner().run(test)
931 Trying:
932 x = 12
933 Expecting nothing
934 ok
935 Trying:
936 print(x)
937 Expecting:
938 12
939 ok
940 Trying:
941 x//2
942 Expecting:
943 6
944 ok
945 TestResults(failed=0, attempted=3)
946
947 >>> # Restore sys.argv
948 >>> sys.argv = old_argv
949
950 In the remaining examples, the test runner's verbosity will be
951 explicitly set, to ensure that the test behavior is consistent.
952 """
953 def exceptions(): r"""
954 Tests of `DocTestRunner`'s exception handling.
955
956 An expected exception is specified with a traceback message. The
957 lines between the first line and the type/value may be omitted or
958 replaced with any other string:
959
960 >>> def f(x):
961 ... '''
962 ... >>> x = 12
963 ... >>> print(x//0)
964 ... Traceback (most recent call last):
965 ... ZeroDivisionError: integer division or modulo by zero
966 ... '''
967 >>> test = doctest.DocTestFinder().find(f)[0]
968 >>> doctest.DocTestRunner(verbose=False).run(test)
969 TestResults(failed=0, attempted=2)
970
971 An example may not generate output before it raises an exception; if
972 it does, then the traceback message will not be recognized as
973 signaling an expected exception, so the example will be reported as an
974 unexpected exception:
975
976 >>> def f(x):
977 ... '''
978 ... >>> x = 12
979 ... >>> print('pre-exception output', x//0)
980 ... pre-exception output
981 ... Traceback (most recent call last):
982 ... ZeroDivisionError: integer division or modulo by zero
983 ... '''
984 >>> test = doctest.DocTestFinder().find(f)[0]
985 >>> doctest.DocTestRunner(verbose=False).run(test)
986 ... # doctest: +ELLIPSIS
987 **********************************************************************
988 File ..., line 4, in f
989 Failed example:
990 print('pre-exception output', x//0)
991 Exception raised:
992 ...
993 ZeroDivisionError: integer division or modulo by zero
994 TestResults(failed=1, attempted=2)
995
996 Exception messages may contain newlines:
997
998 >>> def f(x):
999 ... r'''
1000 ... >>> raise ValueError('multi\nline\nmessage')
1001 ... Traceback (most recent call last):
1002 ... ValueError: multi
1003 ... line
1004 ... message
1005 ... '''
1006 >>> test = doctest.DocTestFinder().find(f)[0]
1007 >>> doctest.DocTestRunner(verbose=False).run(test)
1008 TestResults(failed=0, attempted=1)
1009
1010 If an exception is expected, but an exception with the wrong type or
1011 message is raised, then it is reported as a failure:
1012
1013 >>> def f(x):
1014 ... r'''
1015 ... >>> raise ValueError('message')
1016 ... Traceback (most recent call last):
1017 ... ValueError: wrong message
1018 ... '''
1019 >>> test = doctest.DocTestFinder().find(f)[0]
1020 >>> doctest.DocTestRunner(verbose=False).run(test)
1021 ... # doctest: +ELLIPSIS
1022 **********************************************************************
1023 File ..., line 3, in f
1024 Failed example:
1025 raise ValueError('message')
1026 Expected:
1027 Traceback (most recent call last):
1028 ValueError: wrong message
1029 Got:
1030 Traceback (most recent call last):
1031 ...
1032 ValueError: message
1033 TestResults(failed=1, attempted=1)
1034
1035 However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
1036 detail:
1037
1038 >>> def f(x):
1039 ... r'''
1040 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1041 ... Traceback (most recent call last):
1042 ... ValueError: wrong message
1043 ... '''
1044 >>> test = doctest.DocTestFinder().find(f)[0]
1045 >>> doctest.DocTestRunner(verbose=False).run(test)
1046 TestResults(failed=0, attempted=1)
1047
1048 IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
1049 between Python versions. For example, in Python 2.x, the module path of
1050 the exception is not in the output, but this will fail under Python 3:
1051
1052 >>> def f(x):
1053 ... r'''
1054 ... >>> from http.client import HTTPException
1055 ... >>> raise HTTPException('message')
1056 ... Traceback (most recent call last):
1057 ... HTTPException: message
1058 ... '''
1059 >>> test = doctest.DocTestFinder().find(f)[0]
1060 >>> doctest.DocTestRunner(verbose=False).run(test)
1061 ... # doctest: +ELLIPSIS
1062 **********************************************************************
1063 File ..., line 4, in f
1064 Failed example:
1065 raise HTTPException('message')
1066 Expected:
1067 Traceback (most recent call last):
1068 HTTPException: message
1069 Got:
1070 Traceback (most recent call last):
1071 ...
1072 http.client.HTTPException: message
1073 TestResults(failed=1, attempted=2)
1074
1075 But in Python 3 the module path is included, and therefore a test must look
1076 like the following test to succeed in Python 3. But that test will fail under
1077 Python 2.
1078
1079 >>> def f(x):
1080 ... r'''
1081 ... >>> from http.client import HTTPException
1082 ... >>> raise HTTPException('message')
1083 ... Traceback (most recent call last):
1084 ... http.client.HTTPException: message
1085 ... '''
1086 >>> test = doctest.DocTestFinder().find(f)[0]
1087 >>> doctest.DocTestRunner(verbose=False).run(test)
1088 TestResults(failed=0, attempted=2)
1089
1090 However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
1091 (or its unexpected absence) will be ignored:
1092
1093 >>> def f(x):
1094 ... r'''
1095 ... >>> from http.client import HTTPException
1096 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1097 ... Traceback (most recent call last):
1098 ... HTTPException: message
1099 ... '''
1100 >>> test = doctest.DocTestFinder().find(f)[0]
1101 >>> doctest.DocTestRunner(verbose=False).run(test)
1102 TestResults(failed=0, attempted=2)
1103
1104 The module path will be completely ignored, so two different module paths will
1105 still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
1106 be used when exceptions have changed module.
1107
1108 >>> def f(x):
1109 ... r'''
1110 ... >>> from http.client import HTTPException
1111 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1112 ... Traceback (most recent call last):
1113 ... foo.bar.HTTPException: message
1114 ... '''
1115 >>> test = doctest.DocTestFinder().find(f)[0]
1116 >>> doctest.DocTestRunner(verbose=False).run(test)
1117 TestResults(failed=0, attempted=2)
1118
1119 But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
1120
1121 >>> def f(x):
1122 ... r'''
1123 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1124 ... Traceback (most recent call last):
1125 ... TypeError: wrong type
1126 ... '''
1127 >>> test = doctest.DocTestFinder().find(f)[0]
1128 >>> doctest.DocTestRunner(verbose=False).run(test)
1129 ... # doctest: +ELLIPSIS
1130 **********************************************************************
1131 File ..., line 3, in f
1132 Failed example:
1133 raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1134 Expected:
1135 Traceback (most recent call last):
1136 TypeError: wrong type
1137 Got:
1138 Traceback (most recent call last):
1139 ...
1140 ValueError: message
1141 TestResults(failed=1, attempted=1)
1142
1143 If the exception does not have a message, you can still use
1144 IGNORE_EXCEPTION_DETAIL to normalize the modules between Python 2 and 3:
1145
1146 >>> def f(x):
1147 ... r'''
1148 ... >>> from http.client import HTTPException
1149 ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1150 ... Traceback (most recent call last):
1151 ... foo.bar.HTTPException
1152 ... '''
1153 >>> test = doctest.DocTestFinder().find(f)[0]
1154 >>> doctest.DocTestRunner(verbose=False).run(test)
1155 TestResults(failed=0, attempted=2)
1156
1157 Note that a trailing colon doesn't matter either:
1158
1159 >>> def f(x):
1160 ... r'''
1161 ... >>> from http.client import HTTPException
1162 ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1163 ... Traceback (most recent call last):
1164 ... foo.bar.HTTPException:
1165 ... '''
1166 >>> test = doctest.DocTestFinder().find(f)[0]
1167 >>> doctest.DocTestRunner(verbose=False).run(test)
1168 TestResults(failed=0, attempted=2)
1169
1170 If an exception is raised but not expected, then it is reported as an
1171 unexpected exception:
1172
1173 >>> def f(x):
1174 ... r'''
1175 ... >>> 1//0
1176 ... 0
1177 ... '''
1178 >>> test = doctest.DocTestFinder().find(f)[0]
1179 >>> doctest.DocTestRunner(verbose=False).run(test)
1180 ... # doctest: +ELLIPSIS
1181 **********************************************************************
1182 File ..., line 3, in f
1183 Failed example:
1184 1//0
1185 Exception raised:
1186 Traceback (most recent call last):
1187 ...
1188 ZeroDivisionError: integer division or modulo by zero
1189 TestResults(failed=1, attempted=1)
1190 """
1191 def displayhook(): r"""
1192 Test that changing sys.displayhook doesn't matter for doctest.
1193
1194 >>> import sys
1195 >>> orig_displayhook = sys.displayhook
1196 >>> def my_displayhook(x):
1197 ... print('hi!')
1198 >>> sys.displayhook = my_displayhook
1199 >>> def f():
1200 ... '''
1201 ... >>> 3
1202 ... 3
1203 ... '''
1204 >>> test = doctest.DocTestFinder().find(f)[0]
1205 >>> r = doctest.DocTestRunner(verbose=False).run(test)
1206 >>> post_displayhook = sys.displayhook
1207
1208 We need to restore sys.displayhook now, so that we'll be able to test
1209 results.
1210
1211 >>> sys.displayhook = orig_displayhook
1212
1213 Ok, now we can check that everything is ok.
1214
1215 >>> r
1216 TestResults(failed=0, attempted=1)
1217 >>> post_displayhook is my_displayhook
1218 True
1219 """
1220 def optionflags(): r"""
1221 Tests of `DocTestRunner`'s option flag handling.
1222
1223 Several option flags can be used to customize the behavior of the test
1224 runner. These are defined as module constants in doctest, and passed
1225 to the DocTestRunner constructor (multiple constants should be ORed
1226 together).
1227
1228 The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
1229 and 1/0:
1230
1231 >>> def f(x):
1232 ... '>>> True\n1\n'
1233
1234 >>> # Without the flag:
1235 >>> test = doctest.DocTestFinder().find(f)[0]
1236 >>> doctest.DocTestRunner(verbose=False).run(test)
1237 TestResults(failed=0, attempted=1)
1238
1239 >>> # With the flag:
1240 >>> test = doctest.DocTestFinder().find(f)[0]
1241 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1242 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1243 ... # doctest: +ELLIPSIS
1244 **********************************************************************
1245 File ..., line 2, in f
1246 Failed example:
1247 True
1248 Expected:
1249 1
1250 Got:
1251 True
1252 TestResults(failed=1, attempted=1)
1253
1254 The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1255 and the '<BLANKLINE>' marker:
1256
1257 >>> def f(x):
1258 ... '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'
1259
1260 >>> # Without the flag:
1261 >>> test = doctest.DocTestFinder().find(f)[0]
1262 >>> doctest.DocTestRunner(verbose=False).run(test)
1263 TestResults(failed=0, attempted=1)
1264
1265 >>> # With the flag:
1266 >>> test = doctest.DocTestFinder().find(f)[0]
1267 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
1268 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1269 ... # doctest: +ELLIPSIS
1270 **********************************************************************
1271 File ..., line 2, in f
1272 Failed example:
1273 print("a\n\nb")
1274 Expected:
1275 a
1276 <BLANKLINE>
1277 b
1278 Got:
1279 a
1280 <BLANKLINE>
1281 b
1282 TestResults(failed=1, attempted=1)
1283
1284 The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1285 treated as equal:
1286
1287 >>> def f(x):
1288 ... '>>> print(1, 2, 3)\n 1 2\n 3'
1289
1290 >>> # Without the flag:
1291 >>> test = doctest.DocTestFinder().find(f)[0]
1292 >>> doctest.DocTestRunner(verbose=False).run(test)
1293 ... # doctest: +ELLIPSIS
1294 **********************************************************************
1295 File ..., line 2, in f
1296 Failed example:
1297 print(1, 2, 3)
1298 Expected:
1299 1 2
1300 3
1301 Got:
1302 1 2 3
1303 TestResults(failed=1, attempted=1)
1304
1305 >>> # With the flag:
1306 >>> test = doctest.DocTestFinder().find(f)[0]
1307 >>> flags = doctest.NORMALIZE_WHITESPACE
1308 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1309 TestResults(failed=0, attempted=1)
1310
1311 An example from the docs:
1312 >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
1313 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1314 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1315
1316 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1317 output to match any substring in the actual output:
1318
1319 >>> def f(x):
1320 ... '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'
1321
1322 >>> # Without the flag:
1323 >>> test = doctest.DocTestFinder().find(f)[0]
1324 >>> doctest.DocTestRunner(verbose=False).run(test)
1325 ... # doctest: +ELLIPSIS
1326 **********************************************************************
1327 File ..., line 2, in f
1328 Failed example:
1329 print(list(range(15)))
1330 Expected:
1331 [0, 1, 2, ..., 14]
1332 Got:
1333 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1334 TestResults(failed=1, attempted=1)
1335
1336 >>> # With the flag:
1337 >>> test = doctest.DocTestFinder().find(f)[0]
1338 >>> flags = doctest.ELLIPSIS
1339 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1340 TestResults(failed=0, attempted=1)
1341
1342 ... also matches nothing:
1343
1344 >>> if 1:
1345 ... for i in range(100):
1346 ... print(i**2, end=' ') #doctest: +ELLIPSIS
1347 ... print('!')
1348 0 1...4...9 16 ... 36 49 64 ... 9801 !
1349
1350 ... can be surprising; e.g., this test passes:
1351
1352 >>> if 1: #doctest: +ELLIPSIS
1353 ... for i in range(20):
1354 ... print(i, end=' ')
1355 ... print(20)
1356 0 1 2 ...1...2...0
1357
1358 Examples from the docs:
1359
1360 >>> print(list(range(20))) # doctest:+ELLIPSIS
1361 [0, 1, ..., 18, 19]
1362
1363 >>> print(list(range(20))) # doctest: +ELLIPSIS
1364 ... # doctest: +NORMALIZE_WHITESPACE
1365 [0, 1, ..., 18, 19]
1366
1367 The SKIP flag causes an example to be skipped entirely. I.e., the
1368 example is not run. It can be useful in contexts where doctest
1369 examples serve as both documentation and test cases, and an example
1370 should be included for documentation purposes, but should not be
1371 checked (e.g., because its output is random, or depends on resources
1372 which would be unavailable.) The SKIP flag can also be used for
1373 'commenting out' broken examples.
1374
1375 >>> import unavailable_resource # doctest: +SKIP
1376 >>> unavailable_resource.do_something() # doctest: +SKIP
1377 >>> unavailable_resource.blow_up() # doctest: +SKIP
1378 Traceback (most recent call last):
1379 ...
1380 UncheckedBlowUpError: Nobody checks me.
1381
1382 >>> import random
1383 >>> print(random.random()) # doctest: +SKIP
1384 0.721216923889
1385
1386 The REPORT_UDIFF flag causes failures that involve multi-line expected
1387 and actual outputs to be displayed using a unified diff:
1388
1389 >>> def f(x):
1390 ... r'''
1391 ... >>> print('\n'.join('abcdefg'))
1392 ... a
1393 ... B
1394 ... c
1395 ... d
1396 ... f
1397 ... g
1398 ... h
1399 ... '''
1400
1401 >>> # Without the flag:
1402 >>> test = doctest.DocTestFinder().find(f)[0]
1403 >>> doctest.DocTestRunner(verbose=False).run(test)
1404 ... # doctest: +ELLIPSIS
1405 **********************************************************************
1406 File ..., line 3, in f
1407 Failed example:
1408 print('\n'.join('abcdefg'))
1409 Expected:
1410 a
1411 B
1412 c
1413 d
1414 f
1415 g
1416 h
1417 Got:
1418 a
1419 b
1420 c
1421 d
1422 e
1423 f
1424 g
1425 TestResults(failed=1, attempted=1)
1426
1427 >>> # With the flag:
1428 >>> test = doctest.DocTestFinder().find(f)[0]
1429 >>> flags = doctest.REPORT_UDIFF
1430 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1431 ... # doctest: +ELLIPSIS
1432 **********************************************************************
1433 File ..., line 3, in f
1434 Failed example:
1435 print('\n'.join('abcdefg'))
1436 Differences (unified diff with -expected +actual):
1437 @@ -1,7 +1,7 @@
1438 a
1439 -B
1440 +b
1441 c
1442 d
1443 +e
1444 f
1445 g
1446 -h
1447 TestResults(failed=1, attempted=1)
1448
1449 The REPORT_CDIFF flag causes failures that involve multi-line expected
1450 and actual outputs to be displayed using a context diff:
1451
1452 >>> # Reuse f() from the REPORT_UDIFF example, above.
1453 >>> test = doctest.DocTestFinder().find(f)[0]
1454 >>> flags = doctest.REPORT_CDIFF
1455 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1456 ... # doctest: +ELLIPSIS
1457 **********************************************************************
1458 File ..., line 3, in f
1459 Failed example:
1460 print('\n'.join('abcdefg'))
1461 Differences (context diff with expected followed by actual):
1462 ***************
1463 *** 1,7 ****
1464 a
1465 ! B
1466 c
1467 d
1468 f
1469 g
1470 - h
1471 --- 1,7 ----
1472 a
1473 ! b
1474 c
1475 d
1476 + e
1477 f
1478 g
1479 TestResults(failed=1, attempted=1)
1480
1481
1482 The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1483 used by the popular ndiff.py utility. This does intraline difference
1484 marking, as well as interline differences.
1485
1486 >>> def f(x):
1487 ... r'''
1488 ... >>> print("a b c d e f g h i j k l m")
1489 ... a b c d e f g h i j k 1 m
1490 ... '''
1491 >>> test = doctest.DocTestFinder().find(f)[0]
1492 >>> flags = doctest.REPORT_NDIFF
1493 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1494 ... # doctest: +ELLIPSIS
1495 **********************************************************************
1496 File ..., line 3, in f
1497 Failed example:
1498 print("a b c d e f g h i j k l m")
1499 Differences (ndiff with -expected +actual):
1500 - a b c d e f g h i j k 1 m
1501 ? ^
1502 + a b c d e f g h i j k l m
1503 ? + ++ ^
1504 TestResults(failed=1, attempted=1)
1505
1506 The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
1507 failing example:
1508
1509 >>> def f(x):
1510 ... r'''
1511 ... >>> print(1) # first success
1512 ... 1
1513 ... >>> print(2) # first failure
1514 ... 200
1515 ... >>> print(3) # second failure
1516 ... 300
1517 ... >>> print(4) # second success
1518 ... 4
1519 ... >>> print(5) # third failure
1520 ... 500
1521 ... '''
1522 >>> test = doctest.DocTestFinder().find(f)[0]
1523 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1524 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1525 ... # doctest: +ELLIPSIS
1526 **********************************************************************
1527 File ..., line 5, in f
1528 Failed example:
1529 print(2) # first failure
1530 Expected:
1531 200
1532 Got:
1533 2
1534 TestResults(failed=3, attempted=5)
1535
1536 However, output from `report_start` is not suppressed:
1537
1538 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1539 ... # doctest: +ELLIPSIS
1540 Trying:
1541 print(1) # first success
1542 Expecting:
1543 1
1544 ok
1545 Trying:
1546 print(2) # first failure
1547 Expecting:
1548 200
1549 **********************************************************************
1550 File ..., line 5, in f
1551 Failed example:
1552 print(2) # first failure
1553 Expected:
1554 200
1555 Got:
1556 2
1557 TestResults(failed=3, attempted=5)
1558
1559 The FAIL_FAST flag causes the runner to exit after the first failing example,
1560 so subsequent examples are not even attempted:
1561
1562 >>> flags = doctest.FAIL_FAST
1563 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1564 ... # doctest: +ELLIPSIS
1565 **********************************************************************
1566 File ..., line 5, in f
1567 Failed example:
1568 print(2) # first failure
1569 Expected:
1570 200
1571 Got:
1572 2
1573 TestResults(failed=1, attempted=2)
1574
1575 Specifying both FAIL_FAST and REPORT_ONLY_FIRST_FAILURE is equivalent to
1576 FAIL_FAST only:
1577
1578 >>> flags = doctest.FAIL_FAST | doctest.REPORT_ONLY_FIRST_FAILURE
1579 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1580 ... # doctest: +ELLIPSIS
1581 **********************************************************************
1582 File ..., line 5, in f
1583 Failed example:
1584 print(2) # first failure
1585 Expected:
1586 200
1587 Got:
1588 2
1589 TestResults(failed=1, attempted=2)
1590
1591 For the purposes of both REPORT_ONLY_FIRST_FAILURE and FAIL_FAST, unexpected
1592 exceptions count as failures:
1593
1594 >>> def f(x):
1595 ... r'''
1596 ... >>> print(1) # first success
1597 ... 1
1598 ... >>> raise ValueError(2) # first failure
1599 ... 200
1600 ... >>> print(3) # second failure
1601 ... 300
1602 ... >>> print(4) # second success
1603 ... 4
1604 ... >>> print(5) # third failure
1605 ... 500
1606 ... '''
1607 >>> test = doctest.DocTestFinder().find(f)[0]
1608 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1609 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1610 ... # doctest: +ELLIPSIS
1611 **********************************************************************
1612 File ..., line 5, in f
1613 Failed example:
1614 raise ValueError(2) # first failure
1615 Exception raised:
1616 ...
1617 ValueError: 2
1618 TestResults(failed=3, attempted=5)
1619 >>> flags = doctest.FAIL_FAST
1620 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1621 ... # doctest: +ELLIPSIS
1622 **********************************************************************
1623 File ..., line 5, in f
1624 Failed example:
1625 raise ValueError(2) # first failure
1626 Exception raised:
1627 ...
1628 ValueError: 2
1629 TestResults(failed=1, attempted=2)
1630
1631 New option flags can also be registered, via register_optionflag(). Here
1632 we reach into doctest's internals a bit.
1633
1634 >>> unlikely = "UNLIKELY_OPTION_NAME"
1635 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1636 False
1637 >>> new_flag_value = doctest.register_optionflag(unlikely)
1638 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1639 True
1640
1641 Before 2.4.4/2.5, registering a name more than once erroneously created
1642 more than one flag value. Here we verify that's fixed:
1643
1644 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1645 >>> redundant_flag_value == new_flag_value
1646 True
1647
1648 Clean up.
1649 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1650
1651 """
1652
1653 def option_directives(): r"""
1654 Tests of `DocTestRunner`'s option directive mechanism.
1655
1656 Option directives can be used to turn option flags on or off for a
1657 single example. To turn an option on for an example, follow that
1658 example with a comment of the form ``# doctest: +OPTION``:
1659
1660 >>> def f(x): r'''
1661 ... >>> print(list(range(10))) # should fail: no ellipsis
1662 ... [0, 1, ..., 9]
1663 ...
1664 ... >>> print(list(range(10))) # doctest: +ELLIPSIS
1665 ... [0, 1, ..., 9]
1666 ... '''
1667 >>> test = doctest.DocTestFinder().find(f)[0]
1668 >>> doctest.DocTestRunner(verbose=False).run(test)
1669 ... # doctest: +ELLIPSIS
1670 **********************************************************************
1671 File ..., line 2, in f
1672 Failed example:
1673 print(list(range(10))) # should fail: no ellipsis
1674 Expected:
1675 [0, 1, ..., 9]
1676 Got:
1677 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1678 TestResults(failed=1, attempted=2)
1679
1680 To turn an option off for an example, follow that example with a
1681 comment of the form ``# doctest: -OPTION``:
1682
1683 >>> def f(x): r'''
1684 ... >>> print(list(range(10)))
1685 ... [0, 1, ..., 9]
1686 ...
1687 ... >>> # should fail: no ellipsis
1688 ... >>> print(list(range(10))) # doctest: -ELLIPSIS
1689 ... [0, 1, ..., 9]
1690 ... '''
1691 >>> test = doctest.DocTestFinder().find(f)[0]
1692 >>> doctest.DocTestRunner(verbose=False,
1693 ... optionflags=doctest.ELLIPSIS).run(test)
1694 ... # doctest: +ELLIPSIS
1695 **********************************************************************
1696 File ..., line 6, in f
1697 Failed example:
1698 print(list(range(10))) # doctest: -ELLIPSIS
1699 Expected:
1700 [0, 1, ..., 9]
1701 Got:
1702 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1703 TestResults(failed=1, attempted=2)
1704
1705 Option directives affect only the example that they appear with; they
1706 do not change the options for surrounding examples:
1707
1708 >>> def f(x): r'''
1709 ... >>> print(list(range(10))) # Should fail: no ellipsis
1710 ... [0, 1, ..., 9]
1711 ...
1712 ... >>> print(list(range(10))) # doctest: +ELLIPSIS
1713 ... [0, 1, ..., 9]
1714 ...
1715 ... >>> print(list(range(10))) # Should fail: no ellipsis
1716 ... [0, 1, ..., 9]
1717 ... '''
1718 >>> test = doctest.DocTestFinder().find(f)[0]
1719 >>> doctest.DocTestRunner(verbose=False).run(test)
1720 ... # doctest: +ELLIPSIS
1721 **********************************************************************
1722 File ..., line 2, in f
1723 Failed example:
1724 print(list(range(10))) # Should fail: no ellipsis
1725 Expected:
1726 [0, 1, ..., 9]
1727 Got:
1728 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1729 **********************************************************************
1730 File ..., line 8, in f
1731 Failed example:
1732 print(list(range(10))) # Should fail: no ellipsis
1733 Expected:
1734 [0, 1, ..., 9]
1735 Got:
1736 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1737 TestResults(failed=2, attempted=3)
1738
1739 Multiple options may be modified by a single option directive. They
1740 may be separated by whitespace, commas, or both:
1741
1742 >>> def f(x): r'''
1743 ... >>> print(list(range(10))) # Should fail
1744 ... [0, 1, ..., 9]
1745 ... >>> print(list(range(10))) # Should succeed
1746 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1747 ... [0, 1, ..., 9]
1748 ... '''
1749 >>> test = doctest.DocTestFinder().find(f)[0]
1750 >>> doctest.DocTestRunner(verbose=False).run(test)
1751 ... # doctest: +ELLIPSIS
1752 **********************************************************************
1753 File ..., line 2, in f
1754 Failed example:
1755 print(list(range(10))) # Should fail
1756 Expected:
1757 [0, 1, ..., 9]
1758 Got:
1759 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1760 TestResults(failed=1, attempted=2)
1761
1762 >>> def f(x): r'''
1763 ... >>> print(list(range(10))) # Should fail
1764 ... [0, 1, ..., 9]
1765 ... >>> print(list(range(10))) # Should succeed
1766 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1767 ... [0, 1, ..., 9]
1768 ... '''
1769 >>> test = doctest.DocTestFinder().find(f)[0]
1770 >>> doctest.DocTestRunner(verbose=False).run(test)
1771 ... # doctest: +ELLIPSIS
1772 **********************************************************************
1773 File ..., line 2, in f
1774 Failed example:
1775 print(list(range(10))) # Should fail
1776 Expected:
1777 [0, 1, ..., 9]
1778 Got:
1779 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1780 TestResults(failed=1, attempted=2)
1781
1782 >>> def f(x): r'''
1783 ... >>> print(list(range(10))) # Should fail
1784 ... [0, 1, ..., 9]
1785 ... >>> print(list(range(10))) # Should succeed
1786 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1787 ... [0, 1, ..., 9]
1788 ... '''
1789 >>> test = doctest.DocTestFinder().find(f)[0]
1790 >>> doctest.DocTestRunner(verbose=False).run(test)
1791 ... # doctest: +ELLIPSIS
1792 **********************************************************************
1793 File ..., line 2, in f
1794 Failed example:
1795 print(list(range(10))) # Should fail
1796 Expected:
1797 [0, 1, ..., 9]
1798 Got:
1799 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1800 TestResults(failed=1, attempted=2)
1801
1802 The option directive may be put on the line following the source, as
1803 long as a continuation prompt is used:
1804
1805 >>> def f(x): r'''
1806 ... >>> print(list(range(10)))
1807 ... ... # doctest: +ELLIPSIS
1808 ... [0, 1, ..., 9]
1809 ... '''
1810 >>> test = doctest.DocTestFinder().find(f)[0]
1811 >>> doctest.DocTestRunner(verbose=False).run(test)
1812 TestResults(failed=0, attempted=1)
1813
1814 For examples with multi-line source, the option directive may appear
1815 at the end of any line:
1816
1817 >>> def f(x): r'''
1818 ... >>> for x in range(10): # doctest: +ELLIPSIS
1819 ... ... print(' ', x, end='', sep='')
1820 ... 0 1 2 ... 9
1821 ...
1822 ... >>> for x in range(10):
1823 ... ... print(' ', x, end='', sep='') # doctest: +ELLIPSIS
1824 ... 0 1 2 ... 9
1825 ... '''
1826 >>> test = doctest.DocTestFinder().find(f)[0]
1827 >>> doctest.DocTestRunner(verbose=False).run(test)
1828 TestResults(failed=0, attempted=2)
1829
1830 If more than one line of an example with multi-line source has an
1831 option directive, then they are combined:
1832
1833 >>> def f(x): r'''
1834 ... Should fail (option directive not on the last line):
1835 ... >>> for x in range(10): # doctest: +ELLIPSIS
1836 ... ... print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE
1837 ... 0 1 2...9
1838 ... '''
1839 >>> test = doctest.DocTestFinder().find(f)[0]
1840 >>> doctest.DocTestRunner(verbose=False).run(test)
1841 TestResults(failed=0, attempted=1)
1842
1843 It is an error to have a comment of the form ``# doctest:`` that is
1844 *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1845 ``OPTION`` is an option that has been registered with
1846 `register_option`:
1847
1848 >>> # Error: Option not registered
1849 >>> s = '>>> print(12) #doctest: +BADOPTION'
1850 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1851 Traceback (most recent call last):
1852 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1853
1854 >>> # Error: No + or - prefix
1855 >>> s = '>>> print(12) #doctest: ELLIPSIS'
1856 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1857 Traceback (most recent call last):
1858 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1859
1860 It is an error to use an option directive on a line that contains no
1861 source:
1862
1863 >>> s = '>>> # doctest: +ELLIPSIS'
1864 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1865 Traceback (most recent call last):
1866 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1867 """
1868
1869 def test_testsource(): r"""
1870 Unit tests for `testsource()`.
1871
1872 The testsource() function takes a module and a name, finds the (first)
1873 test with that name in that module, and converts it to a script. The
1874 example code is converted to regular Python code. The surrounding
1875 words and expected output are converted to comments:
1876
1877 >>> import test.test_doctest
1878 >>> name = 'test.test_doctest.sample_func'
1879 >>> print(doctest.testsource(test.test_doctest, name))
1880 # Blah blah
1881 #
1882 print(sample_func(22))
1883 # Expected:
1884 ## 44
1885 #
1886 # Yee ha!
1887 <BLANKLINE>
1888
1889 >>> name = 'test.test_doctest.SampleNewStyleClass'
1890 >>> print(doctest.testsource(test.test_doctest, name))
1891 print('1\n2\n3')
1892 # Expected:
1893 ## 1
1894 ## 2
1895 ## 3
1896 <BLANKLINE>
1897
1898 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1899 >>> print(doctest.testsource(test.test_doctest, name))
1900 print(SampleClass.a_classmethod(10))
1901 # Expected:
1902 ## 12
1903 print(SampleClass(0).a_classmethod(10))
1904 # Expected:
1905 ## 12
1906 <BLANKLINE>
1907 """
1908
1909 def test_debug(): r"""
1910
1911 Create a docstring that we want to debug:
1912
1913 >>> s = '''
1914 ... >>> x = 12
1915 ... >>> print(x)
1916 ... 12
1917 ... '''
1918
1919 Create some fake stdin input, to feed to the debugger:
1920
1921 >>> real_stdin = sys.stdin
1922 >>> sys.stdin = _FakeInput(['next', 'print(x)', 'continue'])
1923
1924 Run the debugger on the docstring, and then restore sys.stdin.
1925
1926 >>> try: doctest.debug_src(s)
1927 ... finally: sys.stdin = real_stdin
1928 > <string>(1)<module>()
1929 (Pdb) next
1930 12
1931 --Return--
1932 > <string>(1)<module>()->None
1933 (Pdb) print(x)
1934 12
1935 (Pdb) continue
1936
1937 """
1938
1939 if not hasattr(sys, 'gettrace') or not sys.gettrace():
1940 def test_pdb_set_trace():
1941 """Using pdb.set_trace from a doctest.
1942
1943 You can use pdb.set_trace from a doctest. To do so, you must
1944 retrieve the set_trace function from the pdb module at the time
1945 you use it. The doctest module changes sys.stdout so that it can
1946 capture program output. It also temporarily replaces pdb.set_trace
1947 with a version that restores stdout. This is necessary for you to
1948 see debugger output.
1949
1950 >>> doc = '''
1951 ... >>> x = 42
1952 ... >>> raise Exception('clé')
1953 ... Traceback (most recent call last):
1954 ... Exception: clé
1955 ... >>> import pdb; pdb.set_trace()
1956 ... '''
1957 >>> parser = doctest.DocTestParser()
1958 >>> test = parser.get_doctest(doc, {}, "foo-bar@baz", "foo-bar@baz.py", 0)
1959 >>> runner = doctest.DocTestRunner(verbose=False)
1960
1961 To demonstrate this, we'll create a fake standard input that
1962 captures our debugger input:
1963
1964 >>> real_stdin = sys.stdin
1965 >>> sys.stdin = _FakeInput([
1966 ... 'print(x)', # print data defined by the example
1967 ... 'continue', # stop debugging
1968 ... ''])
1969
1970 >>> try: runner.run(test)
1971 ... finally: sys.stdin = real_stdin
1972 --Return--
1973 > <doctest foo-bar@baz[2]>(1)<module>()->None
1974 -> import pdb; pdb.set_trace()
1975 (Pdb) print(x)
1976 42
1977 (Pdb) continue
1978 TestResults(failed=0, attempted=3)
1979
1980 You can also put pdb.set_trace in a function called from a test:
1981
1982 >>> def calls_set_trace():
1983 ... y=2
1984 ... import pdb; pdb.set_trace()
1985
1986 >>> doc = '''
1987 ... >>> x=1
1988 ... >>> calls_set_trace()
1989 ... '''
1990 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
1991 >>> real_stdin = sys.stdin
1992 >>> sys.stdin = _FakeInput([
1993 ... 'print(y)', # print data defined in the function
1994 ... 'up', # out of function
1995 ... 'print(x)', # print data defined by the example
1996 ... 'continue', # stop debugging
1997 ... ''])
1998
1999 >>> try:
2000 ... runner.run(test)
2001 ... finally:
2002 ... sys.stdin = real_stdin
2003 --Return--
2004 > <doctest test.test_doctest.test_pdb_set_trace[7]>(3)calls_set_trace()->None
2005 -> import pdb; pdb.set_trace()
2006 (Pdb) print(y)
2007 2
2008 (Pdb) up
2009 > <doctest foo-bar@baz[1]>(1)<module>()
2010 -> calls_set_trace()
2011 (Pdb) print(x)
2012 1
2013 (Pdb) continue
2014 TestResults(failed=0, attempted=2)
2015
2016 During interactive debugging, source code is shown, even for
2017 doctest examples:
2018
2019 >>> doc = '''
2020 ... >>> def f(x):
2021 ... ... g(x*2)
2022 ... >>> def g(x):
2023 ... ... print(x+3)
2024 ... ... import pdb; pdb.set_trace()
2025 ... >>> f(3)
2026 ... '''
2027 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2028 >>> real_stdin = sys.stdin
2029 >>> sys.stdin = _FakeInput([
2030 ... 'list', # list source from example 2
2031 ... 'next', # return from g()
2032 ... 'list', # list source from example 1
2033 ... 'next', # return from f()
2034 ... 'list', # list source from example 3
2035 ... 'continue', # stop debugging
2036 ... ''])
2037 >>> try: runner.run(test)
2038 ... finally: sys.stdin = real_stdin
2039 ... # doctest: +NORMALIZE_WHITESPACE
2040 --Return--
2041 > <doctest foo-bar@baz[1]>(3)g()->None
2042 -> import pdb; pdb.set_trace()
2043 (Pdb) list
2044 1 def g(x):
2045 2 print(x+3)
2046 3 -> import pdb; pdb.set_trace()
2047 [EOF]
2048 (Pdb) next
2049 --Return--
2050 > <doctest foo-bar@baz[0]>(2)f()->None
2051 -> g(x*2)
2052 (Pdb) list
2053 1 def f(x):
2054 2 -> g(x*2)
2055 [EOF]
2056 (Pdb) next
2057 --Return--
2058 > <doctest foo-bar@baz[2]>(1)<module>()->None
2059 -> f(3)
2060 (Pdb) list
2061 1 -> f(3)
2062 [EOF]
2063 (Pdb) continue
2064 **********************************************************************
2065 File "foo-bar@baz.py", line 7, in foo-bar@baz
2066 Failed example:
2067 f(3)
2068 Expected nothing
2069 Got:
2070 9
2071 TestResults(failed=1, attempted=3)
2072 """
2073
2074 def test_pdb_set_trace_nested():
2075 """This illustrates more-demanding use of set_trace with nested functions.
2076
2077 >>> class C(object):
2078 ... def calls_set_trace(self):
2079 ... y = 1
2080 ... import pdb; pdb.set_trace()
2081 ... self.f1()
2082 ... y = 2
2083 ... def f1(self):
2084 ... x = 1
2085 ... self.f2()
2086 ... x = 2
2087 ... def f2(self):
2088 ... z = 1
2089 ... z = 2
2090
2091 >>> calls_set_trace = C().calls_set_trace
2092
2093 >>> doc = '''
2094 ... >>> a = 1
2095 ... >>> calls_set_trace()
2096 ... '''
2097 >>> parser = doctest.DocTestParser()
2098 >>> runner = doctest.DocTestRunner(verbose=False)
2099 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2100 >>> real_stdin = sys.stdin
2101 >>> sys.stdin = _FakeInput([
2102 ... 'print(y)', # print data defined in the function
2103 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print(z)',
2104 ... 'up', 'print(x)',
2105 ... 'up', 'print(y)',
2106 ... 'up', 'print(foo)',
2107 ... 'continue', # stop debugging
2108 ... ''])
2109
2110 >>> try:
2111 ... runner.run(test)
2112 ... finally:
2113 ... sys.stdin = real_stdin
2114 ... # doctest: +REPORT_NDIFF
2115 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2116 -> self.f1()
2117 (Pdb) print(y)
2118 1
2119 (Pdb) step
2120 --Call--
2121 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
2122 -> def f1(self):
2123 (Pdb) step
2124 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
2125 -> x = 1
2126 (Pdb) step
2127 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2128 -> self.f2()
2129 (Pdb) step
2130 --Call--
2131 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
2132 -> def f2(self):
2133 (Pdb) step
2134 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
2135 -> z = 1
2136 (Pdb) step
2137 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
2138 -> z = 2
2139 (Pdb) print(z)
2140 1
2141 (Pdb) up
2142 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2143 -> self.f2()
2144 (Pdb) print(x)
2145 1
2146 (Pdb) up
2147 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2148 -> self.f1()
2149 (Pdb) print(y)
2150 1
2151 (Pdb) up
2152 > <doctest foo-bar@baz[1]>(1)<module>()
2153 -> calls_set_trace()
2154 (Pdb) print(foo)
2155 *** NameError: name 'foo' is not defined
2156 (Pdb) continue
2157 TestResults(failed=0, attempted=2)
2158 """
2159
2160 def test_DocTestSuite():
2161 """DocTestSuite creates a unittest test suite from a doctest.
2162
2163 We create a Suite by providing a module. A module can be provided
2164 by passing a module object:
2165
2166 >>> import unittest
2167 >>> import test.sample_doctest
2168 >>> suite = doctest.DocTestSuite(test.sample_doctest)
2169 >>> suite.run(unittest.TestResult())
2170 <unittest.result.TestResult run=9 errors=0 failures=4>
2171
2172 We can also supply the module by name:
2173
2174 >>> suite = doctest.DocTestSuite('test.sample_doctest')
2175 >>> suite.run(unittest.TestResult())
2176 <unittest.result.TestResult run=9 errors=0 failures=4>
2177
2178 The module need not contain any doctest examples:
2179
2180 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_doctests')
2181 >>> suite.run(unittest.TestResult())
2182 <unittest.result.TestResult run=0 errors=0 failures=0>
2183
2184 The module need not contain any docstrings either:
2185
2186 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings')
2187 >>> suite.run(unittest.TestResult())
2188 <unittest.result.TestResult run=0 errors=0 failures=0>
2189
2190 We can use the current module:
2191
2192 >>> suite = test.sample_doctest.test_suite()
2193 >>> suite.run(unittest.TestResult())
2194 <unittest.result.TestResult run=9 errors=0 failures=4>
2195
2196 We can also provide a DocTestFinder:
2197
2198 >>> finder = doctest.DocTestFinder()
2199 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2200 ... test_finder=finder)
2201 >>> suite.run(unittest.TestResult())
2202 <unittest.result.TestResult run=9 errors=0 failures=4>
2203
2204 The DocTestFinder need not return any tests:
2205
2206 >>> finder = doctest.DocTestFinder()
2207 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings',
2208 ... test_finder=finder)
2209 >>> suite.run(unittest.TestResult())
2210 <unittest.result.TestResult run=0 errors=0 failures=0>
2211
2212 We can supply global variables. If we pass globs, they will be
2213 used instead of the module globals. Here we'll pass an empty
2214 globals, triggering an extra error:
2215
2216 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
2217 >>> suite.run(unittest.TestResult())
2218 <unittest.result.TestResult run=9 errors=0 failures=5>
2219
2220 Alternatively, we can provide extra globals. Here we'll make an
2221 error go away by providing an extra global variable:
2222
2223 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2224 ... extraglobs={'y': 1})
2225 >>> suite.run(unittest.TestResult())
2226 <unittest.result.TestResult run=9 errors=0 failures=3>
2227
2228 You can pass option flags. Here we'll cause an extra error
2229 by disabling the blank-line feature:
2230
2231 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2232 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2233 >>> suite.run(unittest.TestResult())
2234 <unittest.result.TestResult run=9 errors=0 failures=5>
2235
2236 You can supply setUp and tearDown functions:
2237
2238 >>> def setUp(t):
2239 ... import test.test_doctest
2240 ... test.test_doctest.sillySetup = True
2241
2242 >>> def tearDown(t):
2243 ... import test.test_doctest
2244 ... del test.test_doctest.sillySetup
2245
2246 Here, we installed a silly variable that the test expects:
2247
2248 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2249 ... setUp=setUp, tearDown=tearDown)
2250 >>> suite.run(unittest.TestResult())
2251 <unittest.result.TestResult run=9 errors=0 failures=3>
2252
2253 But the tearDown restores sanity:
2254
2255 >>> import test.test_doctest
2256 >>> test.test_doctest.sillySetup
2257 Traceback (most recent call last):
2258 ...
2259 AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2260
2261 The setUp and tearDown functions are passed test objects. Here
2262 we'll use the setUp function to supply the missing variable y:
2263
2264 >>> def setUp(test):
2265 ... test.globs['y'] = 1
2266
2267 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
2268 >>> suite.run(unittest.TestResult())
2269 <unittest.result.TestResult run=9 errors=0 failures=3>
2270
2271 Here, we didn't need to use a tearDown function because we
2272 modified the test globals, which are a copy of the
2273 sample_doctest module dictionary. The test globals are
2274 automatically cleared for us after a test.
2275 """
2276
2277 def test_DocFileSuite():
2278 """We can test tests found in text files using a DocFileSuite.
2279
2280 We create a suite by providing the names of one or more text
2281 files that include examples:
2282
2283 >>> import unittest
2284 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2285 ... 'test_doctest2.txt',
2286 ... 'test_doctest4.txt')
2287 >>> suite.run(unittest.TestResult())
2288 <unittest.result.TestResult run=3 errors=0 failures=2>
2289
2290 The test files are looked for in the directory containing the
2291 calling module. A package keyword argument can be provided to
2292 specify a different relative location.
2293
2294 >>> import unittest
2295 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2296 ... 'test_doctest2.txt',
2297 ... 'test_doctest4.txt',
2298 ... package='test')
2299 >>> suite.run(unittest.TestResult())
2300 <unittest.result.TestResult run=3 errors=0 failures=2>
2301
2302 Support for using a package's __loader__.get_data() is also
2303 provided.
2304
2305 >>> import unittest, pkgutil, test
2306 >>> added_loader = False
2307 >>> if not hasattr(test, '__loader__'):
2308 ... test.__loader__ = pkgutil.get_loader(test)
2309 ... added_loader = True
2310 >>> try:
2311 ... suite = doctest.DocFileSuite('test_doctest.txt',
2312 ... 'test_doctest2.txt',
2313 ... 'test_doctest4.txt',
2314 ... package='test')
2315 ... suite.run(unittest.TestResult())
2316 ... finally:
2317 ... if added_loader:
2318 ... del test.__loader__
2319 <unittest.result.TestResult run=3 errors=0 failures=2>
2320
2321 '/' should be used as a path separator. It will be converted
2322 to a native separator at run time:
2323
2324 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2325 >>> suite.run(unittest.TestResult())
2326 <unittest.result.TestResult run=1 errors=0 failures=1>
2327
2328 If DocFileSuite is used from an interactive session, then files
2329 are resolved relative to the directory of sys.argv[0]:
2330
2331 >>> import types, os.path, test.test_doctest
2332 >>> save_argv = sys.argv
2333 >>> sys.argv = [test.test_doctest.__file__]
2334 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2335 ... package=types.ModuleType('__main__'))
2336 >>> sys.argv = save_argv
2337
2338 By setting `module_relative=False`, os-specific paths may be
2339 used (including absolute paths and paths relative to the
2340 working directory):
2341
2342 >>> # Get the absolute path of the test package.
2343 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2344 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
2345
2346 >>> # Use it to find the absolute path of test_doctest.txt.
2347 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2348
2349 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
2350 >>> suite.run(unittest.TestResult())
2351 <unittest.result.TestResult run=1 errors=0 failures=1>
2352
2353 It is an error to specify `package` when `module_relative=False`:
2354
2355 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2356 ... package='test')
2357 Traceback (most recent call last):
2358 ValueError: Package may only be specified for module-relative paths.
2359
2360 You can specify initial global variables:
2361
2362 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2363 ... 'test_doctest2.txt',
2364 ... 'test_doctest4.txt',
2365 ... globs={'favorite_color': 'blue'})
2366 >>> suite.run(unittest.TestResult())
2367 <unittest.result.TestResult run=3 errors=0 failures=1>
2368
2369 In this case, we supplied a missing favorite color. You can
2370 provide doctest options:
2371
2372 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2373 ... 'test_doctest2.txt',
2374 ... 'test_doctest4.txt',
2375 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2376 ... globs={'favorite_color': 'blue'})
2377 >>> suite.run(unittest.TestResult())
2378 <unittest.result.TestResult run=3 errors=0 failures=2>
2379
2380 And, you can provide setUp and tearDown functions:
2381
2382 >>> def setUp(t):
2383 ... import test.test_doctest
2384 ... test.test_doctest.sillySetup = True
2385
2386 >>> def tearDown(t):
2387 ... import test.test_doctest
2388 ... del test.test_doctest.sillySetup
2389
2390 Here, we installed a silly variable that the test expects:
2391
2392 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2393 ... 'test_doctest2.txt',
2394 ... 'test_doctest4.txt',
2395 ... setUp=setUp, tearDown=tearDown)
2396 >>> suite.run(unittest.TestResult())
2397 <unittest.result.TestResult run=3 errors=0 failures=1>
2398
2399 But the tearDown restores sanity:
2400
2401 >>> import test.test_doctest
2402 >>> test.test_doctest.sillySetup
2403 Traceback (most recent call last):
2404 ...
2405 AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2406
2407 The setUp and tearDown functions are passed test objects.
2408 Here, we'll use a setUp function to set the favorite color in
2409 test_doctest.txt:
2410
2411 >>> def setUp(test):
2412 ... test.globs['favorite_color'] = 'blue'
2413
2414 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2415 >>> suite.run(unittest.TestResult())
2416 <unittest.result.TestResult run=1 errors=0 failures=0>
2417
2418 Here, we didn't need to use a tearDown function because we
2419 modified the test globals. The test globals are
2420 automatically cleared for us after a test.
2421
2422 Tests in a file run using `DocFileSuite` can also access the
2423 `__file__` global, which is set to the name of the file
2424 containing the tests:
2425
2426 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2427 >>> suite.run(unittest.TestResult())
2428 <unittest.result.TestResult run=1 errors=0 failures=0>
2429
2430 If the tests contain non-ASCII characters, we have to specify which
2431 encoding the file is encoded with. We do so by using the `encoding`
2432 parameter:
2433
2434 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2435 ... 'test_doctest2.txt',
2436 ... 'test_doctest4.txt',
2437 ... encoding='utf-8')
2438 >>> suite.run(unittest.TestResult())
2439 <unittest.result.TestResult run=3 errors=0 failures=2>
2440
2441 """
2442
2443 def test_trailing_space_in_test():
2444 """
2445 Trailing spaces in expected output are significant:
2446
2447 >>> x, y = 'foo', ''
2448 >>> print(x, y)
2449 foo \n
2450 """
2451
2452 class ESC[4;38;5;81mWrapper:
2453 def __init__(self, func):
2454 self.func = func
2455 functools.update_wrapper(self, func)
2456
2457 def __call__(self, *args, **kwargs):
2458 self.func(*args, **kwargs)
2459
2460 @Wrapper
2461 def test_look_in_unwrapped():
2462 """
2463 Docstrings in wrapped functions must be detected as well.
2464
2465 >>> 'one other test'
2466 'one other test'
2467 """
2468
2469 def test_unittest_reportflags():
2470 """Default unittest reporting flags can be set to control reporting
2471
2472 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2473 only the first failure of each test. First, we'll look at the
2474 output without the flag. The file test_doctest.txt file has two
2475 tests. They both fail if blank lines are disabled:
2476
2477 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2478 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2479 >>> import unittest
2480 >>> result = suite.run(unittest.TestResult())
2481 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2482 Traceback ...
2483 Failed example:
2484 favorite_color
2485 ...
2486 Failed example:
2487 if 1:
2488 ...
2489
2490 Note that we see both failures displayed.
2491
2492 >>> old = doctest.set_unittest_reportflags(
2493 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2494
2495 Now, when we run the test:
2496
2497 >>> result = suite.run(unittest.TestResult())
2498 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2499 Traceback ...
2500 Failed example:
2501 favorite_color
2502 Exception raised:
2503 ...
2504 NameError: name 'favorite_color' is not defined
2505 <BLANKLINE>
2506 <BLANKLINE>
2507
2508 We get only the first failure.
2509
2510 If we give any reporting options when we set up the tests,
2511 however:
2512
2513 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2514 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2515
2516 Then the default eporting options are ignored:
2517
2518 >>> result = suite.run(unittest.TestResult())
2519
2520 *NOTE*: These doctest are intentionally not placed in raw string to depict
2521 the trailing whitespace using `\x20` in the diff below.
2522
2523 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2524 Traceback ...
2525 Failed example:
2526 favorite_color
2527 ...
2528 Failed example:
2529 if 1:
2530 print('a')
2531 print()
2532 print('b')
2533 Differences (ndiff with -expected +actual):
2534 a
2535 - <BLANKLINE>
2536 +\x20
2537 b
2538 <BLANKLINE>
2539 <BLANKLINE>
2540
2541
2542 Test runners can restore the formatting flags after they run:
2543
2544 >>> ignored = doctest.set_unittest_reportflags(old)
2545
2546 """
2547
2548 def test_testfile(): r"""
2549 Tests for the `testfile()` function. This function runs all the
2550 doctest examples in a given file. In its simple invocation, it is
2551 called with the name of a file, which is taken to be relative to the
2552 calling module. The return value is (#failures, #tests).
2553
2554 We don't want `-v` in sys.argv for these tests.
2555
2556 >>> save_argv = sys.argv
2557 >>> if '-v' in sys.argv:
2558 ... sys.argv = [arg for arg in save_argv if arg != '-v']
2559
2560
2561 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2562 **********************************************************************
2563 File "...", line 6, in test_doctest.txt
2564 Failed example:
2565 favorite_color
2566 Exception raised:
2567 ...
2568 NameError: name 'favorite_color' is not defined
2569 **********************************************************************
2570 1 items had failures:
2571 1 of 2 in test_doctest.txt
2572 ***Test Failed*** 1 failures.
2573 TestResults(failed=1, attempted=2)
2574 >>> doctest.master = None # Reset master.
2575
2576 (Note: we'll be clearing doctest.master after each call to
2577 `doctest.testfile`, to suppress warnings about multiple tests with the
2578 same name.)
2579
2580 Globals may be specified with the `globs` and `extraglobs` parameters:
2581
2582 >>> globs = {'favorite_color': 'blue'}
2583 >>> doctest.testfile('test_doctest.txt', globs=globs)
2584 TestResults(failed=0, attempted=2)
2585 >>> doctest.master = None # Reset master.
2586
2587 >>> extraglobs = {'favorite_color': 'red'}
2588 >>> doctest.testfile('test_doctest.txt', globs=globs,
2589 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2590 **********************************************************************
2591 File "...", line 6, in test_doctest.txt
2592 Failed example:
2593 favorite_color
2594 Expected:
2595 'blue'
2596 Got:
2597 'red'
2598 **********************************************************************
2599 1 items had failures:
2600 1 of 2 in test_doctest.txt
2601 ***Test Failed*** 1 failures.
2602 TestResults(failed=1, attempted=2)
2603 >>> doctest.master = None # Reset master.
2604
2605 The file may be made relative to a given module or package, using the
2606 optional `module_relative` parameter:
2607
2608 >>> doctest.testfile('test_doctest.txt', globs=globs,
2609 ... module_relative='test')
2610 TestResults(failed=0, attempted=2)
2611 >>> doctest.master = None # Reset master.
2612
2613 Verbosity can be increased with the optional `verbose` parameter:
2614
2615 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2616 Trying:
2617 favorite_color
2618 Expecting:
2619 'blue'
2620 ok
2621 Trying:
2622 if 1:
2623 print('a')
2624 print()
2625 print('b')
2626 Expecting:
2627 a
2628 <BLANKLINE>
2629 b
2630 ok
2631 1 items passed all tests:
2632 2 tests in test_doctest.txt
2633 2 tests in 1 items.
2634 2 passed and 0 failed.
2635 Test passed.
2636 TestResults(failed=0, attempted=2)
2637 >>> doctest.master = None # Reset master.
2638
2639 The name of the test may be specified with the optional `name`
2640 parameter:
2641
2642 >>> doctest.testfile('test_doctest.txt', name='newname')
2643 ... # doctest: +ELLIPSIS
2644 **********************************************************************
2645 File "...", line 6, in newname
2646 ...
2647 TestResults(failed=1, attempted=2)
2648 >>> doctest.master = None # Reset master.
2649
2650 The summary report may be suppressed with the optional `report`
2651 parameter:
2652
2653 >>> doctest.testfile('test_doctest.txt', report=False)
2654 ... # doctest: +ELLIPSIS
2655 **********************************************************************
2656 File "...", line 6, in test_doctest.txt
2657 Failed example:
2658 favorite_color
2659 Exception raised:
2660 ...
2661 NameError: name 'favorite_color' is not defined
2662 TestResults(failed=1, attempted=2)
2663 >>> doctest.master = None # Reset master.
2664
2665 The optional keyword argument `raise_on_error` can be used to raise an
2666 exception on the first error (which may be useful for postmortem
2667 debugging):
2668
2669 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2670 ... # doctest: +ELLIPSIS
2671 Traceback (most recent call last):
2672 doctest.UnexpectedException: ...
2673 >>> doctest.master = None # Reset master.
2674
2675 If the tests contain non-ASCII characters, the tests might fail, since
2676 it's unknown which encoding is used. The encoding can be specified
2677 using the optional keyword argument `encoding`:
2678
2679 >>> doctest.testfile('test_doctest4.txt', encoding='latin-1') # doctest: +ELLIPSIS
2680 **********************************************************************
2681 File "...", line 7, in test_doctest4.txt
2682 Failed example:
2683 '...'
2684 Expected:
2685 'f\xf6\xf6'
2686 Got:
2687 'f\xc3\xb6\xc3\xb6'
2688 **********************************************************************
2689 ...
2690 **********************************************************************
2691 1 items had failures:
2692 2 of 2 in test_doctest4.txt
2693 ***Test Failed*** 2 failures.
2694 TestResults(failed=2, attempted=2)
2695 >>> doctest.master = None # Reset master.
2696
2697 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2698 TestResults(failed=0, attempted=2)
2699 >>> doctest.master = None # Reset master.
2700
2701 Test the verbose output:
2702
2703 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2704 Trying:
2705 'föö'
2706 Expecting:
2707 'f\xf6\xf6'
2708 ok
2709 Trying:
2710 'bąr'
2711 Expecting:
2712 'b\u0105r'
2713 ok
2714 1 items passed all tests:
2715 2 tests in test_doctest4.txt
2716 2 tests in 1 items.
2717 2 passed and 0 failed.
2718 Test passed.
2719 TestResults(failed=0, attempted=2)
2720 >>> doctest.master = None # Reset master.
2721 >>> sys.argv = save_argv
2722 """
2723
2724 class ESC[4;38;5;81mTestImporter(ESC[4;38;5;149mimportlibESC[4;38;5;149m.ESC[4;38;5;149mabcESC[4;38;5;149m.ESC[4;38;5;149mMetaPathFinder, ESC[4;38;5;149mimportlibESC[4;38;5;149m.ESC[4;38;5;149mabcESC[4;38;5;149m.ESC[4;38;5;149mResourceLoader):
2725
2726 def find_spec(self, fullname, path, target=None):
2727 return importlib.util.spec_from_file_location(fullname, path, loader=self)
2728
2729 def get_data(self, path):
2730 with open(path, mode='rb') as f:
2731 return f.read()
2732
2733 class ESC[4;38;5;81mTestHook:
2734
2735 def __init__(self, pathdir):
2736 self.sys_path = sys.path[:]
2737 self.meta_path = sys.meta_path[:]
2738 self.path_hooks = sys.path_hooks[:]
2739 sys.path.append(pathdir)
2740 sys.path_importer_cache.clear()
2741 self.modules_before = sys.modules.copy()
2742 self.importer = TestImporter()
2743 sys.meta_path.append(self.importer)
2744
2745 def remove(self):
2746 sys.path[:] = self.sys_path
2747 sys.meta_path[:] = self.meta_path
2748 sys.path_hooks[:] = self.path_hooks
2749 sys.path_importer_cache.clear()
2750 sys.modules.clear()
2751 sys.modules.update(self.modules_before)
2752
2753
2754 @contextlib.contextmanager
2755 def test_hook(pathdir):
2756 hook = TestHook(pathdir)
2757 try:
2758 yield hook
2759 finally:
2760 hook.remove()
2761
2762
2763 def test_lineendings(): r"""
2764 *nix systems use \n line endings, while Windows systems use \r\n, and
2765 old Mac systems used \r, which Python still recognizes as a line ending. Python
2766 handles this using universal newline mode for reading files. Let's make
2767 sure doctest does so (issue 8473) by creating temporary test files using each
2768 of the three line disciplines. At least one will not match either the universal
2769 newline \n or os.linesep for the platform the test is run on.
2770
2771 Windows line endings first:
2772
2773 >>> import tempfile, os
2774 >>> fn = tempfile.mktemp()
2775 >>> with open(fn, 'wb') as f:
2776 ... f.write(b'Test:\r\n\r\n >>> x = 1 + 1\r\n\r\nDone.\r\n')
2777 35
2778 >>> doctest.testfile(fn, module_relative=False, verbose=False)
2779 TestResults(failed=0, attempted=1)
2780 >>> os.remove(fn)
2781
2782 And now *nix line endings:
2783
2784 >>> fn = tempfile.mktemp()
2785 >>> with open(fn, 'wb') as f:
2786 ... f.write(b'Test:\n\n >>> x = 1 + 1\n\nDone.\n')
2787 30
2788 >>> doctest.testfile(fn, module_relative=False, verbose=False)
2789 TestResults(failed=0, attempted=1)
2790 >>> os.remove(fn)
2791
2792 And finally old Mac line endings:
2793
2794 >>> fn = tempfile.mktemp()
2795 >>> with open(fn, 'wb') as f:
2796 ... f.write(b'Test:\r\r >>> x = 1 + 1\r\rDone.\r')
2797 30
2798 >>> doctest.testfile(fn, module_relative=False, verbose=False)
2799 TestResults(failed=0, attempted=1)
2800 >>> os.remove(fn)
2801
2802 Now we test with a package loader that has a get_data method, since that
2803 bypasses the standard universal newline handling so doctest has to do the
2804 newline conversion itself; let's make sure it does so correctly (issue 1812).
2805 We'll write a file inside the package that has all three kinds of line endings
2806 in it, and use a package hook to install a custom loader; on any platform,
2807 at least one of the line endings will raise a ValueError for inconsistent
2808 whitespace if doctest does not correctly do the newline conversion.
2809
2810 >>> from test.support import os_helper
2811 >>> import shutil
2812 >>> dn = tempfile.mkdtemp()
2813 >>> pkg = os.path.join(dn, "doctest_testpkg")
2814 >>> os.mkdir(pkg)
2815 >>> os_helper.create_empty_file(os.path.join(pkg, "__init__.py"))
2816 >>> fn = os.path.join(pkg, "doctest_testfile.txt")
2817 >>> with open(fn, 'wb') as f:
2818 ... f.write(
2819 ... b'Test:\r\n\r\n'
2820 ... b' >>> x = 1 + 1\r\n\r\n'
2821 ... b'Done.\r\n'
2822 ... b'Test:\n\n'
2823 ... b' >>> x = 1 + 1\n\n'
2824 ... b'Done.\n'
2825 ... b'Test:\r\r'
2826 ... b' >>> x = 1 + 1\r\r'
2827 ... b'Done.\r'
2828 ... )
2829 95
2830 >>> with test_hook(dn):
2831 ... doctest.testfile("doctest_testfile.txt", package="doctest_testpkg", verbose=False)
2832 TestResults(failed=0, attempted=3)
2833 >>> shutil.rmtree(dn)
2834
2835 """
2836
2837 def test_testmod(): r"""
2838 Tests for the testmod function. More might be useful, but for now we're just
2839 testing the case raised by Issue 6195, where trying to doctest a C module would
2840 fail with a UnicodeDecodeError because doctest tried to read the "source" lines
2841 out of the binary module.
2842
2843 >>> import unicodedata
2844 >>> doctest.testmod(unicodedata, verbose=False)
2845 TestResults(failed=0, attempted=0)
2846 """
2847
2848 try:
2849 os.fsencode("foo-bär@baz.py")
2850 supports_unicode = True
2851 except UnicodeEncodeError:
2852 # Skip the test: the filesystem encoding is unable to encode the filename
2853 supports_unicode = False
2854
2855 if supports_unicode:
2856 def test_unicode(): """
2857 Check doctest with a non-ascii filename:
2858
2859 >>> doc = '''
2860 ... >>> raise Exception('clé')
2861 ... '''
2862 ...
2863 >>> parser = doctest.DocTestParser()
2864 >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)
2865 >>> test
2866 <DocTest foo-bär@baz from foo-bär@baz.py:0 (1 example)>
2867 >>> runner = doctest.DocTestRunner(verbose=False)
2868 >>> runner.run(test) # doctest: +ELLIPSIS
2869 **********************************************************************
2870 File "foo-bär@baz.py", line 2, in foo-bär@baz
2871 Failed example:
2872 raise Exception('clé')
2873 Exception raised:
2874 Traceback (most recent call last):
2875 File ...
2876 exec(compile(example.source, filename, "single",
2877 File "<doctest foo-bär@baz[0]>", line 1, in <module>
2878 raise Exception('clé')
2879 Exception: clé
2880 TestResults(failed=1, attempted=1)
2881 """
2882
2883 def test_CLI(): r"""
2884 The doctest module can be used to run doctests against an arbitrary file.
2885 These tests test this CLI functionality.
2886
2887 We'll use the support module's script_helpers for this, and write a test files
2888 to a temp dir to run the command against. Due to a current limitation in
2889 script_helpers, though, we need a little utility function to turn the returned
2890 output into something we can doctest against:
2891
2892 >>> def normalize(s):
2893 ... return '\n'.join(s.decode().splitlines())
2894
2895 With those preliminaries out of the way, we'll start with a file with two
2896 simple tests and no errors. We'll run both the unadorned doctest command, and
2897 the verbose version, and then check the output:
2898
2899 >>> from test.support import script_helper
2900 >>> from test.support.os_helper import temp_dir
2901 >>> with temp_dir() as tmpdir:
2902 ... fn = os.path.join(tmpdir, 'myfile.doc')
2903 ... with open(fn, 'w', encoding='utf-8') as f:
2904 ... _ = f.write('This is a very simple test file.\n')
2905 ... _ = f.write(' >>> 1 + 1\n')
2906 ... _ = f.write(' 2\n')
2907 ... _ = f.write(' >>> "a"\n')
2908 ... _ = f.write(" 'a'\n")
2909 ... _ = f.write('\n')
2910 ... _ = f.write('And that is it.\n')
2911 ... rc1, out1, err1 = script_helper.assert_python_ok(
2912 ... '-m', 'doctest', fn)
2913 ... rc2, out2, err2 = script_helper.assert_python_ok(
2914 ... '-m', 'doctest', '-v', fn)
2915
2916 With no arguments and passing tests, we should get no output:
2917
2918 >>> rc1, out1, err1
2919 (0, b'', b'')
2920
2921 With the verbose flag, we should see the test output, but no error output:
2922
2923 >>> rc2, err2
2924 (0, b'')
2925 >>> print(normalize(out2))
2926 Trying:
2927 1 + 1
2928 Expecting:
2929 2
2930 ok
2931 Trying:
2932 "a"
2933 Expecting:
2934 'a'
2935 ok
2936 1 items passed all tests:
2937 2 tests in myfile.doc
2938 2 tests in 1 items.
2939 2 passed and 0 failed.
2940 Test passed.
2941
2942 Now we'll write a couple files, one with three tests, the other a python module
2943 with two tests, both of the files having "errors" in the tests that can be made
2944 non-errors by applying the appropriate doctest options to the run (ELLIPSIS in
2945 the first file, NORMALIZE_WHITESPACE in the second). This combination will
2946 allow thoroughly testing the -f and -o flags, as well as the doctest command's
2947 ability to process more than one file on the command line and, since the second
2948 file ends in '.py', its handling of python module files (as opposed to straight
2949 text files).
2950
2951 >>> from test.support import script_helper
2952 >>> from test.support.os_helper import temp_dir
2953 >>> with temp_dir() as tmpdir:
2954 ... fn = os.path.join(tmpdir, 'myfile.doc')
2955 ... with open(fn, 'w', encoding="utf-8") as f:
2956 ... _ = f.write('This is another simple test file.\n')
2957 ... _ = f.write(' >>> 1 + 1\n')
2958 ... _ = f.write(' 2\n')
2959 ... _ = f.write(' >>> "abcdef"\n')
2960 ... _ = f.write(" 'a...f'\n")
2961 ... _ = f.write(' >>> "ajkml"\n')
2962 ... _ = f.write(" 'a...l'\n")
2963 ... _ = f.write('\n')
2964 ... _ = f.write('And that is it.\n')
2965 ... fn2 = os.path.join(tmpdir, 'myfile2.py')
2966 ... with open(fn2, 'w', encoding='utf-8') as f:
2967 ... _ = f.write('def test_func():\n')
2968 ... _ = f.write(' \"\"\"\n')
2969 ... _ = f.write(' This is simple python test function.\n')
2970 ... _ = f.write(' >>> 1 + 1\n')
2971 ... _ = f.write(' 2\n')
2972 ... _ = f.write(' >>> "abc def"\n')
2973 ... _ = f.write(" 'abc def'\n")
2974 ... _ = f.write("\n")
2975 ... _ = f.write(' \"\"\"\n')
2976 ... rc1, out1, err1 = script_helper.assert_python_failure(
2977 ... '-m', 'doctest', fn, fn2)
2978 ... rc2, out2, err2 = script_helper.assert_python_ok(
2979 ... '-m', 'doctest', '-o', 'ELLIPSIS', fn)
2980 ... rc3, out3, err3 = script_helper.assert_python_ok(
2981 ... '-m', 'doctest', '-o', 'ELLIPSIS',
2982 ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
2983 ... rc4, out4, err4 = script_helper.assert_python_failure(
2984 ... '-m', 'doctest', '-f', fn, fn2)
2985 ... rc5, out5, err5 = script_helper.assert_python_ok(
2986 ... '-m', 'doctest', '-v', '-o', 'ELLIPSIS',
2987 ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
2988
2989 Our first test run will show the errors from the first file (doctest stops if a
2990 file has errors). Note that doctest test-run error output appears on stdout,
2991 not stderr:
2992
2993 >>> rc1, err1
2994 (1, b'')
2995 >>> print(normalize(out1)) # doctest: +ELLIPSIS
2996 **********************************************************************
2997 File "...myfile.doc", line 4, in myfile.doc
2998 Failed example:
2999 "abcdef"
3000 Expected:
3001 'a...f'
3002 Got:
3003 'abcdef'
3004 **********************************************************************
3005 File "...myfile.doc", line 6, in myfile.doc
3006 Failed example:
3007 "ajkml"
3008 Expected:
3009 'a...l'
3010 Got:
3011 'ajkml'
3012 **********************************************************************
3013 1 items had failures:
3014 2 of 3 in myfile.doc
3015 ***Test Failed*** 2 failures.
3016
3017 With -o ELLIPSIS specified, the second run, against just the first file, should
3018 produce no errors, and with -o NORMALIZE_WHITESPACE also specified, neither
3019 should the third, which ran against both files:
3020
3021 >>> rc2, out2, err2
3022 (0, b'', b'')
3023 >>> rc3, out3, err3
3024 (0, b'', b'')
3025
3026 The fourth run uses FAIL_FAST, so we should see only one error:
3027
3028 >>> rc4, err4
3029 (1, b'')
3030 >>> print(normalize(out4)) # doctest: +ELLIPSIS
3031 **********************************************************************
3032 File "...myfile.doc", line 4, in myfile.doc
3033 Failed example:
3034 "abcdef"
3035 Expected:
3036 'a...f'
3037 Got:
3038 'abcdef'
3039 **********************************************************************
3040 1 items had failures:
3041 1 of 2 in myfile.doc
3042 ***Test Failed*** 1 failures.
3043
3044 The fifth test uses verbose with the two options, so we should get verbose
3045 success output for the tests in both files:
3046
3047 >>> rc5, err5
3048 (0, b'')
3049 >>> print(normalize(out5))
3050 Trying:
3051 1 + 1
3052 Expecting:
3053 2
3054 ok
3055 Trying:
3056 "abcdef"
3057 Expecting:
3058 'a...f'
3059 ok
3060 Trying:
3061 "ajkml"
3062 Expecting:
3063 'a...l'
3064 ok
3065 1 items passed all tests:
3066 3 tests in myfile.doc
3067 3 tests in 1 items.
3068 3 passed and 0 failed.
3069 Test passed.
3070 Trying:
3071 1 + 1
3072 Expecting:
3073 2
3074 ok
3075 Trying:
3076 "abc def"
3077 Expecting:
3078 'abc def'
3079 ok
3080 1 items had no tests:
3081 myfile2
3082 1 items passed all tests:
3083 2 tests in myfile2.test_func
3084 2 tests in 2 items.
3085 2 passed and 0 failed.
3086 Test passed.
3087
3088 We should also check some typical error cases.
3089
3090 Invalid file name:
3091
3092 >>> rc, out, err = script_helper.assert_python_failure(
3093 ... '-m', 'doctest', 'nosuchfile')
3094 >>> rc, out
3095 (1, b'')
3096 >>> # The exact error message changes depending on the platform.
3097 >>> print(normalize(err)) # doctest: +ELLIPSIS
3098 Traceback (most recent call last):
3099 ...
3100 FileNotFoundError: [Errno ...] ...nosuchfile...
3101
3102 Invalid doctest option:
3103
3104 >>> rc, out, err = script_helper.assert_python_failure(
3105 ... '-m', 'doctest', '-o', 'nosuchoption')
3106 >>> rc, out
3107 (2, b'')
3108 >>> print(normalize(err)) # doctest: +ELLIPSIS
3109 usage...invalid...nosuchoption...
3110
3111 """
3112
3113 def test_no_trailing_whitespace_stripping():
3114 r"""
3115 The fancy reports had a bug for a long time where any trailing whitespace on
3116 the reported diff lines was stripped, making it impossible to see the
3117 differences in line reported as different that differed only in the amount of
3118 trailing whitespace. The whitespace still isn't particularly visible unless
3119 you use NDIFF, but at least it is now there to be found.
3120
3121 *NOTE*: This snippet was intentionally put inside a raw string to get rid of
3122 leading whitespace error in executing the example below
3123
3124 >>> def f(x):
3125 ... r'''
3126 ... >>> print('\n'.join(['a ', 'b']))
3127 ... a
3128 ... b
3129 ... '''
3130 """
3131 """
3132 *NOTE*: These doctest are not placed in raw string to depict the trailing whitespace
3133 using `\x20`
3134
3135 >>> test = doctest.DocTestFinder().find(f)[0]
3136 >>> flags = doctest.REPORT_NDIFF
3137 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
3138 ... # doctest: +ELLIPSIS
3139 **********************************************************************
3140 File ..., line 3, in f
3141 Failed example:
3142 print('\n'.join(['a ', 'b']))
3143 Differences (ndiff with -expected +actual):
3144 - a
3145 + a
3146 b
3147 TestResults(failed=1, attempted=1)
3148
3149 *NOTE*: `\x20` is for checking the trailing whitespace on the +a line above.
3150 We cannot use actual spaces there, as a commit hook prevents from committing
3151 patches that contain trailing whitespace. More info on Issue 24746.
3152 """
3153
3154
3155 def test_run_doctestsuite_multiple_times():
3156 """
3157 It was not possible to run the same DocTestSuite multiple times
3158 http://bugs.python.org/issue2604
3159 http://bugs.python.org/issue9736
3160
3161 >>> import unittest
3162 >>> import test.sample_doctest
3163 >>> suite = doctest.DocTestSuite(test.sample_doctest)
3164 >>> suite.run(unittest.TestResult())
3165 <unittest.result.TestResult run=9 errors=0 failures=4>
3166 >>> suite.run(unittest.TestResult())
3167 <unittest.result.TestResult run=9 errors=0 failures=4>
3168 """
3169
3170
3171 def load_tests(loader, tests, pattern):
3172 tests.addTest(doctest.DocTestSuite(doctest))
3173 tests.addTest(doctest.DocTestSuite())
3174 return tests
3175
3176
3177 def test_coverage(coverdir):
3178 trace = import_helper.import_module('trace')
3179 tracer = trace.Trace(ignoredirs=[sys.base_prefix, sys.base_exec_prefix,],
3180 trace=0, count=1)
3181 tracer.run('test_main()')
3182 r = tracer.results()
3183 print('Writing coverage results...')
3184 r.write_results(show_missing=True, summary=True,
3185 coverdir=coverdir)
3186
3187
3188 if __name__ == '__main__':
3189 if '-c' in sys.argv:
3190 test_coverage('/tmp/doctest.cover')
3191 else:
3192 unittest.main()
Browse
Usage
Versions