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